Visa bilder inbäddade i dokument i agentbaserad hämtning (förhandsversion)

Använd bildvisning (förhandsversion) för att visa bilder som är inbäddade i dina källdokument (till exempel diagram, diagram, informationsgrafik, skannade formulär och produktbilder) under agentisk hämtning, så att din stora språkmodell (LLM) kan resonera över visuell kontext tillsammans med text när den syntetiserar ett svar.

När du aktiverar bildservering, Azure AI-sökning:

• Vid indexeringstillfället extraherar du avbildningar från dokument som stöds och lagrar dem i ett Azure Blob-tillgångslager som tillhandahålls av kunden.

• Vid frågetillfället hämtar dessa bilder under hämtningsåtgärden, base64-kodar dem och matar in dem som multimodalt innehåll i LLM-prompten som genererar det syntetiserade svaret.

Den här artikeln visar hur du aktiverar bildvisning på en kunskapsbas, åsidosätter den per begäran, inspekterar bildvisningsstatistik och planerar för livscykelkraven för lagringskontot.

Användningsstöd

Förutsättningar

• En Azure AI-sökning-tjänst med en kunskapsbas som anger en LLM. Kunskapsbasen måste använda svarssyntes.

• En filbaserad kunskapskälla med index som har konfigurerats med en assetStore i sin ingestionParameters. Typer som stöds:

  • Kunskapskälla för Blob (Azure Blob Storage eller Azure Data Lake Storage Gen2)
  • Indexerad OneLake-kunskapskälla
  • Indexerad SharePoint-kunskapskälla

  För Blob-kunskapskällor som använder standardextraktion ska du uppfylla förutsättningarna för Blob-kunskapskällan.

• Kunskapskällan får inte konfigurera ingestionPermissionOptions.

• Källdokument som innehåller extraherbara bilder, till exempel PNG-filer, JPEG-filer eller PDF-filer med inbäddade bilder.

• En Microsoft Foundry-resurs i en region som stöds av Azure Content Understanding i Foundry Tools, med Azure OpenAI-inbäddning och distributioner av multimodala chattmodeller. Använd resursslutpunkten i https://<resource-name>.services.ai.azure.com formatet .

• Behörighet att skapa eller uppdatera kunskapsbasen och den hanterade kunskapskällan. Konfigurera nyckellös autentisering med rollerna Search Service Contributor och Search Index Data Contributor som tilldelats användaren eller automationsidentiteten som utför dessa hanteringsåtgärder (rekommenderas). Du kan också använda en administratörs-API-nyckel.

• Behörighet att anropa åtgärden hämta. Tilldela rollen Dataläsare för sökindex till den identitet som skickar hämtningsbegäranden (rekommenderas) eller använd en fråge-API-nyckel.

• Vid utgående anrop till LLM vid svarsgenerering måste söktjänsten ha en hanterad identitet med behörigheten Cognitive Services User på Microsoft Foundry-resursen som är värd för LLM:et.

• För åtkomst till tillgångslager konfigurerar du söktjänstens hanterade identitet enligt beskrivningen i Konfigurera tillgångslager och programåtkomst.

• REST API för förhandsversionen 2026-08-01 eller motsvarande Azure SDKs förhandsversionspaket: .NET | Java | JavaScript | Python

Begränsningar och överväganden

• Bildleverans är endast tillgänglig via retrieve-API:et i agentbaserad hämtning. Klassiska /docs/search-frågor levererar inte bilder som är inbäddade i dokument till efterföljande svarsgenerering utan en anpassad lösning eller konfiguration.

• Bildvisning körs endast i utdataläge för svarssyntes . Utdataläget extractiveData hoppar över bildvisning.

• Bildleverans gäller endast för filbaserade indexerade kunskapskällor som har assetStore konfigurerade och indexerade segment med ifyllda värden för image_path.

• I blandade kunskapsbaser är det endast typer av kunskapskällor som stöds (blob, indexerade OneLake och indexerat SharePoint) som levererar bilder inbäddade i dokument till efterföljande svarssyntes. Andra typer kan fortfarande bidra med textgrundning.

