Wyświetlanie obrazów osadzonych w dokumentach w wyszukiwaniu agentowym (wersja zapoznawcza)

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te funkcje lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Ważna

Obsługa obrazów jest dostępna w publicznej wersji zapoznawczej i podlega dodatkowym warunkom użytkowania dla Microsoft Azure wersji zapoznawczych. Aby zapoznać się z terminami wersji zapoznawczej specyficznymi dla tej funkcji, zobacz Funkcjonalność w wersji zapoznawczej.

Użyj funkcji udostępniania obrazów (wersja zapoznawcza), aby udostępniać obrazy osadzone w dokumentach źródłowych (takie jak diagramy, wykresy, infografiki, zeskanowane formularze i obrazy produktów) podczas wyszukiwania agentowego, dzięki czemu duży model językowy (LLM) może wnioskować na podstawie kontekstu wizualnego wraz z tekstem podczas tworzenia odpowiedzi.

Po włączeniu obsługi obrazów usługa Foundry IQ (Wyszukiwanie AI platformy Azure):

  • Podczas indeksowania wyodrębnia obrazy z obsługiwanych dokumentów i przechowuje je w udostępnionym przez klienta magazynie obiektów blob platformy Azure.

  • W czasie wykonywania zapytania pobiera te obrazy podczas akcji retrieve, koduje je w formacie base64 i wstawia je jako treść multimodalną do promptu LLM, który generuje syntetyzowaną odpowiedź.

W tym artykule pokazano, jak włączyć udostępnianie obrazów dla bazy wiedzy, zastępować to ustawienie dla poszczególnych żądań, sprawdzać statystyki udostępniania obrazów oraz planować wymagania dotyczące cyklu życia konta magazynowania.

Wsparcie użytkowania

Azure portal portal Microsoft Foundry zestaw SDK .NET Python SDK Java SDK JavaScript SDK REST API
❌ ❌ ✔️ ✔️ ✔️ ✔️ ✔️

Wymagania wstępne

Ograniczenia i zagadnienia

  • Udostępnianie obrazów jest dostępne wyłącznie za pośrednictwem interfejsu retrieve API w trybie agentic retrieval. Klasyczne zapytania /docs/search nie dostarczają obrazów osadzonych w dokumentach do dalszej syntezy odpowiedzi bez niestandardowego rozwiązania lub konfiguracji.

  • Udostępnianie obrazów działa tylko w trybie wyjściowym syntezy odpowiedzi. Tryb wyjściowy extractiveData pomija serwowanie obrazów.

  • Udostępnianie obrazów ma zastosowanie tylko do indeksowanych źródeł wiedzy opartych na plikach, które mają skonfigurowane assetStore oraz indeksowane fragmenty z wypełnionymi wartościami image_path.

  • W mieszanych bazach wiedzy tylko obsługiwane rodzaje źródeł wiedzy (obiekty blob, indeksowany OneLake i indeksowany SharePoint) dostarczają obrazy osadzone w dokumentach do dalszej syntezy odpowiedzi. Inne rodzaje nadal mogą wnosić wkład w ugruntowanie tekstu.

  • Obsługa obrazów nie jest dostępna w przypadku źródeł wiedzy, które używają ingestionPermissionOptions do pobierania uprawnień na poziomie dokumentu, w tym list ACL, zakresów RBAC i etykiet poufności Microsoft Purview. Magazyn zasobów tworzy bazowy magazyn wiedzy, a magazyny wiedzy nie obsługują dziedziczenia uprawnień.

  • Schemat odpowiedzi pobierania nie definiuje pól dla poszczególnych ścieżek obrazów magazynu zasobów ani bajtów obrazów wysyłanych do modelu. Raporty imageServing aktywności agregują statystyki dla obrazów pobranych i wysłanych do modelu.

  • Dostęp do obrazów jest zarządzany na poziomie konta magazynu danych, niezależnie od dostępu do zindeksowanej zawartości. Każda tożsamość z uprawnieniami do odczytu konta magazynu zasobów może pobierać znajdujące się w nim obrazy.

  • Nie przechowuj wpisów tajnych (kluczy kont, tokenów, parametrów połączenia) w dokumentach źródłowych, ponieważ zawartość może być zwracana jako dane uziemienia.

  • Obsługa obrazów może zwiększyć opóźnienie syntezy odpowiedzi z powodu pobierania obrazu i przetwarzania tokenów wielomodalnych. Uruchom reprezentatywne zapytania przy włączonym i wyłączonym udostępnianiu obrazów i porównaj czas odpowiedzi z zaraportowaną aktywnością imageServing.

  • Usługa Content Understanding może generować różne wyniki obrazów dla plików PDF i DOCX. Jeśli wymagane jest spójne wyodrębnianie obrazów osadzonych i werbalizacja, przekonwertuj dokumenty źródłowe na format PDF lub przetestuj każdy format źródła z reprezentatywną zawartością.

