Weergeven van in documenten ingesloten afbeeldingen in agentgestuurd ophalen (preview)

Gebruik afbeeldingslevering (preview) om afbeeldingen die in uw brondocumenten zijn ingesloten (zoals diagrammen, grafieken, infographics, gescande formulieren en productafbeeldingen) beschikbaar te maken tijdens agentische retrieval, zodat uw large language model (LLM) kan redeneren op basis van visuele context naast tekst wanneer het een antwoord samenstelt.

Wanneer u het leveren van afbeeldingen inschakelt, Azure AI Zoeken:

• Bij het indexeren worden afbeeldingen uit ondersteunde documenten geëxtraheerd en opgeslagen in een door de klant geleverde Azure Blob Asset Store.

• Tijdens het uitvoeren van een query worden deze afbeeldingen opgehaald tijdens de retrieve-actie, base64-gecodeerd en als multimodale inhoud toegevoegd aan de LLM-prompt die het gesynthetiseerde antwoord produceert.

In dit artikel wordt uitgelegd hoe u het aanbieden van afbeeldingen voor een kennisbank inschakelt, dit per aanvraag kunt overschrijven, statistieken over het aanbieden van afbeeldingen kunt bekijken en rekening kunt houden met de levenscyclusvereisten van het opslagaccount.

Gebruiksondersteuning

Prerequisites

• Een Azure AI Zoeken-service met een knowledge base waarmee een LLM wordt opgegeven. De Knowledge Base moet antwoordsynthese gebruiken.

• Een bestandgebaseerde geïndexeerde kennisbron die is geconfigureerd met een assetStore in de ingestionParameters ervan. Ondersteunde soorten:

  • Blob-kennisbron (Azure Blob Storage of Azure Data Lake Storage Gen2)
  • Geïndexeerde OneLake-kennisbron
  • Geïndexeerde SharePoint-kennisbron

  Voor blob-kennisbronnen die gebruikmaken van standaardextractie, moet u de vereisten voor de blob-kennisbron voltooien.

• De kennisbron mag ingestionPermissionOptions niet configureren.

• Brondocumenten die uitpakkende afbeeldingen bevatten, zoals PNG-bestanden, JPEG-bestanden of PDF-bestanden met ingesloten afbeeldingen.

• Een Microsoft Foundry-resource in een regio die wordt ondersteund door Azure Content Understanding in Foundry Tools, met Azure OpenAI-insluiting en multimodale chatmodelimplementaties. Gebruik het eindpunt van de resource in de notatie https://<resource-name>.services.ai.azure.com.

• Machtiging voor het maken of bijwerken van de knowledge base en beheerde kennisbron. Configureer sleutelloze verificatie met de rollen Inzender voor zoekservice en Inzender voor zoekindexgegevens die zijn toegewezen aan de identiteit van de gebruiker of automatisering die deze beheerbewerkingen uitvoert (aanbevolen). U kunt ook een beheer-API-sleutel gebruiken.

• Toestemming om de actie 'retrieve' aan te roepen. Wijs de rol Search Index Data Reader toe aan de identiteit waarmee aanvragen voor ophalen worden verzonden (aanbevolen) of gebruik een query-API-sleutel.

• Voor uitgaande aanroepen naar de LLM tijdens antwoordsynthese moet de zoekservice beschikken over een beheerde identiteit met Cognitive Services User-machtigingen op de Microsoft Foundry-resource waarop de LLM wordt gehost.

• Voor toegang tot de asset store configureert u de beheerde identiteit van de zoekservice, zoals beschreven in Asset store en toegang tot toepassingen configureren.

• De REST API 2026-08-01-preview of een equivalent Azure SDK preview-pakket: .NET | Java | JavaScript | Python

Beperkingen en overwegingen

• Het aanbieden van afbeeldingen is alleen beschikbaar via de retrieve API binnen agentische retrieval. Klassieke /docs/search-query’s stellen in documenten ingesloten afbeeldingen niet beschikbaar voor verdere antwoordsynthese zonder aangepaste oplossing of configuratie.