• Bildvisning stöds inte för kunskapskällor som använder ingestionPermissionOptions för att mata in behörigheter på dokumentnivå, inklusive ACL:er, RBAC-omfång eller Microsoft Purview känslighetsetiketter. Resursarkivet skapar ett underliggande kunskapslager, och kunskapslager har inte stöd för behörighetsarv.

• Svarsschemat för hämtning definierar inte fält för enskilda sökvägar för tillgångslagerbilder eller bildbyte som skickas till modellen. Aktivitetsrapporterna imageServing aggregerar statistik för de bilder som hämtats och skickats till modellen.

• Åtkomsten till avbildningar styrs på lagringskontonivå, oberoende av åtkomst till indexerat innehåll. En identitet med läsåtkomst till lagringskontot för tillgångar kan hämta bilderna.

• Lagra inte hemligheter (kontonycklar, token, anslutningssträngar) i källdokument eftersom innehåll kan returneras som grunddata.

• Bildvisning kan öka svarssyntesfördröjningen på grund av bildnedladdning och bearbetning av multimodala token. Kör representativa frågor med bildservern aktiverad och inaktiverad och jämför svarssvarstid med den rapporterade imageServing aktiviteten.

• Content Understanding kan ge olika bildresultat för PDF- och DOCX-filer. Om konsekvent extrahering och verbalisering av inbäddade bilder krävs konverterar du källdokument till PDF eller testar varje källformat med representativt innehåll.

Så här fungerar bildservering

Bildvisning har två faser:

• Indexering: När du konfigurerar standardextrahering av innehåll och ett resurslager för en kunskapskälla delar den genererade Content Understanding-färdigheten upp dokumentet semantiskt, bevarar tabeller som Markdown och använder den konfigurerade LLM:n för att beskriva inbäddade figurer. Bildbeskrivningar utgör en del av det berikade Markdown-innehållet som inbäddningskompetensen vektoriserar. Färdigheten extraherar även bilder till blobtillgångsarkivet och lägger till image_path referenser till överlappande segment.

  När du konfigurerar ett tillgångslager etablerar söktjänsten även ett kunskapslager tillsammans med kunskapskällan för att bevara de extraherade bildartefakterna. Du kan inspektera och hantera det här kunskapsarkivet på samma sätt som andra.

• Hämtning: När hämtningsåtgärden körs med bildservern aktiverad hämtar söktjänsten matchande bilder från tillgångsarkivet, base64-kodar dem och inkluderar dem som multimodalt innehåll i svarssyntesprompten.

Konfigurera tillgångslager och programåtkomst

Bildvisning sträcker sig över tre förtroendegränser. Vid indexering skriver söktjänsten bildartefakter till din resurslagring. Vid frågetillfället läser söktjänsten från tillgångsarkivet för att hämta bilder. Ditt program läser också från tillgångsarkivet om det behöver återge bilder i ett användargränssnitt. Konfigurera varje sökväg så att den följer åtkomst med lägsta behörighet.

Söktjänståtkomst till tillgångsarkivet

• Använd Microsoft Entra ID och en hanterad identitet för söktjänsten. Tilldela identiteten rollen Storage Blob Data Contributor på lagringskontonivå eftersom indexeraren skriver bildartefakter och hämta-åtgärden läser dem. När källcontainern och tillgångscontainern delar samma konto ger rollen även läsåtkomst till källblobben.

• Aktivera inte anonym offentlig åtkomst i tillgångsarkivcontainern.

Programåtkomst till bildreferenser

Det genererade indexet lagrar image_path referenser till bilder i tillgångsarkivet. Svarsschemat för hämtning definierar inte dedikerade fält för enskilda sökvägar för tillgångslagerbilder eller bildbyte som skickas till modellen. Valfritt sourceData är strukturerade referensdata och image_path krävs inte i dem.

Så här visar du en indexerad bild i programmet:

1. Tilldela programmets identitet rollen Storage Blob Data Reader i omfånget för tillgångslagringskontot.

2. Tilldela programmets identitet rollen Dataläsare för sökindex så att det kan köra frågor mot det genererade indexet.

3. Hämta ett auktoriserat image_path från det genererade indexet via en programstyrd fråga eller slutpunkt.

