Immagini incorporate nei documenti Surface nel recupero agentico (anteprima)

Usare la gestione delle immagini (anteprima) per visualizzare immagini incorporate nei documenti di origine (ad esempio diagrammi, grafici, infografiche, moduli analizzati e immagini del prodotto) durante il recupero agentico, in modo che il modello LLM (Large Language Model) possa ragionare sul contesto visivo insieme al testo quando sintetizza una risposta.

Quando si abilita la gestione delle immagini, Azure AI Search:

• Al momento dell'indicizzazione, estrae le immagini dai documenti supportati e le archivia in un archivio di asset BLOB fornito dal cliente Azure.

• In fase di query, recupera le immagini durante l'azione di recupero, le codifica base64 e le inserisce come contenutomultidimensionale nel prompt LLM che produce la risposta sintetizzata.

Questo articolo illustra come abilitare la gestione delle immagini in una Knowledge Base, eseguirne l'override per richiesta, esaminare le statistiche di gestione delle immagini e pianificare i requisiti del ciclo di vita dell'account di archiviazione.

Supporto per l'utilizzo

Prerequisiti

• Un servizio ricerca di intelligenza artificiale di Azure con una knowledge base che specifica un LLM. La Knowledge Base deve usare la sintesi delle risposte.

• Una fonte di conoscenza indicizzata basata su file configurata con un elemento assetStore all'interno del suo ingestionParameters. Tipi supportati:

  • Fonte di dati BLOB (Archiviazione BLOB di Azure o Azure Data Lake Storage Gen2)
  • Fonte di conoscenza di OneLake indicizzata
  • Fonte di conoscenza SharePoint indicizzata

  Per le fonti delle informazioni BLOB che usano l'estrazione standard, completare i prerequisiti delle fonti delle informazioni BLOB.

• La fonte delle informazioni non deve configurare ingestionPermissionOptions.

• Documenti di origine contenenti immagini estraibili, ad esempio file PNG, file JPEG o PDF con immagini incorporate.

• Una risorsa Microsoft Foundry in un'area supportata da Comprensione dei contenuti di Azure in Foundry Tools, con distribuzioni modelli di integrazione Azure OpenAI e chat multimodali. Usare l'endpoint della risorsa nel formato https://<resource-name>.services.ai.azure.com.

• Autorizzazione per creare o aggiornare la base di conoscenza e l'origine della conoscenza gestita. Configurare l'autenticazione senza chiave con i ruoli Collaboratore servizio di ricerca e Collaboratore ai dati dell'indice di ricerca assegnati all'identità utente o di automazione che esegue queste operazioni di gestione (scelta consigliata). In alternativa, usare una chiave API di amministrazione.

• Autorizzazione a richiamare l'azione di recupero. Assegna il ruolo Search Index Data Reader all'identità che invia richieste di recupero (scelta consigliata) oppure usa una chiave API di query.

• Per le chiamate in uscita al LLM durante la sintesi della risposta, il servizio di ricerca deve disporre di un'identità gestita con le autorizzazioni Utente di Servizi cognitivi sulla risorsa Microsoft Foundry che ospita il LLM.

• Per l'accesso all'archivio asset, configurare l'identità gestita del servizio di ricerca come descritto in Configurare l'archivio asset e l'accesso alle applicazioni.

• L'API REST 2026-08-01-preview o un pacchetto di anteprima di Azure SDK equivalente: .NET | Java | JavaScript | Python

Limitazioni e considerazioni

• La gestione delle immagini è disponibile solo tramite l'API retrieve nel recupero agentico. Le query classiche /docs/search non forniscono immagini incorporate in documenti per la sintesi delle risposte downstream senza una soluzione o una configurazione personalizzata.

• La gestione delle immagini viene eseguita solo in modalità di output di sintesi delle risposte . La modalità di output extractiveData salta la visualizzazione delle immagini.

• La pubblicazione delle immagini si applica solo alle fonti di conoscenza indicizzate basate su file che presentano il tag assetStore configurato e blocchi indicizzati con valori image_path compilati.

• Nelle basi di conoscenza miste, solo i tipi di origine della conoscenza supportati (blob, OneLake indicizzato e SharePoint indicizzato) forniscono immagini incorporate nei documenti per la sintesi delle risposte a valle. Anche altri tipi possono contribuire al grounding del testo.

