在智能体检索中显示文档嵌入的图像（预览版）

使用图像呈现（预览版），可在代理式检索期间呈现源文档中嵌入的图像（如示意图、图表、信息图、扫描表单和产品图片），以便大型语言模型（LLM）在生成答案时结合视觉上下文与文本进行推理。

启用图像服务时，Azure AI 搜索：

• 在编制索引时，从受支持的文档中提取图像，并将其存储在客户提供Azure Blob 资产存储中。

• 在查询时，在 检索操作期间提取这些图像，对其进行 base64 编码，并将其作为多模式内容注入到生成合成答案的 LLM 提示符中。

本文介绍如何在知识库上启用映像服务、按请求重写映像、检查映像服务统计信息以及规划存储帐户生命周期要求。

使用支持

先决条件

• 具有指定 LLM 的 知识库 的 Azure AI 搜索服务。 知识库必须使用 答案合成。

• 基于文件的索引知识来源，其 assetStore 中配置有 ingestionParameters。 支持的种类：

  • Blob 知识来源（Azure Blob 存储或 Azure Data Lake Storage Gen2）
  • 已编入索引的 OneLake 知识源
  • 已编入索引的 SharePoint 知识源

  对于使用标准提取的 Blob 知识源，请完成 Blob 知识源先决条件。

• 知识源不得配置 ingestionPermissionOptions。

• 包含可提取图像的源文档，例如 PNG 文件、JPEG 文件或包含嵌入图像的 PDF。

• 位于 Foundry Tools 中受 Azure 内容理解支持的区域 的 Microsoft Foundry 资源，并具有 Azure OpenAI 嵌入和多模态聊天模型部署。 使用 https://<resource-name>.services.ai.azure.com 格式的资源终结点。

• 创建或更新知识库和托管知识库的权限。 配置无密钥身份验证，并将Search Service Contributor和 Search Index Data Contributor 角色分配给执行这些管理操作的用户或自动化标识（推荐）。 或者，使用 管理员 API 密钥。

• 调用检索操作的权限。 将 搜索索引数据读取者 角色分配给发送检索请求（建议）或使用 查询 API 密钥的标识。

• 若要在答案合成期间向 LLM 发起出站调用，搜索服务必须具有 托管身份，并在托管 LLM 的 Microsoft Foundry 资源上具有 认知服务用户 权限。

• 对于资产存储访问，请配置搜索服务托管标识，如 配置资产存储和应用程序访问中所述。

• 2026-08-01-preview REST API 或等效的 Azure SDK 预览包：.NET | Java | JavaScript | Python

限制和注意事项

• 图像服务只能通过代理检索中的 retrieve API 使用。 如果没有自定义解决方案或配置，经典 /docs/search 查询不会向下游应答合成提供文档嵌入的图像。

• 图像服务仅在 应答合成 输出模式下运行。 extractiveData 输出模式跳过图像服务。

• 图像服务仅适用于基于文件的索引知识来源，这些知识来源已配置 assetStore，且其已编制索引的区块填充了 image_path 值。

• 在混合知识库中，只有受支持的知识源类型（blob、已编入索引的 OneLake 和已编入索引的 SharePoint）才会为下游答案合成提供嵌入在文档中的图像。 其他类型仍可提供文本基础。

• 对于使用 ingestionPermissionOptions 引入文档级权限（包括 ACL、RBAC 范围或 Microsoft Purview 敏感度标签）的知识源，不支持提供图像。 资产存储创建基础知识存储，知识存储不支持权限继承。

• 检索响应架构不为发送到模型的单个资产存储图像路径或图像字节定义字段。 imageServing 活动报告了检索到并发送给模型的图像的聚合统计信息。

• 在存储帐户级别（独立于对索引内容的访问权限）控制对映像的访问。 任何对资产存储账户具有读取访问权限的身份都可以获取其中的映像。

• 不要将机密（帐户密钥、令牌、连接字符串）存储在源文档中，因为内容可以作为地面数据返回。

• 由于图像下载和多模式令牌处理，图像服务会增加答案合成延迟。 分别在启用和禁用镜像服务的情况下运行具有代表性的查询，并将响应延迟与报告的 imageServing 活动进行比较。

• 内容理解可以为 PDF 和 DOCX 文件生成不同的图像结果。 如果需要一致的嵌入式图像提取和语言化，请将源文档转换为 PDF，或使用代表性内容测试每个源格式。

图像服务的工作原理

映像服务有两个阶段：

• 索引： 在知识源上配置标准内容提取和资产存储时，生成的内容理解技能以语义方式对文档进行分块，保留表作为 Markdown，并使用配置的 LLM 来描述嵌入的数字。 图形说明会成为由嵌入技能进行向量化的增强型 Markdown 的一部分。 该技能还会将图像提取到你的 Blob 资产存储中，并向重叠的块添加 image_path 引用。

  配置资产存储时，搜索服务还会与知识源一起预配 知识存储 来保留提取的图像项目。 可以像任何其他一样检查和管理此知识存储。