• Het serveren van afbeeldingen werkt alleen in de uitvoermodus antwoordsynthese. In de extractiveData uitvoermodus wordt de weergave van afbeeldingen overgeslagen.

• Het aanbieden van afbeeldingen is alleen van toepassing op bestandsgebaseerde geïndexeerde kennisbronnen waarvoor assetStore is geconfigureerd en waarvan geïndexeerde segmenten gevulde image_path-waarden bevatten.

• In gemengde kennisbanken leveren alleen ondersteunde typen kennisbronnen (blob, geïndexeerde OneLake en geïndexeerde SharePoint) in documenten ingesloten afbeeldingen voor de daaropvolgende antwoordsynthese. Andere typen kunnen nog steeds bijdragen aan tekstuele verankering.

• Het aanbieden van afbeeldingen wordt niet ondersteund voor kennisbronnen die ingestionPermissionOptions gebruiken om machtigingen op documentniveau op te nemen, waaronder ACL's, RBAC-bereiken of Microsoft Purview-gevoeligheidslabels. Het assetarchief maakt een onderliggend kennisarchief en kennisarchieven bieden geen ondersteuning voor overname van machtigingen.

• Het responseschema voor ophalen definieert geen velden voor de afzonderlijke paden naar asset-store-afbeeldingen of voor afbeeldingsbytes die naar het model worden verzonden. De imageServing activiteitenrapporten aggregeren statistieken voor de afbeeldingen die zijn opgehaald en verzonden naar het model.

• Toegang tot afbeeldingen wordt beheerd op opslagaccountniveau, onafhankelijk van toegang tot geïndexeerde inhoud. Elke identiteit met leestoegang tot het opslagaccount voor assets kan de afbeeldingen ophalen.

• Sla geen geheimen (accountsleutels, tokens, verbindingsreeksen) op in brondocumenten omdat inhoud kan worden geretourneerd als grondgegevens.

• Het leveren van afbeeldingen kan de latentie van antwoordsynthese verhogen vanwege het downloaden van afbeeldingen en multimodale tokenverwerking. Voer representatieve query's uit met het serveren van afbeeldingen in- en uitgeschakeld en vergelijk de responslatentie met de gerapporteerde imageServing-activiteit.

• Content Understanding kan verschillende afbeeldingsresultaten produceren voor PDF- en DOCX-bestanden. Als consistente extractie van ingesloten afbeeldingen en de tekstuele beschrijving daarvan vereist zijn, zet brondocumenten dan om naar PDF of test elk bronformaat met representatieve inhoud.

Hoe het bedienen van afbeeldingen werkt

Het leveren van afbeeldingen bestaat uit twee fasen:

• Indexering: Wanneer u standaardinhoudextractie en een assetarchief configureert voor een kennisbron, wordt het document door de gegenereerde vaardigheid Content Understanding semantisch gesegmenteerd, worden tabellen bewaard als Markdown en wordt de geconfigureerde LLM gebruikt om ingesloten afbeeldingen te beschrijven. Afbeeldingsbeschrijvingen maken deel uit van de verrijkte Markdown die door de embeddingvaardigheid wordt gevectoriseerd. De vaardigheid extraheert ook afbeeldingen naar uw blob-opslag voor assets en voegt image_path-verwijzingen toe aan overlappende segmenten.

  Wanneer u een assetarchief configureert, richt de zoekservice naast de kennisbron ook een kennisarchief in om de geëxtraheerde afbeeldingsartefacten te behouden. U kunt dit kennisarchief als elke andere inspecteren en beheren.

• Ophalen: Wanneer de actie ophalen wordt uitgevoerd met het leveren van afbeeldingen ingeschakeld, haalt de zoekservice de overeenkomende afbeeldingen op uit het assetarchief, codeert base64 deze en bevat deze als multimodale inhoud in de antwoordsyntheseprompt.

Assetstore en applicatietoegang configureren

