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

  • 项目

技能组协调一系列分析或转换内容的操作，其中一种技能的输出将变为另一种技能的输入。 当输入依赖于输出时，如果技能组定义和字段关联出现错误，可能会导致操作和数据丢失。

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

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

先决条件

开始之前，必须具备以下先决条件：

注意

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

设置数据

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

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

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

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

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

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

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

  5. 在门户中，获取并保存 Azure 存储的连接字符串。 REST API 对数据编制索引时需要使用该字符串。 可以从 Azure 门户的“设置”>“访问密钥”获取连接字符串 。

获取密钥和 URL

REST 调用需要在每个请求中使用服务 URL 和访问密钥。 搜索服务是使用这二者创建的，因此，如果向订阅添加了 Azure 认知搜索，则请按以下步骤获取必需信息：

  1. 登录到 Azure 门户，在搜索服务的“概览”页中获取 URL。 示例终结点可能类似于 https://mydemo.search.azure.cn。

  2. 在“设置”>“密钥”中，获取有关该服务的完全权限的管理员密钥 。 有两个可交换的管理员密钥，为保证业务连续性而提供，以防需要滚动一个密钥。 可以在请求中使用主要或辅助密钥来添加、修改和删除对象。

    Get an HTTP endpoint and access key

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

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

在本部分中，你将导入一个 Postman 集合，其中包含将在本教程中修复的带有“bug”的工作流。

  1. 启动 Postman 并导入 DebugSessions.postman_collection.json 集合。 如果你不熟悉 Postman，请参阅本快速入门。

  2. 在“文件”>“新建”下，选择该集合。

  3. 导入集合后，展开操作列表 (...)。

  4. 选择“编辑”以设置每个请求中使用的变量。

    当前值 说明
    searchService 搜索服务的名称（例如，如果终结点为 https://mydemo.search.azure.cn，则服务名称为 mydemo）。
    apiKey 从搜索服务的“密钥”页获取的主密钥或辅助密钥。
    storageConnectionString 从 Azure 存储帐户的“访问密钥”页获取的连接字符串。
    containerName 为示例数据创建的容器的名称。

  5. 单击“保存”以保存更改。 除非保存变量，否则请求将失败。

  6. 在该集合中应会看到四个 REST 调用。

    • CreateDataSource 添加 clinical-trials-ds
    • CreateSkillset 添加 clinical-trials-ss
    • CreateIndex 添加 clinical-trials
    • CreateIndexer 添加 clinical-trials-idxr

  7. 依次打开每个请求，然后选择“发送”以将每个请求发送到搜索服务。 最后一个请求将需要几分钟的时间才能完成。

  8. 关闭 Postman，返回到 Azure 门户。

在门户中检查结果

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

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

  2. 选择“clinical-trials”。

  3. 输入此查询字符串 $select=metadata_storage_path, organizations, locations&$count=true 以返回特定文档的字段（由唯一 metadata_storage_path 字段标识）。

  4. 选择“搜索”以运行查询。 “organizations”和“locations”应会显示空值。

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

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

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

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

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

    Screenshot of view warnings.

启动调试会话

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

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

  3. 为会话命名。

  4. 将会话连接到存储帐户。 创建名为“调试会话”的容器。 你可以重复使用此容器来存储所有调试会话数据。

  5. 如果在搜索和存储之间配置了信任连接，请为连接选择用户托管标识或系统标识。 否则，请使用默认值 (None)。

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

  7. 接受集合中第一个文档的默认文档选择。 调试会话仅适用于单个文档。 可选择要调试的文档，也可以只使用第一个文档。

  8. 保存会话。 保存会话将启动由所选文档的技能组定义的扩充管道。

    Screenshot of configuring a new debug session.

  9. 调试会话初始化完毕后，该会话默认显示“AI 扩充”选项卡，并突出显示“技能图” 。 技能图提供技能组的可视层次结构并按顺序并行显示其执行顺序。

    Screenshot of Debug Session visual editor.

查找技能组问题

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

Screenshot of the errors and warnings tab.

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

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

  • “无法执行技能，因为一个或多个技能输入无效。 缺少必需的技能输入。 名称: '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”有问题。

  1. 在“AI 扩充”>“技能图”中，选择标记为“#1”的技能，以便在右窗格中显示其详细信息。

  2. 选择“执行”选项卡，找到“text”的输入。

  3. 选择将以弹出窗口方式打开表达式计算器的 </> 符号。 此输入的显示结果看起来不像文本输入。 它看起来像一系列换行符 (\n \n\n\n\n)，而不像文本。 缺少文本意味着无法标识实体，因此，此文档无法满足技能的先决条件，或者应改为使用另一个输入。

    Screenshot of Expression Evaluator for the text input.

  4. 在右侧窗格中，为 #1 技能选择“执行”，并为输入“text”打开表达式计算器 </>。

  5. 将表达式从 /document/content 更改为 /document/merged_content，然后选择“计算”。 请注意，内容现在是文本区块，因此可用于实体识别。

    Screenshot of Expression Evaluator for fixed merged_content input.

  6. 切换到“技能 JSON 编辑器”。

  7. 在第 16 行的“输入”下，将 /document/content 更改为 /document/merged_content。

     {
   "name": "text",
   "source": "/document/merged_content"
 },

  8. 在“技能详细信息”窗格中选择“保存”。

    Screenshot of the Save command for skillset details.

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

  10. 调试会话执行完成后，检查“错误/警告”选项卡，该选项卡会显示文本输入错误已消失，但仍会出现其他警告。 下一步是解决有关“languageCode”的警告。

    Screenshot of updated errors and warnings.

  11. 选择“执行”选项卡，然后找到“languageCode”的输入。

  12. 选择 </> 符号以弹出表达式计算器。 请注意确认“languageCode”属性不是有效输入。

    Screenshot of Expression Evaluator for the language input.

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

  1. 在“执行”选项卡中，检查输入并查找“languageCode”。 未列出此输入的源。

  2. 将左侧窗格切换为“扩充数据结构”。 向下滚动此文档的扩充节点列表。 请注意，没有“languageCode”节点，但是有一个“language”节点。 因此，技能设置中存在拼写错误。

    Screenshot of Enriched Data Structure, with language highlighted.

  3. 仍然在“扩充数据结构”中，为“language”节点打开表达式计算器 </>，并复制表达式 /document/language。

  4. 在右侧窗格中，选择技能 #1 的“技能设置”，然后为“languageCode”输入打开表达式计算器 </>。

  5. 将新值 /document/language 粘贴到“表达式”框中，然后单击“求值”。 它应该显示正确输入“en”。

  6. 选择“保存”。

  7. 选择“运行”。

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

修复缺失的技能输出值

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

  1. 转到“技能图”，选择“输出字段映射”。 映射实际上是正确的，但通常你会检查索引定义，以确保“locations”和“organizations”的字段存在。

    Screenshot of the output field mappings.

  2. 选择实体识别技能。

  3. 浏览“技能设置”以找到“上下文”。

    Screenshot of the context correction in skill setting.

  4. 双击“上下文”设置，然后将其编辑为读取“/document/merged_content”。

  5. 选择“保存”。

  6. 选择“运行”。

所有错误均已解决。

提交对技能组的更改

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

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

  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 现在已填充预期值。

清理资源

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

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

如果使用的是免费服务，请记住只能设置三个索引、索引器和数据源。 可以在门户中删除单个项目，以不超出此限制。

后续步骤

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