Exibir imagens incorporadas em documentos na recuperação por meio de agentes (versão prévia)

Use fornecimento de imagens (versão prévia) para disponibilizar imagens incorporadas aos seus documentos de origem (como diagramas, gráficos, infográficos, formulários digitalizados e imagens de produtos) durante a recuperação por meio de agentes, para que seu LLM (modelo de linguagem de grande porte) possa raciocinar sobre o contexto visual junto com o texto ao sintetizar uma resposta.

Ao habilitar o fornecimento de imagens, o Pesquisa de IA do Azure :

• No momento da indexação, extrai imagens de documentos com suporte e as armazena em um repositório de ativos Azure Blob fornecido pelo cliente.

• No momento da consulta, busca essas imagens durante a ação de recuperação, a base64 as codifica e as injeta como conteúdo multimodal no prompt llm que produz a resposta sintetizada.

Este artigo mostra como habilitar o fornecimento de imagens em uma base de conhecimento, substituir essa configuração por solicitação, inspecionar as estatísticas de fornecimento de imagens e planejar os requisitos do ciclo de vida da conta de armazenamento.

Suporte de uso

Pré-requisitos

• Um serviço Pesquisa de IA do Azure  com uma base de conhecimento que especifica uma LLM. A base de dados de conhecimento deve usar a síntese de resposta.

• Uma fonte de conhecimento indexada baseada em arquivos configurada com um assetStore no seu ingestionParameters. Tipos com suporte:

  • Fonte de conhecimento Blob (Armazenamento de Blobs do Azure ou Azure Data Lake Storage Gen2)
  • Fonte de conhecimento indexada do OneLake
  • Fonte de conhecimento do SharePoint indexada

  Para fontes de conhecimento de blobs que usam extração padrão, complete os pré-requisitos da fonte de conhecimento de blobs.

• A fonte de conhecimento não deve configurar ingestionPermissionOptions.

• Documentos de origem que contêm imagens extraíveis, como arquivos PNG, arquivos JPEG ou PDFs com imagens inseridas.

• Um recurso do Microsoft Foundry em uma região com suporte à Compreensão de Conteúdo do Azure no Foundry Tools, com implantações de modelos de incorporação do OpenAI do Azure e de chat multimodal. Use o endpoint do recurso no formato https://<resource-name>.services.ai.azure.com.

• Permissão para criar ou atualizar a base de dados de conhecimento e a fonte de conhecimento gerenciada. Configure autenticação sem chave com as funções Colaborador do Serviço de Pesquisa e Colaborador de Dados de Índice de Pesquisa atribuídas ao usuário ou à identidade de automação que executa essas operações de gerenciamento (recomendado). Como alternativa, use uma chave de API de administrador.

• Permissão para chamar a ação de recuperação. Atribua a função Leitor de Dados de Índice de Pesquisa à identidade que envia solicitações de recuperação (recomendadas) ou use uma chave de API de consulta.

• Para chamadas de saída para o LLM durante a síntese da resposta, o serviço Pesquisa deve ter uma identidade gerenciada com permissões Usuário dos Serviços Cognitivos no recurso do Microsoft Foundry que hospeda o LLM.

• Para acesso ao repositório de ativos, configure a identidade gerenciada do serviço de pesquisa, conforme descrito em Configurar o repositório de ativos e o acesso ao aplicativo.

• A API REST 2026-08-01-preview ou um pacote de visualização de SDK do Azure equivalente: .NET | Java | JavaScript | Python

Limitações e considerações

• O fornecimento de imagens está disponível somente por meio da API retrieve na recuperação agêntica. As consultas clássicas /docs/search não fornecem imagens incorporadas ao documento para a síntese de respostas subsequente sem uma solução ou uma configuração personalizada.

• A veiculação de imagens funciona somente no modo de saída de síntese de resposta. O modo de saída extractiveData omite o fornecimento de imagens.

• O fornecimento de imagens aplica-se somente a fontes de conhecimento indexadas baseadas em arquivo que tenham o assetStore configurado e blocos indexados com valores de image_path preenchidos.

• Em bases de conhecimento mistas, somente os tipos de fontes de conhecimento compatíveis (blob, OneLake indexado e SharePoint indexado) fornecem imagens incorporadas aos documentos para a síntese de respostas subsequente. Outros tipos ainda podem contribuir para a fundamentação textual.

