你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Azure 门户中调试 Azure AI 搜索技能组

启动基于门户的调试会话以识别和解决错误、验证更改，并将更改推送到 Azure AI 搜索服务中已发布的技能组。

调试会话是缓存的索引器和技能组执行（范围为单个文档），可使用它通过交互方式编辑和测试更改。 调试完成后，可以将更改保存到技能组中。

有关调试会话如何工作的背景信息，请参阅 Azure AI 搜索中的调试会话。 若要使用示例文档练习调试工作流，请参阅教程：调试会话。

先决条件

• 现有的扩充管道，包括数据源、技能组、索引器和索引。

• 搜索服务中的“参与者”角色分配。

• Azure 存储帐户，用于保存会话状态。

• Azure 存储中的“存储 Blob 数据参与者”角色分配（如果使用的是系统托管标识）。 否则，请计划使用完全访问连接字符串来进行与 Azure 存储的调试会话连接。

• 如果 Azure 存储帐户位于防火墙后面，请将其配置为允许搜索服务访问。

限制

调试会话适用于所有正式发布的索引器数据源和大多数预览版数据源。 以下列表说明了例外情况：

• 当前不支持 Azure Cosmos DB for MongoDB。

• 对于 Azure Cosmos DB for NoSQL，如果某个行在索引期间失败并且没有相应的元数据，则调试会话可能不会选择正确的行。

• 对于 Azure Cosmos DB 的 SQL API，如果分区集合以前未分区，则调试会话将找不到该文档。

• 对于自定义技能，与 Azure 存储的调试会话连接不支持用户分配的托管标识。 如先决条件中所述，可以使用系统托管标识，或指定包含密钥的完全访问连接字符串。 有关详细信息，请参阅使用托管标识将搜索服务连接到其他 Azure 资源。

门户不支持客户管理的密钥加密 (CMK)，这意味着门户体验（如调试会话）不能具有 CMK 加密的连接字符串或其他加密元数据。 如果搜索服务配置为强制实施 CMK，则调试会话将不起作用。

创建调试会话

1. 登录 Azure 门户并查找搜索服务。

2. 在左侧导航页中，选择“调试会话”。

3. 在顶部的操作栏中，选择“添加调试会话”。

   

4. 在“调试会话名称”中提供一个名称，该名称可帮助你记住调试会话所针对的技能组、索引器和数据源。

5. 在“存储连接”中，查找一个常规用途存储帐户，用于缓存调试会话。 系统将提示你进行选择，并视需要在 Blob 存储或 Azure Data Lake Storage Gen2 中创建 Blob 容器。 对于所有后续新创建的调试会话，可以重复使用相同的容器。 容器名称采用“认知-搜索-调试-会话”格式可能比较好。

6. 在“托管标识身份验证”中，如果与 Azure 存储的连接不使用托管标识，请选择“无”。 否则，请选择已向其授予“存储 Blob 数据参与者”权限的托管标识。

7. 在“索引器模板”中，选择驱动所需调试的技能组的索引器。 索引器和技能组的副本都用于初始化会话。

8. 在“待调试文档”中，选择索引中的第一个文档或选择特定文档。 如果选择了特定文档，根据数据源的不同，系统会要求提供 URI 或行 ID。

   如果特定文档是 blob，请提供 blob URI。 可以在门户的 blo b属性页中找到 URI。

   

9. 或者，在“索引器设置”中，指定用于创建会话的任何索引器执行设置。 此设置应模拟实际索引器所用的设置。 在调试会话中指定的任何索引器选项都不会影响索引器本身。

10. 你的配置应与下方屏幕截图上的配置类似。 选择“保存会话”以开始操作。

    

调试会话首先对选定的文档执行索引器和技能组。 文档的内容和元数据将在会话中可见并且可用。

使用“取消”按钮执行调试会话时，可以取消调试会话。 如果点击“取消”按钮，则应该能够分析部分结果。

调试会话的执行时间应比索引器更长，因为它要经过额外的处理。

开始时出现错误和警告

门户中的索引器执行历史记录可为所有文档提供完整的错误和警告列表。 在调试会话中，错误和警告将限制为一个文档。 请浏览此列表，做出更改，然后返回该列表以确认问题是否已解决。

若要查看这些消息，请在“AI 扩充”>“技能图”中选择一个技能，然后在详细信息窗格中选择“错误/警告”。

最佳做法是先解决输入问题，然后继续解决输出问题。

若要证明修改是否解决了错误，请执行以下步骤：

1. 在“技能详细信息”窗格中选择“保存”以保存更改。

2. 在会话窗口中选择“运行”，使用修改后的定义调用技能组执行。

3. 返回“错误/警告”，查看计数是否减少。 在打开该选项卡之前，列表不会刷新。

查看扩充节点的内容

AI 扩充管道从源文档中提取或推导信息和结构，并在此过程中创建一个扩充文档。 首先在文档破解期间创建扩充文档，其中填充了根节点 (/document)，以及直接从数据源（例如元数据和文档键）提取的任何内容的节点。 在技能执行期间，技能会创建更多节点，其中每个技能输出会添加一个新节点到扩充树中。

