Expor imagens incorporadas em documentos na recuperação agêntica (pré-visualização)

Utilize a disponibilização de imagens (pré-visualização) para apresentar imagens incorporadas nos seus documentos de origem (como diagramas, gráficos, infográficos, formulários digitalizados e imagens de produtos) durante a recuperação agêntica, para que o seu modelo de linguagem de grande dimensão (LLM) possa raciocinar com base no contexto visual em conjunto com o texto ao sintetizar uma resposta.

Quando ativa a disponibilização de imagens, o Pesquisa de IA do Azure:

• No momento da indexação, extrai imagens de documentos suportados e armazena-as numa loja de ativos Azure Blob fornecida pelo cliente.

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

Este artigo mostra-lhe como ativar o fornecimento de imagens numa base de conhecimento, substituí-lo para cada pedido, consultar as estatísticas de fornecimento de imagens e planear os requisitos do ciclo de vida da conta de armazenamento.

Suporte de utilização

Pré-requisitos

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

• Uma fonte de conhecimento indexada baseada em ficheiros configurada com um assetStore no ingestionParametersarquivo. Tipos suportados:

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

  Para origens de conhecimento blob que utilizam a extração padrão, cumpra os pré-requisitos da origem de conhecimento blob.

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

• Documentos fonte que contêm imagens extraíveis, como ficheiros PNG, ficheiros JPEG ou PDFs com imagens incorporadas.

• Um recurso Microsoft Foundry numa região suportada pelo Azure Content Understanding no Foundry Tools, com embedding Azure OpenAI e implementações de modelos de chat multimodais. Utilize o endpoint do recurso no formato https://<resource-name>.services.ai.azure.com.

• Permissão para criar ou atualizar a base de conhecimento e a fonte de conhecimento gerida. Configure a autenticação sem chave com as funções Contribuidor do Serviço de Pesquisa e Contribuidor de Dados do Índice de Pesquisa atribuídas ao utilizador ou à identidade de automatização que efetua estas operações de gestão (recomendado). Em alternativa, usa uma chave API de administrador.

• Permissão para chamar a ação de recuperação. Atribuir o papel de Leitor de Dados de Índice de Pesquisa à identidade que envia pedidos de recuperação (recomendado) ou usar uma chave API de consulta.

• Para chamadas de saída para o LLM durante a síntese de respostas, o serviço de pesquisa tem de ter uma identidade gerida com a permissão Cognitive Services User no recurso Microsoft Foundry que aloja o LLM.

• Para acesso à asset store, configure a identidade gerida do serviço de pesquisa conforme descrito em Configurar asset store e acesso à aplicação.

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

Limitações e considerações

• A disponibilização de imagens está disponível apenas através da API retrieve na recuperação agêntica. As consultas clássicas /docs/search não fornecem imagens incorporadas em documentos para síntese de respostas posteriores sem uma solução ou configuração personalizada.

• O fornecimento de imagens é executado apenas no modo de saída de síntese de respostas. O modo de saída extractiveData ignora o fornecimento de imagens.

• A disponibilização de imagens aplica-se apenas a fontes de conhecimento indexadas baseadas em ficheiros que tenham assetStore configurado e segmentos indexados com valores image_path preenchidos.

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

• O fornecimento de imagens não é suportado para fontes de conhecimento que utilizam ingestionPermissionOptions para assimilar permissões ao nível do documento, incluindo ACLs, âmbitos de RBAC ou etiquetas de confidencialidade do Microsoft Purview. O arquivo de recursos cria um arquivo de conhecimento subjacente, e os arquivos de conhecimento não suportam herança de permissões.

• O esquema da resposta de recuperação não define campos para os caminhos individuais das imagens do repositório de ativos nem para os bytes das imagens enviados ao modelo. Os imageServing relatórios de atividade agregam estatísticas para as imagens recuperadas e enviadas ao modelo.

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

• Não armazene segredos (chaves de conta, tokens, cadeias de ligação) em documentos-fonte, porque o conteúdo pode ser devolvido como dados de fundamentação.

• A aplicação de imagens pode aumentar a latência de síntese de respostas devido ao download de imagens e ao processamento multimodal de tokens. Execute consultas representativas com a função de imagem ativada e desativada e compare a latência de resposta com a atividade reportada imageServing .

• A Compreensão de Conteúdo pode produzir diferentes resultados de imagem para ficheiros PDF e DOCX. Se forem necessárias extrações consistentes de imagens embutidas e verbalização, converta documentos fonte para PDF ou teste cada formato fonte com conteúdo representativo.

Como funciona a disponibilização de imagens

O fornecimento de imagens tem duas fases:

