调试会话是 Azure 门户中一个用于调试现有技能组的可视化编辑器，可在会话期间显示由索引器和技能组生成的单个扩充文档的结构和内容。 由于处理的是实时文档，因此会话是交互式的 - 你可以识别错误、修改和调用技能执行，并实时验证结果。 如果所做的更改解决了问题，则可将这些更改提交到已发布的技能组，以全局应用修复措施。
本文介绍支持的方案和编辑器的组织方式。 该编辑器的选项卡和分区将解包技能组的不同层，以便你可以检查技能组结构、流以及它在运行时生成的内容。
支持的方案
使用调试会话来调查和解决以下问题：
比较前两种方案的以下调试会话映像。 对于这两种情况，表面区域显示从源文档到搜索索引过程中生成或转换内容的技能发展。 该流包括索引映射选项，可以沿箭头查看处理流程。 右侧的详细信息窗格是与上下文相关的。 它显示由管道创建的增强文档的表示形式，或技能或映射的详细信息。
第一个图像显示了应用的 AI 扩充的模式（无矢量）。 如果没有依赖项，技能可以按顺序或并行运行。 索引映射显示扩充或生成的内容如何从内存中的数据结构流动到索引中的字段。 扩充的文档显示了技能集创建的数据结构。
第二张图像显示了集成矢量化的典型模式。 集成矢量化的技能通常包括文本拆分技能和嵌入技能。 文本拆分技能会将文档拆分为区块。 嵌入技能调用嵌入 API 来矢量化这些区块。 此特定技能集将内容分块为“pages”数组。 对于集成矢量化，投影映射控制如何将区块映射到索引中的字段。
限制
调试会话适用于所有正式发布的索引器数据源和大多数预览版数据源，但有以下例外：
Azure Cosmos DB for MongoDB 索引器。
对于 Azure Cosmos DB for NoSQL，如果某个行在索引期间失败并且没有相应的元数据，则调试会话可能不会选择正确的行。
对于 Azure Cosmos DB 的 SQL API，如果分区集合以前未分区，则调试会话将找不到该文档。
对于自定义技能，用户分配的托管身份不支持与 Azure 存储的调试会话连接。 如先决条件中所述，可以使用系统托管标识，或指定包含密钥的完全访问连接字符串。 有关详细信息，请参阅使用托管标识将搜索服务连接到其他 Azure 资源。
启用了客户管理密钥（CMK）加密的数据源。
目前还无法选择要调试的文档。 此限制不是永久性的，应该很快解除。 此时，调试会话会选择源数据容器或文件夹中的第一个文档。
调试会话的工作方式
当你启动会话时，搜索服务将创建技能组、索引器的副本和一个数据源，其中包含用于测试技能组的单个文档。 Azure AI 搜索服务将所有会话状态保存到在提供的Azure 存储帐户中创建的新 blob 容器。 生成的容器名称的前缀为 ms-az-cognitive-search-debugsession. 此前缀可降低意外将会话数据导出到账户中其他容器的可能性。
如果使用 托管标识配置存储帐户连接，请将 Storage Blob Data Contributor 角色分配给存储帐户上的搜索服务标识。 在存储帐户中，启用受信任的服务以允许从Azure AI 搜索进行写入访问。
扩充文档和技能组的缓存副本将加载到可视化编辑器中，以便你能够检查已扩充文档的内容和元数据，并且能够检查每个文档节点并编辑技能组定义的任何方面。 会话中所做的任何更改都会被缓存。 除非您提交更改，否则这些更改不会影响已发布的技能集。 提交更改将覆盖生产技能组。
如果扩充管道没有任何错误，则可使用调试会话来以增量方式扩充文档、测试和验证每个更改，然后再提交更改。
调试会话通过分析数据、技能输入和输出和字段映射来帮助识别错误或警告的根本原因。 使用技能详细信息窗格查看每个技能接收什么输入并生成什么输出。 此检查有助于验证是否已正确形成技能定义、表达式和字段映射。 如果索引器遇到配置问题（例如网络设置不正确或权限相关的访问错误），请查看特定的错误消息和链接文档。 有关故障排除指南，请参阅 常见索引器错误和警告。
调试会话和专用连接
调试会话不支持共享专用链接。 如果生产搜索服务使用专用终结点连接来访问数据源或其他资源，则调试会话无法针对该服务运行。
解决方法：使用测试搜索服务
若要调试技能集，请单独创建一个不受专用连接限制的 Azure AI 搜索 服务。 若要使生产数据和架构详细信息远离非专用环境，请使用综合文档生成测试设置：
- 创建与生产数据的字段类型和结构匹配的测试文档，但使用通用字段名称（例如，
content、title、category）和占位符值，而不是实际数据。 技能集逻辑取决于内容类型和结构，而不是特定的字段名称。 - 从你的生产服务中复制技能集 JSON。 如果技能输入引用生产字段名称，请更新这些引用以匹配通用测试字段名称。 使用测试索引器中的 字段映射 将测试字段名称与技能组输入对齐。
- 配置索引器以针对测试数据源运行。
在测试服务上运行调试会话，检查技能输入和输出、验证技能表达式和字段映射以及识别错误。 当您所做的更改通过验证后，请在技能集 JSON 中还原对原始生产字段名称的引用，并将其重新应用回生产服务。
调试会话布局
视觉编辑器会组织成显示操作进度的图面区域，首先是文档破解，然后是技能、映射和索引。
选择任意技能或映射，会打开一个窗格在旁边显示相关信息。
单击相应的链接进一步深入查看技能处理。 例如，以下屏幕截图显示了“文本拆分”技能首次迭代后的输出。
技能详细信息窗格
“ 技能详细信息”窗格包含以下部分：
- 迭代：显示技能执行的次数。 可以检查每一个的输入和输出。
- 技能设置：查看或编辑 JSON 技能集定义。
- 错误和警告：显示特定于此技能的错误或警告。
丰富数据结构窗格
选择蓝色显示或隐藏箭头符号时，“扩充数据结构 ”窗格将从侧边滑出。 它是扩充文档包含的人类可读表示形式。 本文前面的屏幕截图显示了扩充数据结构的示例。
后续步骤
了解调试会话的元素后，就可以在现有技能组上启动第一个调试会话了。