4. Kontrollera att referensen matchar det förväntade lagringskontot och tillgångscontainern. Avvisa icke-betrodda sökvägar innan blobbsökningen.

5. Hämta det resulterande blobnamnet från tillgångscontainern med hjälp av programmets identitet.

Med den här separationen kan du styra vem som kan visa källbilder oberoende av vem som kan anropa hämtnings-API:et.

Konfigurera resurslagret för en kunskapskälla

Konfigurera assetStore i en ingestionParameters indexerad kunskapskälla som stöds. Lagringsarkivet är en blob-behållare som du äger och där söktjänsten skriver bildartefakter i.

För källspecifika instruktioner, se:

• Skapa en blob-kunskapskälla
• Skapa en indexerad SharePoint kunskapskälla
• Skapa en OneLake-kunskapskälla

En minimal blob-kunskapskälla med avbildningsservern aktiverad ser ut så här:

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

Konfigurationsresultat

Kombinationen av assetStore, disableImageVerbalizationoch chatCompletionModel avgör vad indexeraren lagrar och vad modellen ser vid frågetillfället:

• Resurslager + verbalisering (standard):assetStore inställd, disableImageVerbalization lämnad som false, chatCompletionModel inställd. Indexeraren sparar bilder i tillgångsarkivet och lagrar textbeskrivningar i indexet. Hämtningsaktivitet kan rapportera verbalizationUsed som true.

• Endast tillgångslager:assetStore ange, disableImageVerbalization ange till true, chatCompletionModel krävs inte. Indexeraren bevarar bilder i tillgångsarkivet men genererar inte textbeskrivningar. Hämtningsaktivitet kan rapportera verbalizationUsed som false.

• Inget resurslager, modelluppsättning:assetStore inte inställd, chatCompletionModel inställd. Endast textbeskrivningar, inga bildartefakter. Bildvisning gäller inte.

• Inget tillgångslager, ingen modell: Ingen bildbearbetning.

Verifiera konfiguration av tillgångslager

Vänta tills inmatningen har slutförts innan du fortsätter:

• Kontrollera indexerarens status i Azure-portalen eller använd Get Indexer Status (REST API).

• Kontrollera om indexerade segment har ett ifyllt image_path fält. Om image_path är tomt kontrollerar du indexerarens status, konfigurationen av kunskapskällans tillgångslager, innehållet i källdokumentet och innehållet i tillgångscontainern.

• Inspektera behållaren för Asset Store. Du bör se bildblobar som indexeraren skrev under inmatningen.

Aktivera bildservering på en kunskapsbas

Ställ in enableImageServing på true på kunskapskällereferensen i kunskapsbasdefinitionen. Den här inställningen blir standard för varje hämtningsbegäran som riktar sig till kunskapskällan.

Kunskapsbasdefinitionen anger också den LLM som används för svarssyntes vid frågetillfället. Den här inställningen är oberoende av några chatCompletionModel som du anger i kunskapskällans ingestionParameters, vilket styr bildverbalisering under indexeringen.

Om din kunskapsbas refererar till flera kunskapskällor ställer du in enableImageServing endast på de filbaserade indexerade typer som stöds och som har assetStore konfigurerat. Typer som inte stöds (till exempel sökindex, fjärranslutna SharePoint eller webben) bidrar fortfarande med textgrundning men tillhandahåller inte dokumentinbäddade bilder till nedströmssvarssyntesen.

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

Verifiera aktivering av bildserver

Skicka en GET begäran till kunskapsbasens slutpunkt och kontrollera att referensen för kunskapskällan innehåller "enableImageServing": true.

Hämta med bildvisning

Anropa hämtningsåtgärden mot kunskapsbasen. Om du vill åsidosätta standardvärdet för kunskapsbasen per begäran anger du enableImageServing den matchande posten under 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
    }
  ]
}

Vad händer vid hämtningstillfället?

För bildreferenser som är associerade med matchande innehåll laddar söktjänsten ned motsvarande bilder från tillgångsarkivet, base64-kodar dem och skickar dem som multimodalt innehåll till modellen för nedströmssvarssyntes. Granska sammanställd bildvisningsstatistik i activity.imageServing. Den exakta svarsformen finns i referensdokumentationen för Knowledge Retrieval – Retrieve (REST API).

