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

教程：使用调试会话修复技能组

在 Azure AI 搜索中，技能组可协调分析、转换或创建可搜索内容的技能的操作。 通常，一个技能的输出会变成另一个技能的输入。 当输入依赖于输出时，如果技能组定义和字段关联出现错误，可能会导致操作和数据丢失。

调试会话是一种 Azure 门户工具，提供在 Azure AI 搜索上执行的技能组的整体可视化效果。 借助此工具，可深入了解特定步骤，以轻松查看操作可能会在哪里失败。

在本文中，请使用“调试会话”来查找并修复缺少输入和输出的问题。 本教程将包含所有这些方面。 它提供示例数据、用于创建对象的 REST 文件，以及用于调试技能组中的问题的说明。

如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

先决条件

• Azure AI 搜索。 创建服务或在当前订阅下查找现有服务。 可在本教程中使用免费服务。 免费层不提供 Azure AI 搜索服务的托管标识支持。 必须使用密钥连接到 Azure 存储。

• 具有 Blob 存储的 Azure 存储帐户，用于承载示例数据以及保存在调试会话期间创建的缓存数据。 如果使用免费搜索服务，则存储帐户必须已启用共享访问密钥，并且必须允许公用网络访问。

• 包含 REST 客户端的 Visual Studio Code。

• 示例 PDF（临床试验）。

• 用于创建扩充管道的示例 debug-sessions.rest 文件。

注意

本教程还使用 Azure AI 服务进行语言检测、实体识别和关键短语提取。 由于工作负载很小，因此在后台使用 Azure AI 服务来免费处理事务（最多 20 个事务）。 这意味着，无需创建可计费的 Azure AI 服务资源即可完成此练习。

设置示例数据

本部分在 Azure Blob 存储中创建示例数据集，让索引器和技能组有内容可使用。

1. 下载包含 19 个文件的示例数据 (clinical-trials-pdf-19)。

2. 创建 Azure 存储帐户或查找现有帐户。

   • 选择 Azure AI 搜索所在的同一区域，以避免带宽费用。

   • 选择 StorageV2（常规用途 V2）帐户类型。

3. 导航到门户中的 Azure 存储服务页，创建一个 Blob 容器。 最佳做法是将访问级别指定为“专用”。 将容器命名为 clinicaltrialdataset。

4. 在容器中，选择“上传”以上传在第一个步骤中下载并解压缩的示例文件。

5. 在门户中，复制 Azure 存储的连接字符串。 可以从 Azure 门户的“设置”>“访问密钥”获取连接字符串 。

复制密钥和 URL

本教程使用 API 密钥进行身份验证和授权。 需要搜索服务终结点和 API 密钥，可以从 Azure 门户获取该密钥。

1. 登录到 Azure 门户，导航到概述页，并复制 URL。 示例终结点可能类似于 https://mydemo.search.windows.net。

2. 在“设置”>“密钥”下，复制管理密钥。 管理密钥用于添加、修改和删除对象。 有两个可互换的管理密钥。 复制其中任意一个。

   

具有有效的 API 密钥可以在发送请求的应用程序与处理请求的搜索服务之间建立信任关系，这种信任关系以每个请求为基础。

创建数据源、技能组、索引和索引器

在本部分，请创建一个可以在本教程中修复的“有缺陷”工作流。

1. 启动 Visual Studio Code 并打开 debug-sessions.rest 文件。

2. 提供以下变量：搜索服务 URL、搜索服务管理 API 密钥、存储连接字符串以及存储 PDF 的 Blob 容器的名称。

3. 依次发送每个请求。 创建索引器需要几分钟才能完成。

4. 关闭 文件。

在门户中检查结果

由于技能组执行过程中发生了问题，示例代码特意创建了错误索引。 问题是索引缺少数据。

1. 在 Azure 门户的搜索服务“概述”页上，选择“索引”选项卡 。

2. 选择“clinical-trials”。

3. 在搜索资源管理器的 JSON 视图中输入此 JSON 查询字符串。 它返回特定文档的字段（由唯一的 metadata_storage_path 字段标识）。

   "search": "*",
   "select": "metadata_storage_path, organizations, locations",
   "count": true
   