Jak działa obsługa obrazów

Obsługa obrazów ma dwie fazy:

  • Indeksowanie: Podczas konfigurowania standardowego wyodrębniania zawartości i magazynu zasobów w źródle wiedzy wygenerowane umiejętności content Understanding semantycznie fragmentuje dokument, zachowuje tabele jako Markdown i używa skonfigurowanego modułu LLM do opisywania osadzonych rysunków. Opisy rysunków stają się częścią wzbogaconego dokumentu Markdown, który jest wektoryzowany przez umiejętność osadzania. Umiejętność wyodrębnia również obrazy do magazynu obiektów blob i dodaje odwołania image_path do nakładających się bloków.

    Podczas konfigurowania magazynu zasobów usługa IQ usługi Foundry aprowizuje również magazyn wiedzy wraz ze źródłem wiedzy w celu utrwalania wyodrębnionych artefaktów obrazu. Możesz sprawdzić ten magazyn wiedzy i zarządzać nim jak każdy inny.

  • Pobieranie: Po uruchomieniu akcji pobierania z włączonym udostępnianiem obrazów usługa Foundry IQ pobiera pasujące obrazy z magazynu zasobów, koduje je w standardzie base64 i dołącza je jako zawartość wielomodalną w wierszu polecenia syntezy odpowiedzi.

Konfigurowanie magazynu zasobów i dostępu do aplikacji

Udostępnianie obrazów przebiega przez trzy granice zaufania. W czasie indeksowania usługa IQ usługi Foundry zapisuje artefakty obrazów w magazynie zasobów. W czasie wykonywania zapytania usługa IQ foundry odczytuje dane z magazynu zasobów w celu pobrania obrazów. Aplikacja również pobiera dane z magazynu zasobów, jeśli musi wyświetlać obrazy w interfejsie użytkownika. Skonfiguruj każdą ścieżkę zgodnie z zasadą najmniejszych uprawnień.

Dostęp usługi IQ usługi Foundry do magazynu zasobów

  • Użyj Microsoft Entra ID i tożsamości zarządzanej dla usługi IQ usługi Foundry. Przypisz tożsamość roli Współautor danych obiektu blob usługi Storage w zakresie konta magazynu, ponieważ indeksator zapisuje artefakty obrazu, a akcja pobierania je odczytuje. Gdy kontener źródłowy i kontener zasobów korzystają z tego samego konta, rola zapewnia również uprawnienia do odczytu źródłowego obiektu blob.

  • Nie włączaj anonimowego dostępu publicznego w kontenerze magazynu zasobów.

Dostęp aplikacji do odwołań do obrazów

Wygenerowany indeks przechowuje odwołania image_path do obrazów w magazynie zasobów. Schemat odpowiedzi pobierania nie definiuje dedykowanych pól dla poszczególnych ścieżek obrazów magazynu zasobów ani bajtów obrazów wysyłanych do modelu. Opcjonalne sourceData to dane referencyjne ze strukturą i image_path nie są w niej wymagane.

Aby wyświetlić indeksowany obraz w aplikacji:

  1. Przypisz tożsamości aplikacji rolę Czytelnik danych obiektu blob usługi Storage w zakresie konta magazynu zasobu.

  2. Przypisz tożsamości aplikacji rolę Czytelnik danych indeksu wyszukiwania, aby mogła wysyłać zapytania do wygenerowanego indeksu.

  3. Uzyskaj autoryzację image_path z wygenerowanego indeksu za pomocą zapytania kontrolowanego przez aplikację lub punktu końcowego usługi.

  4. Sprawdź, czy odwołanie wskazuje na oczekiwane konto magazynu i kontener zasobów. Odrzuć niezaufane ścieżki przed wyszukiwaniem obiektów blob.

  5. Pobierz nazwę wynikowego obiektu blob z kontenera zasobu przy użyciu tożsamości swojej aplikacji.

Ta separacja umożliwia kontrolowanie, kto może wyświetlać obrazy źródłowe niezależnie od tego, kto może wywołać interfejs API pobierania.