• A disponibilização de imagens não é compatível com fontes de conhecimento que usam ingestionPermissionOptions para importar permissões em nível de documento, incluindo ACLs, escopos RBAC ou rótulos de confidencialidade do Microsoft Purview. O repositório de ativos cria um repositório de conhecimento subjacente, e os repositórios de conhecimento não oferecem suporte à herança de permissões.

• O esquema da resposta de recuperação não define campos para os caminhos individuais das imagens no armazenamento de ativos nem para os bytes das imagens enviados ao modelo. A atividade imageServing apresenta estatísticas agregadas das imagens recuperadas e enviadas ao modelo.

• O acesso a imagens é controlado no nível da conta de armazenamento, independentemente do acesso ao conteúdo indexado. Qualquer identidade com acesso de leitura à conta de armazenamento de ativos pode obter suas imagens.

• Não armazene segredos (chaves de conta, tokens, cadeias de conexão) em documentos de origem porque o conteúdo pode ser retornado como dados de aterramento.

• O fornecimento de imagens pode aumentar a latência da síntese da resposta devido ao download de imagens e ao processamento de tokens multimodais. Execute consultas representativas com o serviço de imagem habilitado e desabilitado e compare a latência de resposta com a atividade relatada imageServing .

• A Compreensão de Conteúdo pode produzir resultados de imagem diferentes para arquivos PDF e DOCX. Se a extração e a verbalização consistentes de imagem inserida forem necessárias, converta documentos de origem em PDF ou teste cada formato de origem com conteúdo representativo.

Como funciona a entrega de imagens

O fornecimento de imagens tem duas fases:

• Indexação: quando você configura a extração de conteúdo padrão e um repositório de ativos em uma fonte de conhecimento, a habilidade de Compreensão de Conteúdo gerada agrupa semanticamente o documento, preserva tabelas como Markdown e usa a LLM configurada para descrever figuras inseridas. As descrições das figuras passam a fazer parte do Markdown enriquecido que é vetorizado pela habilidade de inserções. A habilidade também extrai imagens para o repositório de ativos de blob e adiciona referências image_path a partes sobrepostas.

  Quando você configura um repositório de ativos, o serviço de pesquisa também provisiona um repositório de conhecimento juntamente com a fonte de conhecimento para armazenar os artefatos de imagem extraídos. Você pode inspecionar e gerenciar esse repositório de conhecimento como qualquer outro.

• Recuperação: Quando a ação de recuperação é executada com o serviço de imagem habilitado, o serviço de pesquisa busca as imagens correspondentes do repositório de ativos, codifica-as em base64 e as inclui como conteúdo multimodal no prompt de síntese de resposta.

Configurar o repositório de ativos e o acesso ao aplicativo

O fornecimento de imagens abrange três fronteiras de confiança. No momento da indexação, o serviço Pesquisa grava artefatos de imagem no repositório de ativos. No momento da consulta, o serviço de pesquisa lê do repositório de ativos para recuperar imagens. Seu aplicativo também lê do armazenamento de recursos se precisar renderizar imagens na interface do usuário. Configure cada caminho para seguir o princípio do menor privilégio.

Acesso do serviço de pesquisa ao repositório de ativos

• Use o Microsoft Entra ID e uma identidade gerenciada para o serviço de pesquisa. Atribua à identidade a função Colaborador de dados de blob de armazenamento no escopo da conta de armazenamento, pois o indexador grava artefatos de imagem e a ação de recuperação os lê. Quando os contêineres de origem e de ativos estão na mesma conta, a função também fornece acesso de leitura ao blob de origem.

• Não habilite o acesso público anônimo no contêiner do repositório de ativos.

Acesso do aplicativo a referências de imagem

O índice gerado armazena image_path referências a imagens no repositório de ativos. O esquema da resposta de recuperação não define campos dedicados para os caminhos individuais das imagens no armazenamento de ativos nem para os bytes das imagens enviados ao modelo. O elemento opcional sourceData consiste em dados de referência estruturados, e image_path não é necessário nesses dados.

Para exibir uma imagem indexada em seu aplicativo:

1. Atribua a identidade do aplicativo à função Leitor de Dados do Blob de Armazenamento no escopo da conta de armazenamento de ativos.

2. Atribua a identidade do aplicativo a função Leitor de Dados de Índice de Pesquisa para que ele possa consultar o índice gerado.