4. 运行查询。 你应会看到 organizations 和 locations 的空值。

   这些字段应已通过技能组的实体识别技能进行了填充，此技能用于检测 blob 内容中任何位置的 organizations 和 locations。 在下一练习中，你将调试技能组来确定发生了什么问题。

还可通过 Azure 门户调查错误和警告。

1. 打开“索引器”选项卡，然后选择“clinical-trials-idxr”。

   请注意，虽然索引器作业总体上讲已成功完成，但有警告。

2. 选择“成功”以查看警告（如果大部分都是错误，详细信息链接会显示“失败”）。 你将看到索引器发出的每个警告都有一长串列表。

   

启动调试会话

1. 在搜索服务左侧导航窗格中的“搜索管理”下，选择“调试会话”。

2. 选择“+ 添加调试会话”。

3. 为会话命名。

4. 在索引器模板中，提供索引器名称。 索引器具有对数据源、技能组和索引的引用。

5. 选择“存储帐户”。

6. 保存会话。

   

7. 调试会话将在设置页面上打开。 可以修改初始配置并替代任何默认值。 调试会话仅适用于单个文档。 默认操作是接受集合中的第一个文档作为调试会话的基础。 可以通过在 Azure 存储中提供特定文档的 URI 来选择要调试的文档。

8. 调试会话完成初始化后，应该会看到具有映射和搜索索引的技能工作流。 扩充的文档数据结构显示在侧边的详细信息窗格中。 下面的屏幕截图未显示它，以便你可看到更多的工作流。

   

查找技能组问题

索引器报告的任何问题都指示为“错误”和“警告”。

请注意，错误和警告的数量比之前显示的数量要小得多，因为此列表仅详细说明单个文档的错误。 和索引器显示的列表一样，你可以选择警告消息并查看此警告的详细信息。

选择“警告”以查看通知。 应会看到四个通知：

• “无法执行技能，因为一个或多个技能输入无效。 缺少必需的技能输入。 名称: 'text'，源: '/document/content'。”

• “无法将输出字段“locations”映射到搜索索引。 请检查索引器的“outputFieldMappings”属性。 缺少值“/document/merged_content/locations”。”

• “无法将输出字段“organizations”映射到搜索索引。 请检查索引器的“outputFieldMappings”属性。 缺少值“/document/merged_content/organizations”。”

• “技能已执行，但可能会产生意外结果，因为一个或多个技能输入无效。 缺少可选的技能输入。 名称：languageCode，源：/document/languageCode。 表达式语言分析问题：缺少值“/document/languageCode”。

许多技能都有一个“languageCode”参数。 通过检查该操作，可以看到 EntityRecognitionSkill.#1 缺少此语言代码输入，这与在“locations”和“organizations”输出方面遇到问题的实体识别技能相同。

由于四个通知全都是关于此技能的，因此下一步就是调试此技能。 如果可能，请先解决输入问题，然后再解决输出问题。

修复缺失的技能输入值

1. 在工作图面上，选择报告警告的技能。 在本教程中，选择的是实体识别技能。

2. 技能详细信息窗格将在右侧打开，其中包含迭代及其各自输入和输出对应的部分、技能 JSON 定义的技能设置，以及此技能发生的任何错误和警告的消息。

   

3. 将鼠标悬停在每个输入上（或选择输入），以显示表达式计算器中的值。 请注意，此输入的显示结果看起来不像文本输入。 它看起来像一系列换行符 (\n \n\n\n\n)，而不像文本。 缺少文本意味着无法标识实体，因此，此文档无法满足技能的先决条件，或者应改为使用另一个输入。

   

4. 切换回“扩充数据结构”并查看本文档的扩充节点。 请注意，“content”的 \n \n\n\n\n 没有初始来源，但“merged_content”的另一个值具有 OCR 输出。 尽管没有任何迹象，但此 PDF 的内容看起来是 JPEG 文件，“merged_content”中提取和处理的文本证明了这一点。

   

5. 切换回技能，并选择“技能组设置”来打开 JSON 定义。