Skonfiguruj repozytorium zasobów dla źródła wiedzy

Skonfiguruj assetStore w ingestionParameters obsługiwanym indeksowanym źródle wiedzy. Magazyn zasobów jest kontenerem obiektów blob, którego jesteś właścicielem i w którym usługa IQ usługi Foundry zapisuje artefakty obrazów.

Aby uzyskać instrukcje specyficzne dla źródła, zobacz:

Minimalne źródło wiedzy typu blob z włączonym udostępnianiem obrazów wygląda następująco:

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-11-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"
      }
    }
  }
}

Note

  • Zastąp <storage-resource-id> element identyfikatorem zasobu konta Azure Storage. Format ciągu połączenia ResourceId=<storage-resource-id> informuje usługę Foundry IQ o użyciu tożsamości zarządzanej dla obu kontenerów.

  • Konto Azure Storage hostujące magazyn zasobów musi pozostać dostępne i dostępne dla usługi IQ usługi Foundry przez cały okres istnienia bazy wiedzy. Jeśli zmienisz reguły sieciowe, obrócisz klucze, zamienisz tożsamości lub przeniesiesz konto magazynu w sposób uniemożliwiający usłudze Foundry IQ odczytywanie magazynu zasobów, usługa dostarczania obrazów nie będzie mogła dostarczać tych obrazów do modelu. Porównaj imagesRetrieved z imagesSentToModel pod względem aktywności pobierania oraz starannie zaplanuj i przetestuj zmiany na koncie magazynu.

Wyniki konfiguracji

Kombinacja , assetStoredisableImageVerbalizationi chatCompletionModel określa, co indeksator przechowuje i co model widzi w czasie zapytania:

  • Magazyn zasobów + opis tekstowy (domyślnie):assetStore ustawione, disableImageVerbalization pozostawione jako false, chatCompletionModel ustawione. Indeksator zapisuje obrazy w repozytorium zasobów i przechowuje opisy tekstowe w indeksie. Operacja pobierania może raportować verbalizationUsed jako true.

  • Magazyn zasobów bez słowizacji (nieprawidłowy): Ustawienie disableImageVerbalization wartości lub true pominięcie chatCompletionModel podczas konfigurowania walidacji parametru pozyskiwania kończy się niepowodzeniem assetStore .

  • Brak magazynu zasobów, zestaw modeli:assetStore nie ustawiono, chatCompletionModel ustaw. Tylko opisy tekstu, bez artefaktów obrazu. Serwowanie obrazów nie ma zastosowania.

  • Brak magazynu zasobów, brak modelu: Nie wygenerowano opisów obrazów ani utrwalonych obrazów do obsługi obrazów. Wyodrębnianie i fragmentowanie w ramach Standard Content Understanding można nadal stosować.

Werbalizacja obrazu w czasie pozyskiwania danych jest oddzielona od użycia modelu pobierania i pobierania bazy wiedzy. Aby wyłączyć opisy pozyskiwania, użyj kontrolek opisu wygenerowanego potoku; ta konfiguracja nie zachowuje magazynu zasobów na potrzeby obsługi obrazów.

Weryfikowanie konfiguracji magazynu zasobów

Przed kontynuowaniem poczekaj na zakończenie importowania danych:

  • Sprawdź stan indeksatora w portalu Azure lub użyj Pobierz stan indeksatora (interfejs API REST).

  • Sprawdź, czy indeksowane fragmenty mają wypełnione image_path pole. Jeśli image_path wartość jest pusta, sprawdź stan indeksatora, konfigurację magazynu zasobów źródła wiedzy, zawartość dokumentu źródłowego i zawartość kontenera zasobów.

  • Sprawdź kontener magazynu zasobów. Powinieneś zobaczyć obiekty blob obrazów, które indeksator zapisał podczas pozyskiwania danych.

Włącz obsługę obrazów w bazie wiedzy

Ustaw dla enableImageServing wartość true w odwołaniu do źródła wiedzy w definicji bazy wiedzy. To ustawienie staje się ustawieniem domyślnym dla każdego żądania pobierania, które jest przeznaczone dla źródła wiedzy.

Definicja bazy wiedzy określa również model LLM używany do syntezy odpowiedzi w momencie wykonywania zapytania. To ustawienie jest niezależne od wszelkich ustawień chatCompletionModel, które skonfigurujesz w elemencie ingestionParameters źródła wiedzy, który steruje generowaniem opisów obrazów podczas indeksowania.