• Indexação: Quando configura uma extração de conteúdo padrão e um armazenamento de recursos numa fonte de conhecimento, a competência Content Understanding gerada segmenta semanticamente o documento, preserva as tabelas em Markdown e usa o LLM configurado para descrever figuras incorporadas. As descrições das figuras passam a fazer parte do Markdown enriquecido que a habilidade de incorporação converte em vetores. A habilidade também extrai imagens para o teu stock de blob e adiciona image_path referências a blocos sobrepostos.

  Quando configura um asset store, o serviço de pesquisa também fornece um knowledge store juntamente com a fonte de conhecimento para persistir os artefactos da imagem extraída. Pode inspecionar e gerir este armazenamento de conhecimento como qualquer outro.

• Recuperação: Quando a ação de recuperação é executada com o serviço de imagem ativado, o serviço de pesquisa recolhe as imagens correspondentes da loja de ativos, codifica-as no base64 e inclui-as como conteúdo multimodal no prompt de síntese de respostas.

Configurar a loja de recursos e o acesso à aplicação

O fornecimento de imagens estende-se por três fronteiras de confiança. Durante a indexação, o serviço de pesquisa grava artefactos de imagem no seu armazenamento de recursos. No momento da consulta, o serviço de pesquisa lê do asset store para recuperar imagens. A tua aplicação também lê da asset store caso precise de renderizar imagens numa interface. Configure cada caminho para seguir o acesso com privilégio mínimo.

Acesso do serviço de pesquisa à loja de recursos

• Utilize o Microsoft Entra ID e uma identidade gerida para o serviço de pesquisa. Atribua à identidade o papel Storage Blob Data Contributor ao nível da conta de armazenamento, porque o indexador escreve artefactos de imagem e a operação de recuperação lê-os. Quando os contentores de origem e de ativos partilham essa conta, a função também fornece acesso de leitura ao blob de origem.

• Não ative o acesso público anónimo no contentor da asset store.

Acesso da aplicação a referências de imagem

O índice gerado armazena image_path referências a imagens na asset store. O esquema da resposta de recuperação não define campos dedicados para os caminhos individuais das imagens do armazenamento de recursos nem para os bytes das imagens enviados ao modelo. sourceData é opcional, são dados de referência estruturados, e image_path não é necessário nos mesmos.

Para mostrar uma imagem indexada na sua aplicação:

1. Atribua à identidade da sua aplicação a função Leitor de Dados de Blobs do Armazenamento ao nível da conta de armazenamento de ativos.

2. Atribua à identidade da sua aplicação o papel de Leitor de Dados de Índice de Pesquisa para que possa consultar o índice gerado.

3. Obtenha um image_path autorizado do índice gerado através de uma consulta controlada pela aplicação ou de um ponto final de serviço.

4. Verifique se a referência remete para a conta de armazenamento esperada e para o contentor de ativos. Rejeita caminhos não confiáveis antes da pesquisa por blob.

5. Obtenha o nome do blob resultante do contentor de ativos usando a identidade da sua aplicação.

Esta separação permite-lhe controlar quem pode visualizar as imagens de origem independentemente de quem pode chamar a API de recuperação.

Configure o armazenamento de ativos numa origem de conhecimento

Configure assetStore na ingestionParameters de uma fonte de conhecimento indexada suportada. O armazenamento de recursos é um contentor de blobs que lhe pertence e no qual o serviço de pesquisa escreve artefactos de imagem.

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

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

Uma fonte mínima de conhecimento de blob com o serviço de imagem ativado é assim:

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, disableImageVerbalization, e chatCompletionModel determina o que o indexador armazena e o que o modelo vê no momento da consulta:

• Loja de recursos + verbalização (predefinição):assetStore definido, disableImageVerbalization deixado como false, chatCompletionModel definido. O indexador mantém as imagens no asset store e armazena descrições de texto no índice. A atividade de recuperação pode reportar verbalizationUsed como true.

• Apenas na Asset Store:assetStore definido, disableImageVerbalization definido como true, chatCompletionModel não obrigatório. O indexador mantém as imagens na asset store, mas não gera descrições de texto. A atividade de recuperação pode reportar verbalizationUsed como false.

• Sem asset store, conjunto de modelos:assetStore não definido, chatCompletionModel definido. Apenas descrições em texto, sem artefactos de imagens. A disponibilização de imagens não se aplica.

• Sem asset store, sem modelo: Sem processamento de imagem.

Verificar a configuração da loja de recursos

Espere que a ingestão termine antes de continuar:

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

• Verifica se os chunks indexados têm um campo preenchido image_path . Se image_path estiver vazio, verifique o estado do indexador, a configuração do arquivo de recursos da origem de conhecimento, o conteúdo do documento de origem e o conteúdo do contentor de recursos.

• Inspecione o contentor da loja de recursos. Deverá ver os blobs de imagem que o indexador gravou durante a ingestão.

Ativar a disponibilização de imagens numa base de conhecimento

Defina enableImageServing como true na referência da origem de conhecimento na definição da base de conhecimento. Esta configuração torna-se o padrão para todos os pedidos de recuperação que visam a fonte de conhecimento.

