Tutorial:使用调试会话调试技能组

项目
04/26/2024

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

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

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

如果没有 Azure 订阅，请在开始前创建一个试用版订阅。

先决条件

Azure AI 搜索。创建服务或在当前订阅下查找现有服务。可在本教程中使用免费服务。
具有 Blob 存储的 Azure 存储帐户，用于承载示例数据以及保存在调试会话期间创建的缓存数据。
Postman 应用和 Postman 集合，用于通过 REST API 创建对象。
示例 PDF（临床试验）。

注意

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

设置示例数据

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

下载包含 19 个文件的示例数据 (clinical-trials-pdf-19)。
创建 Azure 存储帐户或查找现有帐户。
- 选择 Azure AI 搜索所在的同一区域，以避免带宽费用。
- 选择 StorageV2（常规用途 V2）帐户类型。
导航到门户中的 Azure 存储服务页，创建一个 Blob 容器。最佳做法是将访问级别指定为“专用”。将容器命名为 clinicaltrialdataset。
在容器中，选择“上传”以上传在第一个步骤中下载并解压缩的示例文件。
在门户中，复制 Azure 存储的连接字符串。可以从 Azure 门户的“设置”>“访问密钥”获取连接字符串。

复制密钥和 URL

REST 调用需要在每个请求中使用搜索服务终结点和 API 密钥。可以从 Azure 门户获取这些值。

登录到 Azure 门户，导航到概述页，并复制 URL。示例终结点可能类似于 https://mydemo.search.azure.cn。
在“设置”>“密钥”下，复制管理密钥。管理密钥用于添加、修改和删除对象。有两个可互换的管理密钥。复制其中任意一个。

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

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

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

启动 Visual Studio Code 并打开 debug-sessions.rest 文件。
提供以下变量：搜索服务 URL、搜索服务管理 API 密钥、存储连接字符串以及存储 PDF 的 Blob 容器的名称。
依次发送每个请求。创建索引器需要几分钟才能完成。
关闭文件。

在门户中检查结果

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

在 Azure 门户的搜索服务“概述”页上，选择“索引”选项卡。
选择“clinical-trials”。
在搜索资源管理器的 JSON 视图中输入此 JSON 查询字符串。它返回特定文档的字段（由唯一的 metadata_storage_path 字段标识）。
```
"select": "metadata_storage_path, organizations, locations",
"count"=true`
```
运行查询。你应会看到 organizations 和 locations 的空值。

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

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

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

请注意，虽然索引器作业总体上讲已成功完成，但有警告。
选择“成功”以查看警告（如果大部分都是错误，详细信息链接会显示“失败”）。你将看到索引器发出的每个警告都有一长串列表。

启动调试会话

在搜索服务左侧导航窗格中的“搜索管理”下，选择“调试会话”。
选择“+ 添加调试会话”。
为会话命名。
将会话连接到存储帐户。创建名为“调试会话”的容器。你可以重复使用此容器来存储所有调试会话数据。
如果在搜索和存储之间配置了信任连接，请为连接选择用户托管标识或系统标识。否则，请使用默认值 (None)。
在索引器模板中，提供索引器名称。索引器具有对数据源、技能组和索引的引用。
接受集合中第一个文档的默认文档选择。调试会话仅适用于单个文档。可选择要调试的文档，也可以只使用第一个文档。
保存会话。保存会话将启动由所选文档的技能组定义的扩充管道。
调试会话初始化完毕后，该会话默认显示“AI 扩充”选项卡，并突出显示“技能图” 。技能图提供技能组的可视层次结构并按顺序并行显示其执行顺序。

查找技能组问题

索引器报告的任何问题都可在相邻的“错误/警告”选项卡中找到。

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

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

“无法执行技能，因为一个或多个技能输入无效。缺少必需的技能输入。名称: '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”输出方面遇到问题的实体识别技能相同。

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

修复缺失的技能输入值

在“错误/警告”选项卡中，标记为 EntityRecognitionSkill.#1 的操作有两个缺失的输入。第一个错误的详细信息说明缺少“text”的必需输入。第二个错误指示输入值“/document/languageCode”有问题。

在“AI 扩充”>“技能图”中，选择标记为“#1”的技能，以便在右窗格中显示其详细信息。
选择“执行”选项卡，找到“text”的输入。
选择将以弹出窗口方式打开表达式计算器的 </> 符号。此输入的显示结果看起来不像文本输入。它看起来像一系列换行符 (\n \n\n\n\n)，而不像文本。缺少文本意味着无法标识实体，因此，此文档无法满足技能的先决条件，或者应改为使用另一个输入。
在右侧窗格中，为 #1 技能选择“执行”，并为输入“text”打开表达式计算器 </>。
将表达式从 /document/content 更改为 /document/merged_content，然后选择“计算”。请注意，内容现在是文本区块，因此可用于实体识别。
切换到“技能 JSON 编辑器”。
在第 16 行的“输入”下，将 /document/content 更改为 /document/merged_content。
```
 {
   "name": "text",
   "source": "/document/merged_content"
 },
```
在“技能详细信息”窗格中选择“保存”。
在会话的窗口菜单中选择“运行”。这将启动对使用文档的技能组的另一次执行。
调试会话执行完成后，检查“错误/警告”选项卡，该选项卡会显示文本输入错误已消失，但仍会出现其他警告。下一步是解决有关“languageCode”的警告。
选择“执行”选项卡，然后找到“languageCode”的输入。
选择 </> 符号以弹出表达式计算器。请注意确认“languageCode”属性不是有效输入。

可通过两种方法来研究此错误。第一种方法是查看输入来自何处，层次结构中的哪个技能应该会生成此结果？ “技能详细信息”窗格中的“执行”选项卡应显示输入源。如果没有源，则表示存在字段映射错误。

在“执行”选项卡中，检查输入并查找“languageCode”。未列出此输入的源。
将左侧窗格切换为“扩充数据结构”。向下滚动此文档的扩充节点列表。请注意，没有“languageCode”节点，但是有一个“language”节点。因此，技能设置中存在拼写错误。
仍然在“扩充数据结构”中，为“language”节点打开表达式计算器 </>，并复制表达式 /document/language。
在右侧窗格中，选择技能 #1 的“技能设置”，然后为“languageCode”输入打开表达式计算器 </>。
将新值 /document/language 粘贴到“表达式”框中，然后选择“求值”。它应该显示正确输入“en”。
选择“保存”。
选择“运行”。

调试会话执行完成后，检查“错误/警告”选项卡，它将显示所有输入警告都已消失。现在，只剩下两个有关 organizations 和 locations 的输出字段的警告。

修复缺失的技能输出值

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

转到“技能图”，选择“输出字段映射”。映射实际上是正确的，但通常你会检查索引定义，以确保“locations”和“organizations”的字段存在。
选择实体识别技能。
浏览“技能设置”以找到“上下文”。
双击“上下文”设置，然后将其编辑为读取“/document/merged_content”。
选择“保存”。
选择“运行”。

所有错误均已解决。

提交对技能组的更改

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

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

在“调试会话”主菜单中，选择“提交更改”。
选择“确定”以确认你希望更新技能组。
关闭调试会话，并从左侧导航窗格中打开“索引器”。
选择“clinical-trials-idxr”。
选择“重置”。
选择“运行”。
选择“刷新”以显示重置和运行命令的状态。

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

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

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

清理资源

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

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

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

后续步骤

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