Surface document-embedded images in agentic retrieval (preview)

Use image serving (preview) to surface images embedded in your source documents (such as diagrams, charts, infographics, scanned forms, and product images) during agentic retrieval, so your large language model (LLM) can reason over visual context alongside text when it synthesizes an answer.

When you enable image serving, Azure AI Search:

• At indexing time, extracts images from supported documents and stores them in a customer-provided Azure Blob asset store.

• At query time, fetches those images during the retrieve action, base64-encodes them, and injects them as multimodal content into the LLM prompt that produces the synthesized answer.

This article shows you how to enable image serving on a knowledge base, override it per request, inspect image serving statistics, and plan for the storage account lifecycle requirements.

Prerequisites

• An Azure AI Search service with a knowledge base that specifies an LLM. The knowledge base must use answer synthesis.

• A file-based indexed knowledge source configured with an assetStore in its ingestionParameters. Supported kinds:

  • Blob knowledge source (Azure Blob Storage or Azure Data Lake Storage Gen2)
  • Indexed OneLake knowledge source
  • Indexed SharePoint knowledge source

  For blob knowledge sources that use standard extraction, complete the blob knowledge source prerequisites.

• The knowledge source must not configure ingestionPermissionOptions.

• Source documents that contain extractable images, such as PNG files, JPEG files, or PDFs with embedded images.

• A Microsoft Foundry resource in a region supported by Azure Content Understanding in Foundry Tools, with Azure OpenAI embedding and multimodal chat model deployments. Use the resource endpoint in the https://<resource-name>.services.ai.azure.com format.

• Permissions to create or update the knowledge base and managed knowledge source. Configure keyless authentication with the Search Service Contributor and Search Index Data Contributor roles assigned to the user or automation identity that performs these management operations (recommended). Alternatively, use an API key.

• Permissions to call the retrieve action. Assign the Search Index Data Reader role to the identity that sends retrieve requests (recommended) or use an API key.

• For outbound calls to the LLM during answer synthesis, the search service must have a managed identity with Cognitive Services User permissions on the Microsoft Foundry resource that hosts the LLM.

• For asset store access, configure the search service managed identity as described in Configure asset store and application access.

• The 2026-05-01-preview REST API or an equivalent Azure SDK preview package: .NET | Java | JavaScript | Python

Limitations and considerations

• Image serving is available only through the retrieve API in agentic retrieval. Classic /docs/search queries don't supply document-embedded images to downstream answer synthesis without a custom solution or configuration.

• Image serving runs only in answer synthesis output mode. The extractiveData output mode skips image serving.

• Image serving applies only to file-based indexed knowledge sources that have assetStore configured and indexed chunks with populated image_path values.

• In mixed knowledge bases, only supported knowledge source kinds (blob, indexed OneLake, and indexed SharePoint) supply document-embedded images to downstream answer synthesis. Other kinds can still contribute text grounding.

• Image serving isn't supported for knowledge sources that use ingestionPermissionOptions to ingest document-level permissions, including ACLs, RBAC scopes, or Microsoft Purview sensitivity labels. The asset store creates an underlying knowledge store, and knowledge stores don't support permission inheritance.

• The retrieve response schema doesn't define fields for the individual asset-store image paths or image bytes sent to the model. The imageServing activity reports aggregate statistics for the images retrieved and sent to the model.

• Access to images is controlled at the storage-account level, independently of access to indexed content. Any identity with read access to the asset storage account can fetch its images.

• Don't store secrets (account keys, tokens, connection strings) in source documents because content can be returned as grounding data.

• Image serving can increase answer synthesis latency because of image download and multimodal token processing. Run representative queries with image serving enabled and disabled and compare response latency with the reported imageServing activity.

• Content Understanding can produce different image results for PDF and DOCX files. If consistent embedded-image extraction and verbalization are required, convert source documents to PDF or test each source format with representative content.

How image serving works

Image serving has two phases:

• Indexing: When you configure standard content extraction and an asset store on a knowledge source, the generated Content Understanding skill semantically chunks the document, preserves tables as Markdown, and uses the configured LLM to describe embedded figures. Figure descriptions become part of the enriched Markdown that the embedding skill vectorizes. The skill also extracts images to your blob asset store and adds image_path references to overlapping chunks.

  When you configure an asset store, the search service also provisions a knowledge store alongside the knowledge source to persist the extracted image artifacts. You can inspect and manage this knowledge store like any other.

• Retrieval: When the retrieve action runs with image serving enabled, the search service fetches the matching images from the asset store, base64-encodes them, and includes them as multimodal content in the answer synthesis prompt.

Configure asset store and application access

Image serving spans three trust boundaries. At indexing time, the search service writes image artifacts to your asset store. At query time, the search service reads from the asset store to retrieve images. Your application also reads from the asset store if it needs to render images in a UI. Configure each path to follow least-privilege access.

Search service access to the asset store

• Use Microsoft Entra ID and a managed identity for the search service. Assign the identity the Storage Blob Data Contributor role at the storage-account scope because the indexer writes image artifacts and the retrieve action reads them. When the source and asset containers share that account, the role also provides source-blob read access.

• Don't enable anonymous public access on the asset store container.

Application access to image references

The generated index stores image_path references to images in the asset store. The retrieve response schema doesn't define dedicated fields for the individual asset-store image paths or image bytes sent to the model. Optional sourceData is structured reference data, and image_path isn't required in it.

To display an indexed image in your application:

1. Assign your application's identity the Storage Blob Data Reader role at the asset storage-account scope.

2. Assign your application's identity the Search Index Data Reader role so it can query the generated index.

3. Obtain an authorized image_path from the generated index through an application-controlled query or service endpoint.

4. Validate that the reference resolves to the expected storage account and asset container. Reject untrusted paths before the blob lookup.

5. Fetch the resulting blob name from the asset container by using your application's identity.

This separation lets you control who can view source images independently of who can call the retrieve API.

Configure the asset store on a knowledge source

Configure assetStore in the ingestionParameters of a supported indexed knowledge source. The asset store is a blob container that you own and that the search service writes image artifacts into.

For source-specific instructions, see:

• Create a blob knowledge source
• Create an indexed SharePoint knowledge source
• Create a OneLake knowledge source

A minimal blob knowledge source with image serving enabled looks like this:

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-05-01-preview
Content-Type: application/json
Authorization: Bearer {{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"
      }
    }
  }
}

Configuration outcomes

The combination of assetStore, disableImageVerbalization, and chatCompletionModel determines what the indexer stores and what the model sees at query time:

• Asset store + verbalization (default): assetStore set, disableImageVerbalization left as false, chatCompletionModel set. The indexer persists images to the asset store and stores text descriptions in the index. Retrieval activity can report verbalizationUsed as true.

• Asset store only: assetStore set, disableImageVerbalization set to true, chatCompletionModel not required. The indexer persists images to the asset store but doesn't generate text descriptions. Retrieval activity can report verbalizationUsed as false.

• No asset store, model set: assetStore not set, chatCompletionModel set. Text descriptions only, no image artifacts. Image serving doesn't apply.

• No asset store, no model: No image processing.

Verify asset store configuration

Wait for ingestion to complete before continuing:

• Check indexer status in the Azure portal or use Get Indexer Status (REST API).

• Check whether indexed chunks have a populated image_path field. If image_path is empty, check the indexer status, the knowledge source asset-store configuration, the source document contents, and the asset container contents.

• Inspect the asset store container. You should see image blobs that the indexer wrote during ingestion.

Enable image serving on a knowledge base

Set enableImageServing to true on the knowledge source reference inside the knowledge base definition. This setting becomes the default for every retrieve request that targets the knowledge source.

The knowledge base definition also specifies the LLM used for answer synthesis at query time. This setting is independent of any chatCompletionModel that you set on the knowledge source's ingestionParameters, which drives image verbalization during indexing.