A definição da base de conhecimento também especifica o LLM utilizado para síntese de respostas no momento da consulta. Esta configuração é independente de qualquer chatCompletionModel que definas na fonte ingestionParametersde conhecimento , o que impulsiona a verbalização das imagens durante a indexação.

Se a sua base de conhecimento fizer referência a várias fontes de conhecimento, defina enableImageServing apenas nos tipos indexados com base em ficheiros suportados que tenham assetStore configurado. Tipos não suportados (como índice de pesquisa, SharePoint remoto ou Web) continuam a contribuir para a ancoragem textual, mas não fornecem imagens incorporadas nos documentos para a síntese posterior de respostas.

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 a ativação do fornecimento de imagens

Envie um GET pedido ao endpoint da base de conhecimento e verifique se a referência da fonte de conhecimento inclui "enableImageServing": true.

Obter com disponibilização de imagens

Chama a ação de recuperação contra a base de conhecimento. Para substituir a predefinição da base de conhecimento para cada pedido, 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 imagens associadas ao conteúdo correspondente, o serviço de pesquisa descarrega as imagens correspondentes da asset store, codifica-as em base64 e passa-as como conteúdo multimodal para o modelo de síntese de respostas a jusante. Consulte estatísticas agregadas sobre o fornecimento de imagens em activity.imageServing. Para a forma exata da resposta, consulte a documentação de referência para Knowledge Retrieval - Retrieve (REST API).

Verificar comportamento de recuperação

Uma resposta de obtenção pode fornecer estes sinais para disponibilização de imagens:

• Quando includeActivity é activity, a matriz imageServing comunica atividade true para uma fonte de conhecimento quando o serviço regista operações de disponibilização de imagens.

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

Regras de precedência

Quando tanto a definição da base de conhecimento como o pedido de recuperação especificam enableImageServing, o valor no pedido de recuperação tem precedência. A precedência completa é:

1. O valor em knowledgeSourceParams[].enableImageServing no pedido de obtenção (se 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 seguinte resume as nove combinações.

Ver estatísticas de fornecimento de imagens

Quando o fornecimento de imagens é executado, a resposta de obtenção inclui uma secção imageServing para cada origem de conhecimento dentro da matriz activity. Use esta secção para comparar as imagens recuperadas da asset store com as imagens enviadas para o modelo.

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

Os campos indicam:

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

• imagesRetrieved: O número de imagens recuperadas do asset store.

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

• totalImageSizeBytes: O tamanho total, em bytes, das imagens enviadas ao modelo.

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

Inspecionar verbalizationUsed e imagesSentToModel de forma independente. Uma resposta pode indicar tanto verbalizationUsed como true e uma ou mais imagens enviadas ao modelo.

Testar a disponibilização de imagens de ponta a ponta

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

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

Os exemplos criam uma origem de conhecimento de blobs e uma base de conhecimento, comparam pedidos de obtenção com o fornecimento de imagens desativado e ativado e inspecionam estatísticas do fornecimento de imagens. Também utilizam uma consulta independente ao índice com caráteres universais para selecionar um image_path e transferir esse recurso. Os exemplos selecionam uma referência delimitada por ponto e vírgula, removem um prefixo de projeção como 11.7: de um caminho relativo ou descodificam em URL um caminho absoluto e removem o seu segmento inicial do contentor de recursos. Estas transformações são comportamentos de exemplo, não garantias da API de recuperação. O recurso selecionado não constitui prova de que a mesma imagem tenha contribuído para uma determinada resposta a uma operação de recuperação.

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

• Escolha uma pergunta que só possa ser respondida a partir de um diagrama, gráfico ou imagem digitalizada.

• Executa o pedido de recuperação com enableImageServing: false e recolhe a resposta.

• Executa o mesmo pedido de obtenção com enableImageServing: true e compara as respostas, a latência e a atividade comunicada.

• Tratar as diferenças de resposta como sinais observacionais A/B, não como prova de que as imagens causaram essas diferenças. Um imagesSentToModel valor superior a 0 significa que o serviço informa que forneceu imagens ao modelo.

Limpeza de recursos

Apague a base de conhecimento antes de apagar a respetiva fonte de conhecimento. Eliminar estes recursos do Pesquisa de IA do Azure não apaga documentos de origem nem blocos de imagens projetados no Armazenamento do Azure. Elimine esses blobs em separado apenas quando nenhuma pipeline de ingestão ou de obtenção de dados retida ainda necessitar deles.

Troubleshooting

Utilize o bloco de atividade imageServing de Inspecionar estatísticas de disponibilização de imagens como primeiro passo de diagnóstico. A tabela seguinte lista verificações para sintomas comuns sem assumir uma única causa.

Conteúdo relacionado

• Consultar uma base de conhecimento
• Use a síntese de respostas para respostas apoiadas por citações
• O que é uma fonte de conhecimento?
• Conceitos de armazenamento de conhecimento