3. Obtenha um image_path autorizado do índice gerado por meio de uma consulta controlada por aplicativo ou de um ponto de extremidade de serviço.

4. Valide se a referência é resolvida para a conta de armazenamento esperada e o contêiner de ativos. Rejeite caminhos não confiáveis antes da pesquisa de blob.

5. Busque o nome do blob resultante do contêiner de ativos usando a identidade do aplicativo.

Essa separação permite controlar quem pode exibir imagens de origem independentemente de quem pode chamar a API de recuperação.

Configurar o repositório de ativos em uma fonte de conhecimento

Configure assetStore em ingestionParameters de uma fonte de conhecimento indexada compatível. O repositório de ativos é um contêiner de blob que você possui e no qual o serviço Pesquisa grava artefatos de imagem.

Para obter instruções específicas da fonte, consulte:

• Criar uma fonte de conhecimento de blobs
• Criar uma fonte de conhecimento SharePoint indexada
• Criar uma fonte de conhecimento do OneLake

Uma fonte de conhecimento de blob mínima com o serviço de imagem habilitado tem esta aparência:

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"
      }
    }
  }
}

Resultados de configuração

A combinação de assetStore, disableImageVerbalizatione chatCompletionModel determina o que o indexador armazena e o que o modelo vê no momento da consulta:

• Repositório de ativos + verbalização (padrão):assetStore definido, disableImageVerbalization mantido como false, chatCompletionModel definido. O indexador mantém as imagens no repositório de ativos e armazena descrições de texto no índice. A atividade de busca pode informar verbalizationUsed como true.

• Somente loja de ativos:assetStore definido, disableImageVerbalization definido como true, chatCompletionModel não obrigatório. O indexador persiste imagens no repositório de ativos, mas não gera descrições de texto. A atividade de busca pode informar verbalizationUsed como false.

• Nenhum repositório de ativos, conjunto de modelos:assetStore não definido, chatCompletionModel definido. Somente descrições de texto, nenhum artefato de imagem. A veiculação de imagens não se aplica.

• Nenhum repositório de ativos, nenhum modelo: Nenhum processamento de imagem.

Verificar a configuração do repositório de ativos

Aguarde a conclusão da ingestão antes de continuar:

• Verifique o status do indexador no portal Azure ou use Get Indexer Status (API REST).

• Verifique se as partes indexadas têm um campo preenchido image_path . Se image_path estiver vazio, verifique o status do indexador, a configuração do repositório de ativos de origem de conhecimento, o conteúdo do documento de origem e o conteúdo do contêiner de ativos.

• Inspecione o contêiner do repositório de ativos. Você deve ver blobs de imagens que o indexador gravou durante o processo de ingestão.

Habilitar a disponibilização de imagens em uma base de conhecimento

Defina enableImageServing como true na referência da fonte de dados de conhecimento dentro da definição da base de dados de conhecimento. Essa configuração se torna o padrão para cada solicitação de recuperação direcionada à fonte de conhecimento.

A definição da base de dados de conhecimento também especifica o LLM usado para síntese de resposta no momento da consulta. Essa configuração é independente de qualquer chatCompletionModel que você defina no ingestionParameters da fonte de conhecimento, que controla a verbalização da imagem durante a indexação.

Se sua base de conhecimento se referir a várias fontes de conhecimento, defina enableImageServing somente em tipos indexados baseados em arquivo com suporte que tenham assetStore configurado. Tipos sem suporte (como índice de pesquisa, SharePoint remoto ou web) ainda contribuem com o embasamento textual, mas não fornecem imagens incorporadas aos documentos para a síntese de respostas subsequente.

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"
      }
    }
  ]
}

Verificar se a entrega de imagens está ativada

Envie uma GET requisição para o endpoint da base de conhecimento e verifique se a referência da fonte de conhecimento inclui "enableImageServing": true.

Recuperação com fornecimento de imagens

Execute a ação de recuperação na base de conhecimento. Para substituir o padrão da base de conhecimento para cada solicitação, defina enableImageServing na entrada correspondente em 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
    }
  ]
}

O que acontece no momento da recuperação

Para referências de imagem associadas ao conteúdo correspondente, o serviço de pesquisa baixa as imagens correspondentes do repositório de ativos, codifica-as em base64 e as passa como conteúdo multimodal para o modelo de síntese de resposta downstream. Inspecione estatísticas agregadas de veiculação de imagens em activity.imageServing. Para obter a forma exata de resposta, consulte a documentação de referência da Recuperação de Conhecimento – Recuperação (API REST).