• 检索： 当检索操作在启用图像服务的情况下运行时，搜索服务将从资产存储中提取匹配的图像，base64 对其进行编码，并将其作为多模式内容包含在答案合成提示中。

配置资产存储和应用程序访问

图像服务跨越三个信任边界。 在编制索引时，搜索服务会将图像项目写入资产存储。 在查询时，搜索服务从资产存储读取以检索图像。 如果应用程序需要在 UI 中呈现图像，则应用程序还会从资产存储中读取图像。 将每条路径配置为遵循最小权限访问原则。

搜索服务对资产存储的访问权限

• 为搜索服务使用 Microsoft Entra ID 和托管标识。 在存储帐户范围内分配 存储 Blob 数据参与者 角色的标识，因为索引器会写入映像项目，检索操作会读取它们。 当源容器和资产容器共享该帐户时，该角色还提供源 Blob 读取访问权限。

• 不要在资产存储容器上启用匿名公共访问。

应用程序对图像引用的访问权限

生成的索引存储 image_path 资源存储中的图像引用。 检索响应架构不为发送到模型的各个资产存储图像路径或图像字节定义专用字段。 可选的 sourceData 是结构化参考数据，其中不需要 image_path。

若要在应用程序中显示索引图像，请执行以下操作：

1. 在资产存储帐户范围内为应用程序分配 存储 Blob 数据读取者 角色。

2. 为应用程序的标识分配 “搜索索引数据读取器” 角色，以便其可以查询已生成的索引。

3. 通过应用程序控制的查询或服务端点，从生成的索引中获取经授权的 image_path。

4. 验证该引用是否解析到预期的存储帐户和资产容器。 在进行 blob 查找之前，拒绝不受信任的路径。

5. 使用应用程序的标识从资产容器中提取生成的 Blob 名称。

这种分离使您可以将谁能查看源图像与谁能调用检索 API 分开控制。

在知识源上配置资产存储

在受支持的索引知识来源的 assetStore 中配置 ingestionParameters。 资产存储是你拥有的 blob 容器，搜索服务将图像项目写入其中。

有关源专用说明，请参阅：

• 创建 Blob 知识库
• 创建索引SharePoint知识源
• 创建 OneLake 知识源

启用了图像服务的最简 Blob 知识来源如下所示：

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "source-documents",
    "ingestionParameters": {
      "assetStore": {
        "connectionString": "ResourceId=<storage-resource-id>",
        "containerName": "image-assets"
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "gpt-4o",
          "modelName": "gpt-4o"
        }
      },
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "https://{foundry-resource}.services.ai.azure.com"
      }
    }
  }
}

配置结果

assetStore、disableImageVerbalization 和 chatCompletionModel 的组合决定了索引器存储的内容以及模型在查询时看到的内容：

• 资源库 + 文本化（默认）：assetStore 设置，disableImageVerbalization 保持为 false，chatCompletionModel 设置。 索引器将图像保存到资产存储中，并将文本说明存储在索引中。 检索活动可以报告 verbalizationUsed 为 true.

• 仅资产存储：assetStore 已设置，disableImageVerbalization 设为 true，chatCompletionModel 非必需。 索引器将图像保存到资产存储，但不生成文本说明。 检索活动可以报告 verbalizationUsed 为 false.

• 没有资源存储，模型设置：assetStore 未设置，chatCompletionModel 已设置。 仅文本说明，无图像项目。 图像服务不适用。

• 无资产存储，无模型： 无图像处理。

验证资产存储配置

等待导入完成后再继续：

• 在 Azure 门户中检查索引器状态或使用 Get 索引器状态 （REST API）。

• 检查已编入索引的块的 image_path 字段是否已填充。 如果 image_path 为空，请检查索引器状态、知识源资产存储配置、源文档内容和资产容器内容。

• 检查资产存储容器。 你应该会看到索引器在引入过程中写入的图像 Blob 对象。

在知识库上启用映像服务

将知识库定义中的知识源引用的 enableImageServing 设置为 true。 此设置将成为面向知识源的每个检索请求的默认值。

知识库定义还指定了在查询时间用于答案合成的 LLM。 此设置独立于你在知识源的 chatCompletionModel 上设置的任何 ingestionParameters，后者在索引期间驱动映像口头化。