Kontrollera hämtningsbeteendet

Ett svar på en hämtningsbegäran kan innehålla följande signaler för bildleverans:

• När includeActivity är truerapporterar imageServing matrisen activity aktivitet för en kunskapskälla när tjänsten registrerar åtgärder för bildservering.

• Ett imagesSentToModel värde som är större än 0 innebär att tjänsten rapporterar att den har angett bilder till modellen för nedströmssvarssyntes.

Prioritetsregler

När både kunskapsbasdefinitionen och hämtningsbegäran anger enableImageServinghar värdet i hämtningsbegäran företräde. Den fullständiga prioriteten är:

1. Värdet i knowledgeSourceParams[].enableImageServing på hämtningsbegäran (om det anges).
2. Värdet för referensen för matchande kunskapskälla i kunskapsbasdefinitionen (om det anges).
3. false (standardvärdet).

I följande tabell sammanfattas de nio kombinationerna.

Granska statistik för bildvisning

När bildservern körs innehåller hämtningssvaret ett imageServing avsnitt för varje kunskapskälla i matrisen activity . Använd det här avsnittet om du vill jämföra de bilder som hämtats från tillgångsarkivet med de bilder som skickas till modellen.

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

Fälten rapporterar:

• verbalizationUsed: Statistik över bildverbalisering rapporterad av tjänsten för hämtningsaktiviteten.

• imagesRetrieved: Antalet bilder som hämtats från tillgångsarkivet.

• imagesSentToModel: Antalet bilder som skickas till den underordnade modellen.

• totalImageSizeBytes: Den totala storleken, i byte, på bilderna som skickas till modellen.

Om imagesRetrieved är större än imagesSentToModelskickades inte alla hämtade avbildningar till modellen.

Inspektera verbalizationUsed och imagesSentToModel oberoende av varandra. Ett svar kan rapportera både verbalizationUsed som true och en eller flera bilder som skickas till modellen.

Testbildsleverans från ände till ände

Använd något av följande exempel för att testa den fullständiga installationen:

• Exempel på C#-bildservering
• Python-exempel för att servera bilder

Exemplen skapar en kunskapskälla för blobbar och en kunskapsbas, jämför hämtningsbegäranden med bildvisning inaktiverad respektive aktiverad och granskar statistik för bildvisning. De använder också en oberoende indexfråga med jokertecken för att välja ut en image_path och ladda ned resursen. Exemplen väljer en semikolonavgränsad referens, tar bort ett projektionsprefix, till exempel 11.7: från en relativ sökväg eller URL-avkodar en absolut sökväg och tar bort dess ledande segment för tillgångscontainer. Dessa transformeringar är exempelbeteende, inte garantier för hämtnings-API:et. Den valda resursen är inte ett belägg för att samma bild användes i svaret på en viss hämtningsförfrågan.

En typisk checklista för A/B-jämförelse:

• Välj en fråga som bara kan besvaras utifrån ett diagram, en tabell eller en skannad bild.

• Kör hämtningsbegäran med enableImageServing: false och samla in svaret.

• Kör samma hämtningsbegäran med enableImageServing: true och jämför svar, svarstid och rapporterad aktivitet.

• Behandla svarsskillnader som observationella A/B-signaler, inte bevis på att bilderna orsakade skillnaderna. Ett imagesSentToModel värde som är större än 0 innebär att tjänsten rapporterar att den har angett bilder till modellen.

Rensa resurser

Ta bort kunskapsbasen innan du tar bort dess kunskapskälla. Om du tar bort dessa Azure AI-sökning resurser tas inte källdokument eller projicerade bildblobar bort i Azure Storage. Ta endast bort dessa blobbar separat om ingen inläsnings- eller hämtningspipeline som behålls fortfarande behöver dem.

Troubleshooting

Använd aktivitetsblocket imageServing från Inspektera statistik för bildleverans som första diagnostiska steg. I följande tabell visas kontroller av vanliga symtom utan att anta en enda orsak.

Relaterat innehåll

• Fråga en kunskapsbas
• Använda svarssyntes för källhänvisningsbaserade svar
• Vad är en kunskapskälla?
• Begrepp för kunskapslager