Het aanbieden van afbeeldingen omvat drie vertrouwensgrenzen. Tijdens het indexeren schrijft de zoekservice afbeeldingsartefacten naar uw assetarchief. Tijdens de query leest de zoekservice uit het assetarchief om afbeeldingen op te halen. Uw toepassing leest ook uit het assetarchief als deze afbeeldingen in een gebruikersinterface moet weergeven. Configureer elk pad om toegang met minimale bevoegdheden te volgen.

Zoekservicetoegang tot het assetarchief

• Gebruik Microsoft Entra ID en een beheerde identiteit voor de zoekservice. Wijs de rol Storage Blob Data Contributor toe aan de identiteit op het niveau van het opslagaccount, omdat de indexer afbeeldingsartefacten schrijft en de ophaalactie deze artefacten leest. Wanneer de bron- en assetcontainers hetzelfde account delen, biedt de rol ook leesrechten op de bron-blob.

• Schakel anonieme openbare toegang voor de asset store-container niet in.

Toepassingstoegang tot afbeeldingsverwijzingen

De gegenereerde index slaat image_path verwijzingen naar afbeeldingen in de assetstore op. Het responseschema van de ophaalbewerking definieert geen specifieke velden voor de afzonderlijke afbeeldingspaden in de asset-store of de afbeeldingsbytes die naar het model worden gestuurd. Optioneel sourceData zijn gestructureerde referentiegegevens en image_path zijn hierin niet vereist.

Een geïndexeerde afbeelding weergeven in uw toepassing:

1. Ken aan de identiteit van uw toepassing de rol Storage Blob Data Reader toe op het niveau van het asset-opslagaccount.

2. Wijs de identiteit van uw toepassing toe aan de rol Search Index Data Reader , zodat deze een query kan uitvoeren op de gegenereerde index.

3. Haal een geautoriseerd image_path op uit de gegenereerde index via een toepassingsgestuurde query of service-eindpunt.

4. Controleer of de verwijzing naar het verwachte opslagaccount en de assetcontainer verwijst. Wijs onvertrouwde paden af vóór de blob-zoekopdracht.

5. Haal de resulterende blobnaam op uit de assetcontainer met behulp van de identiteit van uw toepassing.

Dankzij deze scheiding kunt u bepalen wie de bronafbeeldingen kan bekijken, onafhankelijk van wie de retrieve-API kan aanroepen.

Het assetarchief op een kennisbron configureren

Configureer assetStore in de ingestionParameters van een ondersteunde geïndexeerde kennisbron. Het assetarchief is een blobcontainer die u bezit en waarnaar de zoekservice afbeeldingsartefacten schrijft.

Zie voor bronspecifieke instructies:

• Een blob-kennisbron maken
• Maak een geïndexeerde SharePoint kennisbron
• Een OneLake-kennisbron maken

Een minimale blob-kennisbron met ingeschakelde afbeeldingsweergave ziet er als volgt uit:

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

Resultaten van de configuratie

De combinatie van assetStore, disableImageVerbalization en chatCompletionModel bepaalt wat de indexeerder opslaat en wat het model ziet tijdens querytijd:

• Asset store + verbale weergave (standaard):assetStore ingesteld, disableImageVerbalization gelaten als false, chatCompletionModel ingesteld. De indexeerfunctie bewaart afbeeldingen in het activaarchief en slaat tekstbeschrijvingen op in de index. Ophaalactiviteit kan verbalizationUsed rapporteren als true.

• Alleen assetstore:assetStore ingesteld, disableImageVerbalization ingesteld op true, chatCompletionModel niet vereist. De indexeerfunctie bewaart afbeeldingen in het assetarchief, maar genereert geen tekstbeschrijvingen. Ophaalactiviteit kan verbalizationUsed rapporteren als false.

• Geen assetopslag, modelverzameling:assetStore niet ingesteld, chatCompletionModel ingesteld. Alleen tekstbeschrijvingen, geen afbeeldingsartefacten. Het leveren van afbeeldingen is niet van toepassing.