• La gestione delle immagini non è supportata per le fonti delle informazioni che usano ingestionPermissionOptions per inserire autorizzazioni a livello di documento, inclusi ACL, ambiti RBAC o etichette di riservatezza di Microsoft Purview. L'archivio asset crea un archivio conoscenze sottostante e gli archivi conoscenze non supportano l'eredità delle autorizzazioni.

• Lo schema della risposta di recupero non definisce i campi per i singoli percorsi delle immagini del repository di asset oppure per i byte delle immagini inviati al modello. L'attività imageServing segnala statistiche aggregate per le immagini recuperate e inviate al modello.

• L'accesso alle immagini viene controllato a livello di account di archiviazione, indipendentemente dall'accesso al contenuto indicizzato. Qualsiasi identità con accesso in lettura all'account di archiviazione asset può ottenere le relative immagini.

• Non archiviare segreti (chiavi dell'account, token, stringhe di connessione) nei documenti di origine perché il contenuto può essere restituito come dati di base.

• La fornitura delle immagini può aumentare la latenza nella sintesi delle risposte a causa del download delle immagini e dell'elaborazione dei token multimodali. Eseguire query rappresentative con la gestione delle immagini abilitata e disabilitata e confrontare la latenza di risposta con l'attività segnalata imageServing .

• Content Understanding può produrre risultati di immagine diversi per i file PDF e DOCX. Se è necessaria l'estrazione coerente di immagini incorporate e la verbalizzazione, convertire i documenti di origine in PDF o testare ogni formato di origine con contenuto rappresentativo.

Funzionamento della gestione delle immagini

La gestione delle immagini ha due fasi:

• Indicizzazione: quando si configurano l'estrazione standard del contenuto e un archivio di asset in una fonte delle informazioni, la competenza Comprensione dei contenuti generata suddivide semanticamente il documento, preserva le tabelle in formato Markdown e usa l'LLM configurato per descrivere le figure integrate. Le descrizioni delle figure diventano parte del Markdown arricchito che la competenza di integrazione vettorizza. La competenza estrae inoltre le immagini nell'archivio risorse BLOB e aggiunge riferimenti image_path ai blocchi sovrapposti.

  Quando si configura un archivio delle risorse, il servizio di ricerca crea anche un archivio delle conoscenze accanto alla fonte di conoscenza per conservare gli artefatti delle immagini estratti. È possibile esaminare e gestire questo archivio conoscenze come qualsiasi altro.

• Recupero: Quando l'azione di recupero viene eseguita con la gestione delle immagini abilitata, il servizio di ricerca recupera le immagini corrispondenti dall'archivio asset, le codifica base64 e le include come contenutomultidimensionale nella richiesta di sintesi delle risposte.

Configurare l'archivio delle risorse e l'accesso alle applicazioni

Il servizio di immagini si estende su tre confini di affidabilità. Al momento dell'indicizzazione, il servizio di ricerca salva gli artefatti delle immagini nel tuo archivio risorse. Al momento della query, il servizio di ricerca legge dall'archivio delle risorse per recuperare le immagini. L'applicazione legge anche dall'asset store se deve renderizzare immagini in un'interfaccia utente. Configurare ogni percorso per seguire l'accesso con privilegi minimi.

Accesso del servizio di ricerca all'asset store

• Usa Microsoft Entra ID e una managed identity per il servizio di ricerca. Assegnare all'identità il ruolo Collaboratore dati BLOB di Archiviazione a livello dell'account di archiviazione perché l'indicizzatore scrive gli artefatti immagine e l'azione di recupero li legge. Quando i contenitori di origine e risorse condividono tale account, il ruolo fornisce anche l'accesso in lettura ai BLOB di origine.

• Non abilitare l'accesso pubblico anonimo sul contenitore dell'asset store.

Accesso dell'applicazione ai riferimenti alle immagini

L'indice generato memorizza image_path i riferimenti alle immagini nell'asset store. Lo schema della risposta di recupero non definisce campi dedicati né per i singoli percorsi delle immagini nell'archivio delle risorse né per i byte delle immagini inviati al modello. Facoltativo sourceData è costituito da dati di riferimento strutturati e image_path non è necessario al suo interno.

Per visualizzare un'immagine indicizzata nell'applicazione:

1. Assegnare all'identità dell'applicazione il ruolo Lettore dati BLOB di archiviazione nell'ambito dell'account di archiviazione risorse.

2. Assegnare l'identità dell'applicazione al ruolo lettore di dati dell'indice di ricerca in modo che possa eseguire query sull'indice generato.

3. Ottenere un image_path autorizzato dall'indice generato tramite una query controllata dall'applicazione o un endpoint di servizio.

4. Verificare che il riferimento si risolva nell'account di archiviazione previsto e nel contenitore di asset. Rifiutare i percorsi non affidabili prima della ricerca del BLOB.

5. Recuperare il nome BLOB risultante dal contenitore asset tramite l'identità dell'applicazione.

Questa separazione consente di controllare chi può visualizzare le immagini di origine indipendentemente da chi può chiamare l'API di recupero.

Configurare l'archivio risorse su una fonte di conoscenza

Configurare assetStore nella ingestionParameters di una fonte di conoscenza indicizzata supportata. L'Asset Store è un contenitore di blob di tua proprietà in cui il servizio di ricerca salva gli artefatti immagine.

Per istruzioni specifiche della fonte, vedere:

• Creare una sorgente di conoscenza BLOB
• Creare una fonte di conoscenza indicizzata in SharePoint
• Crea una fonte di conoscenza OneLake

Ecco come si presenta una sorgente di dati BLOB minimale con la funzione di pubblicazione delle immagini abilitata:

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

Risultati della configurazione

La combinazione di assetStore, disableImageVerbalization e chatCompletionModel determina ciò che l'indicizzatore archivia e ciò che il modello vede in fase di query:

• Asset Store + verbalizzazione (impostazione predefinita):assetStore impostato, disableImageVerbalization lasciato come false, chatCompletionModel impostato. L'indicizzatore mantiene le immagini nell'archivio asset e archivia le descrizioni di testo nell'indice. L'attività di recupero può segnalare verbalizationUsed come true.

• Solo Asset Store:assetStore impostato, disableImageVerbalization impostato su true, chatCompletionModel non richiesto. L'indicizzatore rende persistenti le immagini nell'archivio asset, ma non genera descrizioni di testo. L'attività di recupero può segnalare verbalizationUsed come false.

• Nessun Asset Store, set di modelli:assetStore non impostato, chatCompletionModel impostato. Solo descrizioni di testo, nessun artefatto di immagine. La pubblicazione delle immagini non è prevista.

• Nessun archivio di asset, nessun modello: Nessuna elaborazione di immagini.

Verificare la configurazione dell'archivio risorse

Attendere il completamento dell'importazione prima di continuare:

• Controllare lo stato dell'indicizzatore nel portale Azure o usare Get Indexer Status (API REST).

• Controllare se i blocchi indicizzati hanno un campo popolato image_path . Se image_path è vuoto, controlla lo stato dell'indicizzatore, la configurazione dell'asset store della fonte di conoscenza, i contenuti del documento di origine e i contenuti del contenitore di asset.

• Ispezionare il contenitore dell'Asset Store. Dovresti vedere delle macchie di immagini che l'indicizzatore ha creato durante l'acquisizione.

Abilitare la gestione delle immagini in una Knowledge Base

Impostare enableImageServing su true nel riferimento alla fonte di conoscenza all'interno della definizione della base di conoscenza. Questa impostazione diventa l'impostazione predefinita per ogni richiesta di recupero destinata all'origine delle informazioni.

La definizione della knowledge base specifica anche l'LLM usato per la sintesi delle risposte in fase di query. Questa impostazione è indipendente da qualsiasi elemento chatCompletionModel impostato nell'elemento ingestionParametersdella fonte di conoscenza, che determina la verbalizzazione delle immagini durante l'indicizzazione.

Se la tua knowledge base fa riferimento a più fonti di conoscenza, imposta enableImageServing solo sui tipi indicizzati basati su file supportati per i quali è stato configurato assetStore. Le tipologie non supportate (ad esempio l'indice di ricerca, SharePoint remoto o il web) contribuiscono comunque al grounding testuale, ma non forniscono immagini incorporate nei documenti per la successiva sintesi delle risposte.

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

Verificare l'abilitazione della gestione delle immagini

Inviare una GET richiesta all'endpoint della Knowledge Base e verificare che il riferimento all'origine della knowledge base includa "enableImageServing": true.

Recupera con il servizio immagini

Esegui l'azione retrieve sulla base di conoscenza. Per eseguire l'override dell'impostazione predefinita della Knowledge Base per ogni richiesta, impostare enableImageServing nella voce corrispondente in 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
    }
  ]
}