If your knowledge base references multiple knowledge sources, set enableImageServing only on supported file-based indexed kinds that have assetStore configured. Unsupported kinds (such as search index, remote SharePoint, or web) still contribute text grounding but don't supply document-embedded images to downstream answer synthesis.

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-05-01-preview
Content-Type: application/json
Authorization: Bearer {{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"
      }
    }
  ]
}

Verify image serving enablement

Send a GET request to the knowledge base endpoint and verify that the knowledge source reference includes "enableImageServing": true.

Retrieve with image serving

Call the retrieve action against the knowledge base. To override the knowledge base default on a per-request basis, set enableImageServing in the matching entry under knowledgeSourceParams.

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-05-01-preview
Content-Type: application/json
Authorization: Bearer {{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
    }
  ]
}

What happens at retrieval time

For image references associated with matching content, the search service downloads the corresponding images from the asset store, base64-encodes them, and passes them as multimodal content to the downstream answer-synthesis model. Inspect aggregate image-serving statistics in activity.imageServing. For the exact response shape, see the reference documentation for Knowledge Retrieval - Retrieve (REST API).

Verify retrieve behavior

A retrieve response can provide these image-serving signals:

• When includeActivity is true, the activity array reports imageServing activity for a knowledge source when the service records image-serving operations.

• An imagesSentToModel value greater than 0 means the service reports that it supplied images to the downstream answer-synthesis model.

Precedence rules

When both the knowledge base definition and the retrieve request specify enableImageServing, the value in the retrieve request takes precedence. The full precedence is:

1. The value in knowledgeSourceParams[].enableImageServing on the retrieve request (if set).
2. The value on the matching knowledge source reference in the knowledge base definition (if set).
3. false (the default).

The following table summarizes the nine combinations.

Inspect image serving statistics

When image serving runs, the retrieve response includes an imageServing section for each knowledge source inside the activity array. Use this section to compare the images retrieved from the asset store with the images sent to the model.

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

The fields report:

• verbalizationUsed: The service-reported image verbalization statistic for the retrieval activity.

• imagesRetrieved: The number of images retrieved from the asset store.

• imagesSentToModel: The number of images sent to the downstream model.

• totalImageSizeBytes: The total size, in bytes, of the images sent to the model.

If imagesRetrieved is greater than imagesSentToModel, not every retrieved image was sent to the model.

Inspect verbalizationUsed and imagesSentToModel independently. A response can report both verbalizationUsed as true and one or more images sent to the model.

Test image serving end to end

Use one of the following samples to test the full setup:

• C# image-serving sample
• Python image-serving sample

The samples create a blob knowledge source and knowledge base, compare retrieve requests with image serving disabled and enabled, and inspect image-serving statistics. They also use an independent wildcard index query to select an image_path and download that asset. The samples select one semicolon-delimited reference, remove a projection prefix such as 11.7: from a relative path, or URL-decode an absolute path and remove its leading asset-container segment. These transformations are sample behavior, not guarantees of the retrieve API. The selected asset isn't evidence that the same image contributed to a particular retrieve response.

A typical A/B comparison checklist:

• Pick a question that can only be answered from a diagram, chart, or scanned image.

• Run the retrieve request with enableImageServing: false and capture the answer.

• Run the same retrieve request with enableImageServing: true and compare the answers, latency, and reported activity.

• Treat answer differences as observational A/B signals, not proof that images caused the differences. An imagesSentToModel value greater than 0 means the service reports that it supplied images to the model.

Clean up resources

Delete the knowledge base before you delete its knowledge source. Deleting these Azure AI Search resources doesn't delete source documents or projected image blobs in Azure Storage. Delete those blobs separately only when no retained ingestion or retrieval pipeline still needs them.

Troubleshooting

Use the imageServing activity block from Inspect image serving statistics as your first diagnostic. The following table lists checks for common symptoms without assuming a single cause.

Related content

• Query a knowledge base
• Use answer synthesis for citation-backed responses
• What is a knowledge source?
• Knowledge store concepts