Używanie usługi Content Understanding z platformą agenta Microsoft

Integracja Azure Content Understanding w narzędziu Foundry Tools dla platformy Microsoft Agent Framework udostępnia dostawcę kontekstu dla załączników plików. Dostawca wykrywa obsługiwane dokumenty, obrazy, dźwięk i wideo w danych wejściowych agenta, analizuje pliki i dodaje pola markdown i wyodrębnione do kontekstu modelu.

Wymagania wstępne

Dlaczego warto używać tej integracji

  • Automatyczne przetwarzanie załączników. Struktura wywołuje dostawcę przed każdym wywołaniem modelu, więc nie wywołujesz analizatora bezpośrednio.
  • Dane wejściowe wielomodalne. Dostawca akceptuje dokumenty, obrazy, dźwięk i wideo.
  • Strukturalne dane wyjściowe. Dostawca może dodać pola markdown i wyodrębnione do kontekstu modelu.
  • Przetwarzanie odroczone. Konfigurowalny czas oczekiwania umożliwia wykonywanie długotrwałych analiz w tle. Opcjonalna obsługa wyszukiwania plików przekazuje wyodrębnione elementy Markdown do magazynu wektorów do generowania rozszerzonego pobierania (RAG).

Instalowanie pakietu

Zainstaluj pakiet integracyjny Content Understanding dla platformy Microsoft Agent Framework. Integracja jest dostarczana w pakiecieagent-framework-azure-contentunderstanding, który jest również dostępny w infrastrukturze PyPI:

pip install agent-framework-azure-contentunderstanding --pre

Note

Flaga --pre instaluje bieżącą kompilację wersji wstępnej pakietu.

Rejestrowanie usługi Content Understanding jako dostawcy kontekstu

Utwórz obiekt ContentUnderstandingContextProvider, przekaż go do agenta za pomocą parametru context_providers i uruchom agenta w bloku dostawcy async with . Poniższy przykład odpowiada na pytanie dotyczące dołączonego dokumentu:

import asyncio
from agent_framework import Agent, AgentSession, Message, Content
from agent_framework.foundry import FoundryChatClient
from agent_framework.foundry import ContentUnderstandingContextProvider
from azure.identity import AzureCliCredential

credential = AzureCliCredential()

cu = ContentUnderstandingContextProvider(
    endpoint="https://my-resource.cognitiveservices.azure.com/",
    credential=credential,
    # Block until analysis completes before sending to the model.
    max_wait=None,
)

client = FoundryChatClient(
    project_endpoint="https://your-project.services.ai.azure.com",
    model="gpt-5.2",
    credential=credential,
)

async def main():
    async with cu:
        agent = Agent(
            client=client,
            name="DocumentQA",
            instructions="You are a helpful document analyst.",
            context_providers=[cu],
        )
        session = AgentSession()

        response = await agent.run(
            Message(role="user", contents=[
                Content.from_text("What's on this invoice?"),
                Content.from_uri(
                    "https://raw.githubusercontent.com/Azure-Samples/"
                    "azure-ai-content-understanding-assets/main/"
                    "document/invoice.pdf",
                    media_type="application/pdf",
                    additional_properties={"filename": "invoice.pdf"},
                ),
            ]),
            session=session,
        )
        print(response.text)

asyncio.run(main())

Przed każdym wywołaniem modelu platforma wywołuje dostawcę. Dostawca wykrywa i analizuje obsługiwane załączniki, więc nie wywołujesz analizatora bezpośrednio.

Konfiguruj dostawcę

Przekaż dodatkowe parametry, aby wybrać analizator i kontrolować ilość zawartości zwracaną przez dostawcę:

Parameter Purpose
endpoint Punkt końcowy zasobu Microsoft Foundry. W przypadku pominięcia dostawca odczytuje go ze zmiennej środowiskowej AZURE_CONTENTUNDERSTANDING_ENDPOINT .
credential AzureKeyCredential Uwierzytelnianie klucza interfejsu API lub poświadczenie tożsamości Azure, takie jak AzureCliCredential lub DefaultAzureCredential, na potrzeby uwierzytelniania Microsoft Entra ID.
analyzer_id Wstępnie utworzony lub niestandardowy identyfikator analizatora. Jeśli pominiesz ten parametr, dostawca wybierze prebuilt-documentSearch dla dokumentów i obrazów, prebuilt-audioSearch audio i prebuilt-videoSearch wideo.
max_wait Ile sekund oczekiwania przed odroczeniem analizy w tle. Wartość domyślna to 5 sekund. Ustaw ją na wartość , aby None poczekać na zakończenie analizy.
output_sections Które sekcje wyników do dodania do kontekstu modelu. Domyślne sekcje to Markdown i pola.
file_search Opcjonalna konfiguracja przekazywania wyodrębnionego języka Markdown do magazynu wektorów zamiast dodawania pełnej zawartości do kontekstu modelu.

Wskazówka

W przypadku wyodrębniania specyficznego dla domeny ustaw analyzer_id identyfikator wstępnie utworzonego lub niestandardowego analizatora. Następnie dostawca dodaje pola analizatora do kontekstu modelu.

Typy obsługiwanych plików

Dostawca akceptuje dokumenty, obrazy, dźwięk i wideo. Aby uzyskać pełną listę obsługiwanych formatów i limitów rozmiaru, zobacz Content Understanding service quotas and limits (Limity i limity usługi Content Understanding).

Następne kroki

  • Ostatnia aktualizacja o