Cosa accade in fase di recupero

Per i riferimenti alle immagini associati al contenuto corrispondente, il servizio di ricerca scarica le immagini corrispondenti dall'archivio asset, le codifica base64 e le passa come contenuto bidirezionale al modello di sintesi risposte downstream. Esaminare le statistiche aggregate di gestione immagini in activity.imageServing. Per la forma di risposta esatta, vedere la documentazione di riferimento per Il recupero delle informazioni - Recuperare (API REST).

Verifica del comportamento di recupero

Una risposta di recupero può fornire questi segnali di gestione delle immagini:

• Quando includeActivity è true, la matrice imageServing segnala attività activity per una fonte di conoscenza quando il servizio registra operazioni di distribuzione delle immagini.

• Un valore imagesSentToModel superiore a 0 indica che il servizio segnala di aver fornito immagini al modello downstream di sintesi delle risposte.

Regole di precedenza

Quando sia la definizione della knowledge base che la richiesta di recupero specificano enableImageServing, il valore nella richiesta di recupero ha la precedenza. La precedenza completa è:

1. Valore in knowledgeSourceParams[].enableImageServing nella richiesta di recupero (se impostato).
2. Il valore del riferimento alla fonte di conoscenza corrispondente nella definizione della base di conoscenza (se impostato).
3. false (impostazione predefinita).