扩充文档供内部使用，但调试会话使你能够访问技能执行期间生成的内容。 若要查看每个技能的内容或输出，请执行以下步骤：

1. 从默认视图开始：“AI 扩充”>“技能图”，并且图类型设置为“依赖项关系图”。

2. 选择一个技能。

3. 在右侧的详细信息窗格中，选择“执行”，选择一个输出，然后打开表达式计算器 (</>) 查看表达式及其结果。

   

4. 或者，打开“AI 扩充”>“扩充的数据结构”以向下滚动浏览节点列表。 该列表包含潜在节点和实际节点，其中有一列显示了输出，另一列指示了用于生成输出的上游对象。

   

编辑技能定义

如果字段映射正确，请检查各个技能的配置和内容。 如果某个技能未能产生输出，则它可能缺少属性或参数，可以通过错误和验证消息进行确定。

其他问题（例如无效的上下文或输入表达式）可能会更难解决，因为错误会告诉你哪些内容是错误的，但不会告诉你如何修复它。 如需上下文和输入语法方面的帮助，请参阅在 Azure AI 搜索技能组中引用扩充。 有关各个消息的帮助信息，请参阅排查常见索引器错误和警告。

以下步骤说明了如何获取有关技能的信息。

1. 在“AI 扩充”>“技能图”中选择一项技能。 右侧将打开“技能详细信息”窗格。

2. 使用以下任一方法编辑技能定义：

   • “技能设置”（如果偏好可视化编辑器）
   • “技能 JSON 编辑器”，用于直接编辑 JSON 文档

3. 检查扩充树中用于引用节点的路径语法。 下面是一些最常见的输入路径：

   • /document/content 用于文本块。 此节点从 Blob 内容属性中填充。
   • /document/merged_content 用于技能组中包含文本合并技能的文本块。
   • /document/normalized_images/* 用于从图像中识别或推断的文本。

检查字段映射

如果技能产生输出，但搜索索引为空，请检查字段映射。 字段映射指定了如何从管道移出内容及如何将其加入搜索索引。

1. 从默认视图开始：“AI 扩充”>“技能图”，并且图类型设置为“依赖项关系图”。

2. 选择顶部附近的“字段映射”。 至少应该找到用于唯一标识搜索索引中每个搜索文档并将其与数据源中的源文档相关联的文档键。

   如果直接从数据源导入原始内容并绕过扩充，则应在“字段映射”中找到这些字段。

3. 选择图形底部的“输出字段映射”。 在此处可以找到从技能输出到搜索索引中目标字段的映射。 除非使用的是“导入数据向导”，否则，将手动定义输出字段映射，并且这些映射可能不完整或输入错误。

   确认“输出字段映射”中的字段是否根据指定存在于搜索索引中，并检查拼写和扩充节点路径语法。

   

在本地调试自定义技能

自定义技能对调试更具挑战性，因为代码在外部运行，所以调试会话不能用于调试它们。 本部分介绍如何在本地调试自定义 Web API 技能、调试会话、Visual Studio Code 和 ngrok 或 Tunnelmole。 此方法适用于在 Azure Functions 或是本地运行的任何其他 Web 框架（例如 FastAPI）中执行的自定义技能。

获取公共 URL

使用 Tunnelmole

Tunnelmole 是一种开源隧道工具，可以创建一个公共 URL，通过隧道将请求转发到本地计算机。

1. 安装 Tunnelmole：

   • npm：npm install -g tunnelmole
   • Linux：curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac：curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows：使用 npm 进行安装。 或者，如果没有安装 NodeJS，请下载适用于 Windows 的预编译 .exe 文件，并将其放在 PATH 中的某个位置。

2. 运行此命令以创建新隧道：

   tmole 7071
   

   应该会看到如下所示的响应：

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   在前面的示例中，https://m5hdpb-ip-49-183-170-144.tunnelmole.net 转发到本地计算机上的端口 7071，这是公开 Azure 函数的默认端口。

使用 ngrok

ngrok 是一种常用的闭源跨平台应用程序，可以创建隧道或转发 URL，以便 Internet 请求到达本地计算机。 使用 ngrok 将轻松从搜索服务中的扩充管道转发到计算机，以允许进行本地调试。

1. 安装 ngrok。

2. 打开终端，并转到包含 ngrok 可执行文件的文件夹。

3. 使用以下命令运行 ngrok 以创建新隧道：

   ngrok http 7071 
   

   注意

   默认情况下，Azure Functions 会在 7071 上公开。 其他工具和配置可能需要提供其他端口。

4. 启动 ngrok 后，复制并保存公共转发 URL 以供下一步使用。 随机生成转发 URL。

   

在 Azure 门户中配置

在调试会话中，修改自定义 Web API 技能 URI 以调用 Tunnelmole 或 ngrok 转发 URL。 确保在使用 Azure Function 执行技能组代码时追加“/api/FunctionName”。

可以在门户中编辑技能定义。

测试代码

此时，来自调试会话的新请求现在应发送到本地 Azure 函数。 可以在 Visual Studio Code 中使用断点来调试代码或逐步运行代码。

后续步骤

现在，你已了解“调试会话”视觉对象编辑器的布局和功能，请尝试学习教程以获得实际体验。

教程：浏览调试会话