在 Azure portal 中调试Azure AI Search技能集

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

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

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

先决条件

Azure AI Search service、任何区域或层。
用于保存会话状态的Azure Storage帐户。
现有的扩充管道，包括数据源、技能组、索引器和索引。

限制

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

Azure Cosmos DB for MongoDB 索引器。
对于 Azure Cosmos DB for NoSQL，如果在索引期间一行失败，并且没有相应的元数据，调试会话可能无法识别正确的行。
对于 Azure Cosmos DB 的 NoSQL API，如果分区集合以前未分区，则调试会话将找不到文档。
对于自定义技能，用户分配的托管标识在调试会话中不支持连接至 Azure Storage。如先决条件中所述，您可以使用系统托管标识，或指定包含密钥的完整访问连接字符串。有关详细信息，请参阅使用托管标识将搜索服务连接到其他 Azure 资源。

安全和权限

若要将调试会话保存到 Azure Storage，搜索服务身份必须具有对 Azure Storage 的 Storage Blob 数据贡献者权限。否则，请计划为 Azure Storage 的调试会话连接选择一个完全访问连接字符串。
如果Azure Storage帐户位于防火墙后面，请将其配置为 allow search service access。

创建调试会话

登录到 Azure portal，并查找您的搜索服务。
在左侧菜单中，选择“搜索管理”“调试会话”。>
在顶部的操作栏中，选择“添加调试会话”。
在“调试会话名称”中提供一个名称，该名称可帮助你记住调试会话所针对的技能组、索引器和数据源。
在“索引器模板”中，选择驱动所需调试的技能组的索引器。索引器和技能集的副本都用于初始化会话。
在“待调试文档”中，选择索引中的第一个文档或选择特定文档。如果选择了特定文档，根据数据源的不同，系统会要求提供 URI 或行 ID。

对于 Blob 存储中的特定文档，请提供 Blob URI。可以在Azure portal的 blob 属性页中找到 URI。

对于 Azure Cosmos DB 中的 NoSQL 特定文档：在搜索索引中为值提供文档键，并在 Cosmos DB 中为分区键提供实体的 ID。

下面是 Cosmos DB 示例的调试会话配置。
在 Storage 帐户中，选择用于缓存调试会话的常规用途storage帐户。
如果您之前为搜索服务的系统托管标识分配了Storage Blob Data Contributor权限，请选择使用托管身份进行身份验证。如果未选中此框，搜索服务将使用完整的访问连接字符串进行连接。
选择“保存”。
- Azure AI Search在名为 ms-az-cognitive-search-debugsession 的Azure Storage上创建 blob 容器。
- 在该容器中，它将使用你提供的会话名称创建一个文件夹。
- 启动调试会话。

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

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

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

以错误和警告为起点

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

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

选择“错误”或“警告”查看问题列表。

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

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

在“技能详细信息”窗格中选择“保存”以保存更改。
在会话窗口中选择运行，以使用修改后的定义调用技能集执行。
返回到“错误”或“警告”，查看计数是否已减少。

查看扩充或生成的内容

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

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

在调试会话中，展开蓝色箭头以查看与上下文相关的详细信息。默认情况下，详细信息是扩充文档数据结构。但是，如果选择了某个技能或映射，详细信息将与该对象相关。
选择一个技能。
请按照链接进一步深入了解技能处理流程。例如，以下屏幕截图显示了“文本拆分”技能首次迭代后的输出。

检查索引映射

如果技能产生输出，但搜索索引为空，请检查字段映射。字段映射指定了内容如何从管道中导出并进入搜索索引。

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

投影映射 位于提供集成矢量化的技能组合中，例如由 导入数据（新） 向导创建的技能。这些映射确定了父子（区块）字段映射，并决定是否仅为分块内容创建次级索引。
输出字段映射位于索引器中，在技能组调用内置或自定义技能时使用。这些映射用于设置从扩充树中的节点到搜索索引中的字段的数据路径。有关路径的详细信息，请参阅扩充节点路径语法。
字段映射位于索引器定义中，它们从数据源中的原始内容和索引中的字段建立数据路径。你还可以使用字段映射来添加编码和解码步骤。

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

编辑技能定义

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

其他问题（例如无效的上下文或输入表达式）可能会更难解决，因为错误会告诉你哪些内容是错误的，但不会告诉你如何修复它。要获取有关上下文和输入语法的帮助，请参阅 Azure AI Search 技能集中的 Reference 增强。 ** 如需获取有关单个消息的帮助，请参阅常见索引器错误和警告的排查。

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

选择工作界面的一个技能。右侧将打开“技能详细信息”窗格。
使用“技能设置”编辑技能定义。可以直接编辑 JSON。
检查扩充树中用于引用节点的路径语法。下面是一些最常见的输入路径：
- /document/content 适用于文本块。此节点从 Blob 内容属性中填充。
- /document/merged_content 用于包含文本合并技能的模块中的文本块。
- /document/normalized_images/* 用于从图像中识别或推断的文本。

在本地调试自定义技能

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

获取公共 URL

本部分将介绍用于获取自定义技能的公共 URL 的两种方法。

使用 Tunnelmole

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

安装 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 进行安装。或者，如果没有安装 Node.js，请下载适用于 Windows 的预编译 .exe 文件，并将其放在 PATH 中的某个位置。
运行此命令以创建新隧道：
```
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 functions的默认端口。

使用 ngrok

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

安装 ngrok。
打开终端，并转到包含 ngrok 可执行文件的文件夹。
使用以下命令运行 ngrok 以创建新隧道：
```
ngrok http 7071 
```
注意事项

默认情况下，Azure 函数通过端口 7071 公开。其他工具和配置可能需要提供其他端口。
启动 ngrok 后，复制并保存公共转发 URL 以供下一步使用。随机生成转发 URL。

在 Azure portal 中配置

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

可以在“技能详细信息”窗格的“技能设置”部分编辑技能定义。

测试代码

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

后续步骤

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

教程：浏览调试会话

Last updated on 2026-03-16

Compartilhar via