• Geen activaarchief, geen model: Geen afbeeldingsverwerking.

De configuratie van de assetstore verifiëren

Wacht totdat de opname is voltooid voordat u doorgaat:

• Controleer de status van de indexeerfunctie in de Azure portal of gebruik Get IndexerStatus (REST API).

• Controleer of geïndexeerde segmenten een ingevuld image_path veld hebben. Als image_path leeg is, controleer dan de indexeerstatus, de configuratie van de assetopslag van de kennisbron, de inhoud van het brondocument en de inhoud van de assetcontainer.

• Controleer de container van de assetstore. U zou afbeeldingsblobs moeten zien die de indexer tijdens de opnamefase heeft geschreven.

Het weergeven van afbeeldingen inschakelen in een kennisbank

Stel enableImageServing in op true in de verwijzing naar de kennisbron in de definitie van de kennisbank. Deze instelling wordt de standaardinstelling voor elke ophaalaanvraag die is gericht op de kennisbron.

De definitie van de Knowledge Base geeft ook de LLM op die wordt gebruikt voor antwoordsynthese tijdens het uitvoeren van query's. Deze instelling is onafhankelijk van de chatCompletionModel instellingen die u instelt op de kennisbron ingestionParameters, waardoor de verbalisatie van afbeeldingen tijdens het indexeren wordt aangezet.

Als uw kennisbank verwijst naar meerdere kennisbronnen, stelt u enableImageServing alleen in voor ondersteunde, op bestanden gebaseerde geïndexeerde typen waarvoor assetStore is geconfigureerd. Niet-ondersteunde soorten (zoals zoekindex, externe SharePoint of web) dragen nog steeds bij aan tekstgronding, maar leveren geen in documenten ingesloten afbeeldingen aan downstreamantwoordsynthese.

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

Controleren of het leveren van afbeeldingen is ingeschakeld

Stuur een GET verzoek naar het eindpunt van de kennisbank en controleer of de verwijzing naar de kennisbron "enableImageServing": true bevat.

Ophalen met het leveren van afbeeldingen

Roep de actie ophalen aan op basis van de knowledge base. Als u de standaardinstelling van de kennisbank voor een afzonderlijke aanvraag wilt overschrijven, stelt u enableImageServing in in de bijbehorende vermelding onder 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
    }
  ]
}

Wat gebeurt er op het moment van ophalen

Voor afbeeldingsverwijzingen die zijn gekoppeld aan overeenkomende inhoud, downloadt de zoekservice de bijbehorende afbeeldingen uit het assetarchief, codeert base64 deze en geeft deze als multimodale inhoud door aan het downstream-antwoordsynthesemodel. Inspecteer geaggregeerde statistieken voor het aanbieden van afbeeldingen in activity.imageServing. Zie voor de exacte structuur van het antwoord de referentiedocumentatie voor Knowledge Retrieval - Retrieve (REST API).

Het ophaalgedrag controleren

Een response op een ophaalverzoek kan deze signalen voor het serveren van afbeeldingen bevatten:

• Wanneer includeActivitytrue is, rapporteert de matrix imageServingactivity-activiteit voor een kennisbron wanneer de service bewerkingen voor het aanbieden van afbeeldingen registreert.

• Een waarde van imagesSentToModel die groter is dan 0, betekent dat de service rapporteert dat deze afbeeldingen heeft geleverd aan het onderliggende model voor antwoordsynthese.

Prioriteitsregels

Wanneer zowel de definitie van de knowledgebase als de ophaalaanvraag enableImageServing specificeren, heeft de waarde in de ophaalaanvraag voorrang. De volledige prioriteit is:

1. De waarde in knowledgeSourceParams[].enableImageServing op het ophaalverzoek (indien ingesteld).
2. De waarde voor de overeenkomende kennisbronreferentie in de knowledge base-definitie (indien ingesteld).
3. false (de standaardinstelling).

