Microsoft Agent Framework에서 Content Understanding 사용

Microsoft Agent Framework에 대한 foundry Tools 통합의 Azure Content Understanding은 파일 첨부 파일에 대한 컨텍스트 공급자를 제공합니다. 공급자는 에이전트 입력에서 지원되는 문서, 이미지, 오디오 및 비디오를 검색하고, 파일을 분석하고, Markdown 및 추출된 필드를 모델 컨텍스트에 추가합니다.

사전 요구 사항

  • Azure 구독입니다. 무료 Azure 구독을 만들 수 있습니다.
  • Content Understanding이 구성된 Microsoft Foundry 리소스입니다. 설치 지침은 Microsoft Foundry 리소스 만들기를 참조하세요. 리소스가 지원되는 지역에 있는지 확인합니다.
  • 리소스에 대해 구성된 기본 모델 배포입니다. Foundry 모델 배포를 참조하세요.
  • Python 3.10 이상.
  • 샘플에서 인증할 수 있도록 Azure CLI(az login)로 AzureCliCredential로그인합니다.

이 통합을 사용하는 이유

  • 자동 첨부 파일 처리. 프레임워크는 각 모델 호출 전에 공급자를 호출하므로 분석기를 직접 호출하지 않습니다.
  • 다중 모드 입력입니다. 공급자는 문서, 이미지, 오디오 및 비디오를 허용합니다.
  • 구조적 출력. 공급자는 Markdown 및 추출된 필드를 모델 컨텍스트에 추가할 수 있습니다.
  • 지연된 처리입니다. 구성 가능한 대기 시간을 사용하면 장기 실행 분석을 백그라운드에서 계속할 수 있습니다. 선택적 파일 검색 지원은 RAG(검색 보강 생성)를 위해 추출된 Markdown을 벡터 저장소에 업로드합니다.

패키지 설치

Microsoft Agent Framework용 Content Understanding 통합 패키지를 설치합니다. 통합은 PyPI에서도 agent-framework-azure-contentunderstanding사용할 수 있는 패키지에 제공됩니다.

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

메모

플래그는 --pre 패키지의 현재 시험판 빌드를 설치합니다.

Content Understanding을 컨텍스트 공급자로 등록

생성하고 ContentUnderstandingContextProvider, 매개 변수를 통해 에이전트에 context_providers 전달하고, 공급자 블록 async with 내에서 에이전트를 실행합니다. 다음 예제에서는 첨부된 문서에 대한 질문에 대답합니다.

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())

각 모델 호출 전에 프레임워크는 공급자를 호출합니다. 공급자는 지원되는 첨부 파일을 검색하고 분석하므로 분석기를 직접 호출하지 않습니다.

제공자 구성

추가 매개 변수를 전달하여 분석기를 선택하고 공급자가 반환하는 콘텐츠 양을 제어합니다.

매개 변수 Purpose
endpoint Microsoft Foundry 리소스의 엔드포인트입니다. 생략하면 공급자가 환경 변수에서 AZURE_CONTENTUNDERSTANDING_ENDPOINT 읽습니다.
credential AzureKeyCredential API 키 인증 또는 Microsoft Entra ID 인증에 대한 Azure ID 자격 증명(예: AzureCliCredential 또는DefaultAzureCredential)입니다.
analyzer_id 미리 빌드된 또는 사용자 지정 분석기 ID입니다. 이 매개 변수를 생략하면 공급자가 문서 및 이미지, prebuilt-audioSearch 오디오 및 prebuilt-videoSearch 비디오에 대해 선택합니다prebuilt-documentSearch.
max_wait 분석을 백그라운드로 연기하기 전에 대기할 시간(초)입니다. 기본값은 5초입니다. 분석이 완료될 때까지 기다리도록 None 설정합니다.
output_sections 모델 컨텍스트에 추가할 결과 섹션입니다. 기본 섹션은 Markdown 및 필드입니다.
file_search 모델 컨텍스트에 전체 콘텐츠를 추가하는 대신 추출된 Markdown을 벡터 저장소에 업로드하기 위한 선택적 구성입니다.

Tip

도메인별 추출의 경우 미리 빌드된 또는 사용자 지정 분석기 ID로 설정합니다 analyzer_id . 그런 다음 공급자는 분석기 필드를 모델 컨텍스트에 추가합니다.

지원되는 파일 형식

공급자는 문서, 이미지, 오디오 및 비디오를 허용합니다. 지원되는 형식 및 크기 제한의 전체 목록은 Content Understanding 서비스 할당량 및 제한을 참조하세요.

다음 단계

  • 에 마지막으로 업데이트됨