6. 将表达式从 /document/content 更改为 /document/merged_content，然后选择“保存”。 请注意，不会再列出警告。

   

7. 在会话的窗口菜单中选择“运行”。 这会启动对使用文档的技能组的另一次执行。

8. 调试会话执行完成后，请注意警告计数已减少一个。 警告显示文本输入的错误已消失，但其他警告仍然存在。 下一步是解决有关 /document/languageCode 值缺失或为空的警告。

   

9. 选择技能并将鼠标悬停在 /document/languageCode 上。 此输入的值为 null，这不是有效的输入。

10. 与上一个问题一样，首先查看扩充数据结构，以获取其节点的证据。 请注意，没有“languageCode”节点，但是有一个“language”节点。 因此，技能设置中存在拼写错误。

11. 复制表达式 /document/language。

12. 在技能详细信息窗格中，为 #1 技能选择“技能设置”并粘贴新值 /document/language。

13. 选择“保存”。

14. 选择“运行”。

15. 调试会话执行完成后，可以在技能详细信息窗格中检查结果。 将鼠标悬停在 /document/language 上时，应该会看到 en 是表达式计算器中的值。

请注意，输入警告已消失。 现在，只剩下两个有关 organizations 和 locations 的输出字段的警告。

修复缺失的技能输出值

消息说要检查索引器的“outputFieldMappings”属性，因此让我们从这里开始。

1. 在工作图面上选择“输出字段映射”。 请注意，输出字段映射缺失。

   

2. 第一步是，确认搜索索引具有预期的字段。 在这种情况下，索引包含“位置”和“组织”的字段。

3. 如果索引不存在问题，下一步是检查技能输出。 与之前一样，选择扩充数据结构，并滚动节点以查找“位置”和“组织”。 请注意，父级是“content”而不是“merged_content”。 上下文错误。

4. 对于实体识别技能，切换回技能详细信息窗格。

5. 在“技能设置”中，将 context 更改为 document/merged_content。 此时，应该对技能定义了进行三次修改。

   

6. 选择“保存”。

7. 选择“运行”。

所有错误均已解决。

提交对技能组的更改

启动调试会话后，搜索服务创建了技能组的副本。 这样做是为了保护搜索服务上的原始技能组。 现在，你已完成对技能组的调试，接下来可以提交修复（覆盖原始技能组）。

或者，如果你尚未准备好提交更改，则可保存调试会话，稍后再重新打开它。

1. 在“调试会话”主菜单中，选择“提交更改”。

2. 选择“确定”以确认你希望更新技能组。

3. 关闭调试会话，并从左侧导航窗格中打开“索引器”。

4. 选择“clinical-trials-idxr”。

5. 选择“重置”。

6. 选择“运行”。

7. 选择“刷新”以显示重置和运行命令的状态。

索引器运行完毕后，在“执行历史记录”选项卡中，最近一次运行的时间戳旁边应该有一个绿色复选标记和“成功”字样。若要确保已应用更改，请执行以下操作：

1. 在左侧导航窗格中，打开“索引器”。

2. 选择“clinical-trials”索引，然后在“搜索资源管理器”选项卡中输入查询字符串 $select=metadata_storage_path, organizations, locations&$count=true 以返回特定文档的字段（由唯一 metadata_storage_path 字段标识）。

3. 选择“搜索”。

结果应显示 organizations 和 locations 现在已填充预期值。

清理资源

在自己的订阅中操作时，最好在项目结束时确定是否仍需要已创建的资源。 持续运行资源可能会产生费用。 可以逐个删除资源，也可以删除资源组以删除整个资源集。

可以使用左侧导航窗格中的“所有资源”或“资源组”链接 ，在门户中查找和管理资源。

免费服务仅限于三个索引、索引器和数据源。 可以在门户中删除单个项目，以不超出此限制。

后续步骤

本教程涉及技能组定义和处理的各个方面。 若要详细了解概念和工作流，请参阅以下文章：

• 如何将技能组输出字段映射到搜索索引中的字段

• Azure AI 搜索中的技能组

• 如何为增量扩充配置缓存