De volgende tabel bevat een overzicht van de negen combinaties.

Inspecteer statistieken voor het aanbieden van afbeeldingen

Wanneer het serveren van afbeeldingen wordt uitgevoerd, bevat de ophaalrespons voor elke kennisbron een sectie imageServing in de activity-array. Gebruik deze sectie om de afbeeldingen die uit de assetstore zijn opgehaald te vergelijken met de afbeeldingen die naar het model zijn verzonden.

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

Het veldenrapport:

• verbalizationUsed: De door de service gerapporteerde statistiek voor beeldverbalisatie voor de ophaalactiviteit.

• imagesRetrieved: Het aantal afbeeldingen dat is opgehaald uit de asset store.

• imagesSentToModel: Het aantal afbeeldingen dat naar het downstream-model wordt verzonden.

• totalImageSizeBytes: De totale grootte, in bytes, van de afbeeldingen die naar het model zijn verzonden.

Als imagesRetrieved deze groter is dan imagesSentToModel, is niet elke opgehaalde afbeelding naar het model verzonden.

Inspecteer verbalizationUsed en imagesSentToModel onafhankelijk. Een antwoord kan zowel verbalizationUsedtrue als een of meer afbeeldingen rapporteren die naar het model worden verzonden.

End-to-endweergave van testafbeelding testen

Gebruik een van de volgende voorbeelden om de volledige installatie te testen:

• C#-voorbeeld voor het serveren van afbeeldingen
• Python-voorbeeld voor het serveren van afbeeldingen

Met de voorbeelden maakt u een Blob-kennisbron en kennisbank, vergelijkt u ophaalaanvragen met het leveren van afbeeldingen uitgeschakeld en ingeschakeld, en bekijkt u statistieken over het leveren van afbeeldingen. Ze gebruiken ook een onafhankelijke jokertekenindexquery om een image_path asset te selecteren en te downloaden. De voorbeelden selecteren één door puntkomma's gescheiden verwijzing, verwijderen een projectievoorvoegsel zoals 11.7: uit een relatief pad, of URL-decoderen een absoluut pad en verwijderen het leidende asset-containersegment daarvan. Deze transformaties zijn voorbeeldgedrag, geen garanties voor de ophalen-API. Het geselecteerde item bewijst niet dat dezelfde afbeelding heeft bijgedragen aan een specifieke ophaalrespons.

Een typische controlelijst voor A/B-vergelijking:

• Kies een vraag die alleen kan worden beantwoord vanuit een diagram, grafiek of gescande afbeelding.

• Voer de aanvraag ophalen uit met enableImageServing: false en leg het antwoord vast.

• Voer dezelfde ophaalaanvraag uit met enableImageServing: true en vergelijk de antwoorden, latentie en gerapporteerde activiteit.

• Behandel antwoordverschillen als observationele A/B-signalen, niet bewijs dat afbeeldingen de verschillen hebben veroorzaakt. Een imagesSentToModel waarde groter dan 0 betekent dat de service rapporteert dat deze afbeeldingen aan het model heeft geleverd.

De hulpbronnen opschonen

Verwijder de knowledge base voordat u de bijbehorende kennisbron verwijdert. Als u deze Azure AI Zoeken resources verwijdert, worden brondocumenten of geprojecteerde afbeeldingsblobs in Azure Storage niet verwijderd. Verwijder die blobs alleen apart wanneer geen enkele behouden ingestie- of ophaalpijplijn ze nog nodig heeft.

Troubleshooting

Gebruik het imageServing activiteitenblok uit Statistieken voor het aanbieden van afbeeldingen controleren als eerste diagnostische stap. De volgende tabel bevat controles op veelvoorkomende symptomen zonder dat er één oorzaak wordt aangenomen.

Verwante inhoud

• Een query uitvoeren op een knowledge base
• Antwoordsynthese gebruiken voor antwoorden met bronvermeldingen
• Wat is een kennisbron?
• Concepten van kennisarchief