Verificar o comportamento de recuperação

Uma resposta de recuperação pode fornecer os seguintes sinais de veiculação de imagem:

• Quando includeActivity é true, a matriz activity relata atividade imageServing para uma fonte de conhecimento quando o serviço registra operações de fornecimento de imagens.

• Um valor imagesSentToModel maior que 0 significa que o serviço indica que forneceu imagens ao modelo downstream de síntese de respostas.

Regras de precedência

Quando a definição da base de dados de conhecimento e a solicitação de recuperação especificam enableImageServing, o valor na solicitação de recuperação tem precedência. A precedência completa é:

1. O valor em knowledgeSourceParams[].enableImageServing na solicitação de recuperação (se estiver definido).
2. O valor na referência correspondente da fonte de conhecimento na definição da base de conhecimento (se definido).
3. false (o padrão).

A tabela a seguir resume as nove combinações.

Inspecionar estatísticas de fornecimento de imagens

Quando o fornecimento de imagens é executado, a resposta de recuperação inclui uma seção imageServing para cada fonte de conhecimento dentro da matriz activity. Use esta seção para comparar as imagens recuperadas do repositório de ativos com as imagens enviadas ao modelo.

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

O relatório dos campos:

• verbalizationUsed: a estatística de descrição textual da imagem relatada pelo serviço para a atividade de recuperação.

• imagesRetrieved: o número de imagens recuperadas do repositório de ativos.

• imagesSentToModel: o número de imagens enviadas para o modelo downstream.

• totalImageSizeBytes: o tamanho total, em bytes, das imagens enviadas para o modelo.

Se imagesRetrieved for maior que imagesSentToModel, nem todas as imagens recuperadas foram enviadas para o modelo.

Inspecione verbalizationUsed e imagesSentToModel independentemente. Uma resposta pode relatar tanto verbalizationUsed como true e uma ou mais imagens enviadas ao modelo.

Imagem de teste servindo de ponta a ponta

Use um dos seguintes exemplos para testar a configuração completa:

• Exemplo de serviço de imagem em C#
• Exemplo em Python de serviço de imagens

Os exemplos criam uma fonte de conhecimento de blobs e uma base de conhecimento, comparam solicitações de recuperação com o fornecimento de imagens desabilitado e habilitado e inspecionam estatísticas de fornecimento de imagens. Eles também usam uma consulta independente ao índice com curinga para selecionar um image_path e baixar esse ativo. Os exemplos selecionam uma referência delimitada por ponto e vírgula, removem de um caminho relativo um prefixo de projeção, como 11.7:, ou decodificam em URL um caminho absoluto e removem seu segmento inicial do contêiner de ativos. Essas transformações são comportamento de exemplo, não garantias da API de recuperação. O ativo selecionado não comprova que a mesma imagem contribuiu para uma determinada resposta de recuperação.

Uma lista de verificação de comparação A/B típica:

• Escolha uma pergunta que só pode ser respondida em um diagrama, gráfico ou imagem digitalizada.

• Execute a solicitação de recuperação com enableImageServing: false e capture a resposta.

• Execute a mesma solicitação de recuperação com enableImageServing: true e compare as respostas, a latência e a atividade relatada.

• Trate as diferenças de resposta como sinais de A/B observacionais, não a prova de que as imagens causaram as diferenças. Um valor imagesSentToModel maior que 0 indica que o serviço forneceu imagens ao modelo.

Limpar os recursos

Exclua a base de dados de conhecimento antes de excluir sua fonte de conhecimento. Excluir esses recursos Pesquisa de IA do Azure  não exclui documentos de origem nem blobs de imagem projetados em Armazenamento do Azure. Exclua esses blobs separadamente somente quando nenhum pipeline de ingestão ou recuperação retido ainda precisar deles.

Solução de problemas

Use o bloco de atividade imageServing de Inspecionar estatísticas de disponibilização de imagens como seu primeiro recurso de diagnóstico. A tabela a seguir lista verifica se há sintomas comuns sem assumir uma única causa.

Conteúdo relacionado

• Consultar uma base de dados de conhecimento
• Usar a síntese de respostas para respostas apoiadas por citação
• O que é uma fonte de conhecimento?
• Conceitos do repositório de conhecimento