如果你的知识库引用了多个知识来源，请仅对配置了 enableImageServing 的支持的基于文件的索引类型设置 assetStore。 不受支持的类型（如搜索索引、远程 SharePoint 或 Web）仍会提供文本依据，但不会向下游答案生成提供文档中嵌入的图像。

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-kb",
  "knowledgeSources": [
    {
      "name": "my-blob-ks",
      "enableImageServing": true
    }
  ],
  "outputMode": "answerSynthesis",
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
        "deploymentId": "gpt-4o",
        "modelName": "gpt-4o"
      }
    }
  ]
}

验证镜像服务是否已启用

向知识库端点发送 GET 请求，并验证知识源引用是否包含 "enableImageServing": true。

使用图像服务进行检索

针对知识库调用 检索操作 。 要根据每个请求覆盖知识库默认值，请在 enableImageServing 下的匹配条目中设置 knowledgeSourceParams。

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "retrievalReasoningEffort": { "kind": "medium" },
  "outputMode": "answerSynthesis",
  "includeActivity": true,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's the wiring configuration shown in the installation guide?" }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "my-blob-ks",
      "kind": "azureBlob",
      "enableImageServing": true
    }
  ]
}

检索时发生的情况

对于与匹配内容关联的图像引用，搜索服务将从资产存储下载相应的图像，对其进行 base64 编码，并将其作为多模式内容传递给下游应答合成模型。 在activity.imageServing中查看汇总图像服务统计信息。 有关确切的响应形状，请参阅 知识检索 - 检索 （REST API）的参考文档。

验证检索行为

检索响应可以提供以下图像服务信号：

• 当 true 为 includeActivity 时，如果服务记录了图像提供操作，activity 数组会针对某个知识源报告 imageServing 活动。

• imagesSentToModel 的值大于 0 表示该服务报告称其已向下游答案合成模型提供了图像。

优先规则

当知识库定义和检索请求都指定 enableImageServing时，检索请求中的值优先。 完整优先级为：

1. 检索请求中的 knowledgeSourceParams[].enableImageServing 值（如果已设置）。
2. 知识库定义中匹配知识库引用的值（如果已设置）。
3. false （默认值）。

下表汇总了九种组合。

检查图像服务统计信息

当映像服务运行时，检索响应在 imageServing 数组内的每个知识源包含一个 activity 部分。 使用此部分可将从资产存储中检索到的图像与发送到模型的图像进行比较。

"activity": [
  {
    "type": "azureBlob",
    "knowledgeSourceName": "my-blob-ks",
    "imageServing": {
      "verbalizationUsed": true,
      "imagesRetrieved": 5,
      "imagesSentToModel": 4,
      "totalImageSizeBytes": 248361
    }
  }
]

字段报告：

• verbalizationUsed：检索活动的由服务报告的图像文字说明统计数据。

• imagesRetrieved：从资产存储中检索的图像数。

• imagesSentToModel：发送到下游模型的图像数。

• totalImageSizeBytes：发送到模型的图像的总大小（以字节为单位）。

如果 imagesRetrieved 大于 imagesSentToModel，则不是每个检索到的图像都发送到模型。

分别检查imagesSentToModel和verbalizationUsed。 响应可以同时将 verbalizationUsed 报告为 true，并报告发送给模型的一张或多张图像。

对图像服务进行端到端测试

使用以下示例之一测试完整设置：

• C# 图像服务示例
• Python图像服务示例

这些示例会创建 Blob 知识源和知识库，比较在禁用和启用图像服务时的检索请求，并检查图像服务统计信息。 他们还使用独立的通配符索引查询来选取 image_path 并下载该资源。 这些示例会选择一个以分号分隔的引用项，从相对路径中删除诸如 11.7: 之类的投影前缀，或者对绝对路径进行 URL 解码并删除其开头的 asset-container 段。 这些转换只是示例行为，并非 retrieve API 的保证。 所选资产没有证据表明同一图像促成了特定的检索响应。

典型的 A/B 比较清单：

• 选择一个只能根据示意图、图表或扫描图像来回答的问题。

• 运行检索请求 enableImageServing: false 并捕获答案。

• 使用 enableImageServing: true 运行相同的检索请求，并比较答案、延迟时间和报告的活动情况。

• 将答案差异视为观察 A/B 信号，而不是证明图像导致了差异。 imagesSentToModel 值大于 0 表示服务报告称其已向模型提供了图像。

清理资源

在删除知识源之前，请先删除知识库。 删除这些 Azure AI 搜索资源并不会删除 Azure 存储中的源文档或投影图像 Blob。 仅在没有任何保留的数据引入或检索管道仍需使用这些 Blob 时，才分别删除它们。

故障排除

使用imageServing中的 活动块作为第一个诊断。 下表列出了针对常见症状的检查项，且不预设单一原因。

相关内容

• 查询知识库
• 使用答案合成来创建有引文支持的响应
• 什么是知识源？
• 知识存储概念