La tabella seguente riepiloga le nove combinazioni.

Esaminare le statistiche di gestione delle immagini

Quando viene eseguita la distribuzione delle immagini, la risposta di recupero include una sezione imageServing per ogni origine di conoscenza all'interno dell'array activity. Usare questa sezione per confrontare le immagini recuperate dall'archivio asset con le immagini inviate al modello.

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

Il rapporto sui campi:

• verbalizationUsed: statistica della verbalizzazione immagini riportata dal servizio per l'attività di recupero.

• imagesRetrieved: numero di immagini recuperate dall'archivio asset.

• imagesSentToModel: numero di immagini inviate al modello downstream.

• totalImageSizeBytes: dimensione totale, in byte, delle immagini inviate al modello.

Se imagesRetrieved è maggiore di imagesSentToModel, non tutte le immagini recuperate sono state inviate al modello.

Ispezionare verbalizationUsed e imagesSentToModel indipendentemente. Una risposta può segnalare sia verbalizationUsed come true che una o più immagini inviate al modello.

Gestione delle immagini di prova dall'inizio alla fine

Usare uno degli esempi seguenti per testare la configurazione completa:

• Esempio di gestione delle immagini C#
• Python esempio di gestione delle immagini

Gli esempi creano una fonte delle informazioni knowledge base, confrontano le richieste di recupero con la gestione immagini disabilitata e abilitata ed esaminano le statistiche della gestione immagini. Usano anche una query di indice con caratteri jolly indipendenti per selezionare un image_path e scaricare tale asset. Gli esempi selezionano un riferimento delimitato da punto e virgola, rimuovono un prefisso di proiezione come 11.7: da un percorso relativo oppure eseguono la decodifica URL di un percorso assoluto e ne rimuovono il segmento iniziale asset-container. Queste trasformazioni sono un comportamento di esempio, non garanzie dell'API di recupero. L'asset selezionato non dimostra che la stessa immagine ha contribuito a una particolare risposta di recupero.

Una classica checklist per il confronto A/B:

• Selezionare una domanda a cui è possibile rispondere solo da un diagramma, un grafico o un'immagine analizzata.

• Eseguire la richiesta di recupero con enableImageServing: false e acquisire la risposta.

• Eseguire la stessa richiesta di recupero con enableImageServing: true e confrontare le risposte, la latenza e l'attività segnalata.

• Considerare le differenze di risposta come segnali A/B osservazionali, non la prova che le immagini hanno causato le differenze. Un imagesSentToModel valore maggiore di 0 indica che il servizio segnala che ha fornito immagini al modello.

Pulire le risorse

Eliminare la base di conoscenza prima di eliminare la relativa fonte di conoscenza. L'eliminazione di queste risorse Azure AI Search non elimina i documenti di origine o i BLOB di immagini proiettati in Archiviazione di Azure. Eliminare questi BLOB separatamente solo quando nessuna pipeline di acquisizione o di recupero mantenuta richiede ancora tali BLOB.

Risoluzione dei problemi

Come primo passo diagnostico, utilizza il blocco di attività imageServing da Esamina le statistiche di distribuzione delle immagini. Nella tabella seguente sono elencati i controlli per i sintomi comuni senza presupporre una singola causa.

Contenuti correlati

• Interrogare una base di conoscenza
• Usare la sintesi delle risposte per le risposte supportate dalla citazione
• Che cos'è un'origine delle conoscenze?
• Concetti relativi all'archivio conoscenze