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

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

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

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

先决条件

• Azure AI 搜索服务。 我们建议使用系统分配的托管标识和角色分配，使 Azure AI 搜索能够写入 Azure 存储，并调用技能组中使用的 Azure AI 资源。

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

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

• 对于角色分配，搜索服务标识必须：

  • 对技能组使用的 Azure AI 多服务帐户拥有“认知服务用户”权限。

  • 对 Azure 存储拥有“存储 Blob 数据参与者”权限。 否则，请计划使用完全访问连接字符串来进行与 Azure 存储的调试会话连接。

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

限制

调试会话适用于所有正式发布的索引器数据源

• 具有 Azure Cosmos DB for MongoDB 索引器。

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

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

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

• 目前还无法选择要调试的文档。 从限制并非永久性的，很快就会取消。 此时，调试会话会选择源数据容器或文件夹中的第一个文档。

创建调试会话

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

2. 在左侧菜单中，选择“搜索管理”>“调试会话”。

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

   

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

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

6. 在“存储帐户”中，找到一个常规用途存储帐户用于缓存调试会话。

7. 如果你先前为搜索服务系统托管标识分配了“存储 Blob 数据参与者”权限，请选择“使用托管标识进行身份验证”。

8. 选择“保存”。

   • Azure AI 搜索将在 Azure 存储中创建一个名为 ms-az-cognitive-search-debugsession 的 Blob 容器。
   • 在该容器中，Azure AI 搜索将使用你提供的会话名称创建一个文件夹。
   • Azure AI 搜索启动调试会话。

9. 将向设置页面开放调试会话。 可以修改初始配置并替代任何默认值。

10. 在“存储连接字符串”中，可以指定连接字符串或更改存储帐户。

11. （可选）在“索引器设置”中，指定用于创建会话的任何索引器执行设置。 这些设置应与实际索引器使用的设置相同。 在调试会话中指定的任何索引器选项都不会影响索引器本身。

12. 如果你进行了更改，请依次选择“保存会话”、“运行”。

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

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

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

开始时出现错误和警告

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

请记住，调试会话基于整个索引中的一个文档。 如果输入或输出看起来不正确，那么问题可能出在该文档上。 可以选择另一个文档来确认错误和警告是普遍性的，还是与单个文档有关。

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

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

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

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

3. 返回到“错误”或“警告”，查看计数是否已减少。

查看扩充或生成的内容

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

技能组创建或使用的所有内容将显示在表达式计算器中。 可以将鼠标悬停在链接上，以查看扩充文档树中的每个输入或输出值。 若要查看每个技能的输入或输出，请执行以下步骤：

1. 在调试会话中，展开蓝色箭头以查看区分上下文的详细信息。 默认情况下，详细信息是扩充文档数据结构。 但是，如果你选择技能或映射，则详细信息将与该对象有关。

   

2. 选择一个技能。

   

3. 单击相应的链接进一步深入查看技能处理。 例如，以下屏幕截图显示了“文本拆分”技能首次迭代后的输出。

   

检查索引映射

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

选择一个映射选项，并展开详细信息视图以查看源和目标定义。

• 投影映射位于提供集成矢量化的技能组（例如导入和矢量化数据向导创建的技能）中。 这些映射确定了父子（区块）字段映射，以及是否仅为分块内容创建辅助索引

• 输出字段映射位于索引器中，在技能组调用内置或自定义技能时使用。 这些映射用于设置从扩充树中的节点到搜索索引中的字段的数据路径。 有关路径的详细信息，请参阅扩充节点路径语法。

• 字段映射位于索引器定义中，它们从数据源中的原始内容和索引中的字段建立数据路径。 你还可以使用字段映射来添加编码和解码步骤。

此示例显示了投影映射的详细信息。 可以编辑 JSON 来修复任何映射问题。

编辑技能定义

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

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

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

1. 在工作面上选择一个技能。 右侧将打开“技能详细信息”窗格。

2. 使用“技能设置”编辑技能定义。 可以直接编辑 JSON。

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

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

在本地调试自定义技能

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

获取公共 URL

本部分将介绍用于获取自定义技能的公共 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 门户中配置

获取自定义技能的公共 URL 后，在调试会话中修改自定义 Web API 技能 URI，以调用 Tunnelmole 或 ngrok 转发 URL。 使用 Azure Function 执行技能组代码时，请务必追加“/api/FunctionName”。

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

测试代码

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

后续步骤

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