Jeśli baza wiedzy odwołuje się do wielu źródeł wiedzy, ustaw enableImageServing tylko dla obsługiwanych indeksowanych typów opartych na plikach, dla których skonfigurowano assetStore. Nieobsługiwane typy (takie jak indeks wyszukiwania, zdalny SharePoint lub internet) nadal stanowią podstawę tekstową, ale nie dostarczają obrazów osadzonych w dokumentach do dalszej syntezy odpowiedzi.

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-11-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"
      }
    }
  ]
}

Sprawdź, czy serwowanie obrazów jest włączone

Wyślij GET żądanie do punktu końcowego bazy wiedzy i sprawdź, czy odwołanie do źródła wiedzy zawiera "enableImageServing": true.

Pobieranie z serwowaniem obrazów

Wywołaj akcję pobierania względem bazy wiedzy. Aby nadpisać domyślne ustawienie bazy wiedzy dla każdego żądania, ustaw wartość enableImageServing w odpowiednim wpisie pod knowledgeSourceParams.

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-11-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
    }
  ]
}

Note

Obsługa obrazów jest uruchamiana tylko wtedy, gdy outputMode ma wartość answerSynthesis. Żądania korzystające z extractiveData pomijają serwowanie obrazów, nawet gdy enableImageServing jest ustawione.

Co się dzieje w czasie pobierania

W przypadku odwołań do obrazów skojarzonych z zgodną zawartością usługa Foundry IQ pobiera odpowiednie obrazy z magazynu zasobów, koduje je base64 i przekazuje je jako zawartość wielomodalną do docelowego modelu syntezy odpowiedzi. Sprawdź zbiorcze statystyki serwowania obrazów w activity.imageServing. Dokładny format odpowiedzi znajdziesz w dokumentacji referencyjnej dla Knowledge Retrieval - Retrieve (interfejs REST API).

Zweryfikuj działanie pobierania

Odpowiedź na żądanie pobrania może zawierać następujące sygnały związane z dostarczaniem obrazów:

  • Gdy wartość includeActivity to true, tablica activity raportuje aktywność imageServing dla źródła wiedzy, gdy usługa rejestruje operacje udostępniania obrazów.

  • Wartość imagesSentToModel większa niż 0 oznacza, że usługa zgłasza, że dostarcza obrazy do podrzędnego modelu syntezy odpowiedzi.

Reguły pierwszeństwa

Jeśli zarówno definicja bazy wiedzy, jak i żądanie pobrania określają enableImageServing, pierwszeństwo ma wartość podana w żądaniu pobrania. Pełny priorytet to:

  1. Wartość w elemencie knowledgeSourceParams[].enableImageServing w żądaniu pobrania (jeśli jest ustawiona).
  2. Wartość odpowiedniego odwołania do źródła wiedzy w definicji bazy wiedzy (jeśli jest ustawiona).
  3. false (wartość domyślna).

Poniższa tabela zawiera podsumowanie dziewięciu kombinacji.

Definicja bazy wiedzy (enableImageServing) Pobierz żądanie (enableImageServing) Włączono obsługę obrazów?
true true Yes
true false No
true Nie ustawiono Yes
false true Yes
false false No
false Nie ustawiono No
Nie ustawiono true Yes
Nie ustawiono false No
Nie ustawiono Nie ustawiono No

Sprawdź statystyki dostarczania obrazów

Gdy działa obsługa obrazów, odpowiedź pobierania zawiera sekcję imageServing dla każdego źródła wiedzy w tablicy activity. Ta sekcja służy do porównywania obrazów pobranych z magazynu zasobów z obrazami wysyłanymi do modelu.

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

Raport z pól:

  • verbalizationUsed: statystyka werbalizacji obrazów zgłoszona przez usługę dla działania pobierania.

  • imagesRetrieved: liczba obrazów pobranych z magazynu zasobów.

  • imagesSentToModel: liczba obrazów wysyłanych do modelu podrzędnego.

  • totalImageSizeBytes: łączny rozmiar obrazów wysyłanych do modelu w bajtach.

Jeśli imagesRetrieved wartość jest większa niż imagesSentToModel, nie każdy pobrany obraz został wysłany do modelu.

Sprawdź verbalizationUsed i imagesSentToModel niezależnie. Odpowiedź może zawierać zarówno informację o verbalizationUsed jako true, jak i o co najmniej jednym obrazie przesłanym do modelu.

Test obsługi obrazu od końca do końca

Aby przetestować pełną konfigurację, użyj jednego z następujących przykładów:

Przykłady tworzą źródło wiedzy Blob i bazę wiedzy, porównują żądania pobierania przy wyłączonej i włączonej obsłudze obrazów oraz analizują statystyki obsługi obrazów. Używają również niezależnego zapytania do indeksu z symbolami wieloznacznymi, aby wybrać image_path i pobrać ten zasób. Przykłady wybierają jedną referencję rozdzieloną średnikami, usuwają prefiks projekcji, taki jak 11.7:, ze ścieżki względnej lub dekodują adres URL ścieżki bezwzględnej i usuwają z niej początkowy segment kontenera zasobów. Te przekształcenia stanowią przykładowe zachowania, a nie gwarancje interfejsu API Retrieve. Wybrany zasób nie stanowi dowodu na to, że ten sam obraz został wykorzystany do wygenerowania konkretnej odpowiedzi operacji pobierania.

Typowa lista kontrolna porównania A/B:

  • Wybierz pytanie, na które można odpowiedzieć tylko na diagramie, wykresie lub zeskanowanym obrazie.

  • Uruchom żądanie pobrania za pomocą enableImageServing: false i przechwyć odpowiedź.

  • Uruchom to samo żądanie pobrania z enableImageServing: true i porównaj odpowiedzi, opóźnienie oraz zaraportowaną aktywność.

  • Traktuj różnice odpowiedzi jako obserwacyjne sygnały A/B, a nie dowód, że obrazy spowodowały różnice. Wartość imagesSentToModel większa niż 0 oznacza, że usługa zgłasza, że dostarcza obrazy do modelu.

Uprzątnij zasoby

Usuń bazę wiedzy przed usunięciem jej źródła wiedzy. Usunięcie tych zasobów IQ usługi Foundry nie powoduje usunięcia dokumentów źródłowych ani obiektów blob obrazów z projekcji w Azure Storage. Usuń te obiekty blob osobno tylko wtedy, gdy nie są już potrzebne żadnemu zachowanemu potokowi pozyskiwania ani pobierania.

Troubleshooting

Użyj bloku aktywności imageServing z sekcji Sprawdzanie statystyk dostarczania obrazów jako pierwszego narzędzia diagnostycznego. Poniższa tabela zawiera kontrole dotyczące typowych objawów, bez zakładania jednej przyczyny.

Objaw Kontrole
imagesRetrieved jest 0 dla dokumentów bogatych w obrazy Sprawdź stan indeksatora i ostrzeżenia, wartości image_path wypełnione w pasujących zindeksowanych fragmentach oraz bloby obrazów w kontenerze zasobów. Upewnij się, że dokumenty źródłowe zawierają obrazy możliwe do wyodrębnienia i że tożsamość usługi Foundry IQ ma Współautor danych obiektu blob usługi Storage w zakresie konta magazynu.
Odpowiedź operacji pobierania nie ma bloku imageServing Upewnij się, że żądanie ustawia includeActivity na true. Sprawdź efektywną wartość enableImageServing po zastosowaniu priorytetu żądania, bazy wiedzy i wartości domyślnej. Upewnij się, że jest to outputModeanswerSynthesis, i sprawdź błędy i ostrzeżenia dotyczące działań źródłowych.
verbalizationUsed różni się od oczekiwanego Sprawdź disableImageVerbalization, chatCompletionModeli najnowszy stan indeksatora. Sprawdź verbalizationUsed niezależnie od imagesSentToModel. Odpowiedź może zawierać informację o treści werbalnej i obrazach przesłanych razem.
Synteza odpowiedzi kończy się niepowodzeniem lub upłynął limit czasu po włączeniu obsługi obrazów Porównaj przykładowe żądania przy włączonym i wyłączonym dostarczaniu obrazów. Sprawdź błędy działań i ostrzeżenia, stan wdrożenia modelu syntezy odpowiedzi, uprawnienia tożsamości usługi Foundry IQ dla modelu i konta magazynu oraz dostępność magazynu zasobów.
Aplikacja nie może wyrenderować image_path odpytywanego niezależnie. Upewnij się, że niezależne zapytanie do indeksu zwraca blob image_path, którego można użyć, że wskazany blob istnieje oraz że aplikacja może uzyskać dostęp do tego blobu niezależnie od operacji retrieve. Sprawdź, czy tożsamość aplikacji ma rolę Search Index Data Reader dla zapytania do indeksu oraz rolę Storage Blob Data Reader w zakresie konta magazynu zasobów.