Structured output - Docs by LangChain

이 문서는 LangChain과 LangGraph에서 에이전트가 특정하고 예측 가능한 형식으로 데이터를 반환할 수 있도록 하는 'Structured Output' 기능에 대해 상세히 설명합니다. 자연어 응답을 파싱하는 대신, JSON 객체, Pydantic 모델 또는 dataclass와 같은 구조화된 데이터를 직접 사용할 수 있도록 합니다.

핵심 방법론은 create_agent 함수와 response_format 매개변수를 통해 구현됩니다. response_format은 에이전트가 구조화된 데이터를 반환하는 방식을 제어하며, ToolStrategy[StructuredResponseT], ProviderStrategy[StructuredResponseT], type[StructuredResponseT], 또는 None 값을 가질 수 있습니다. 특히 type[StructuredResponseT]와 같이 스키마 유형이 직접 제공될 때, LangChain은 모델의 기능을 기반으로 최적의 전략을 자동으로 선택합니다. $langchain>=1.1$을 사용하는 경우, 모델의 프로필 데이터를 동적으로 읽어 Native Structured Output 지원 여부를 판단합니다.

1. Provider Strategy (Provider-native Structured Output)
일부 모델 제공자(예: OpenAI, Anthropic (Claude), xAI (Grok))는 API를 통해 Native Structured Output을 지원합니다. 이 방식은 가장 신뢰할 수 있으며, ProviderStrategy를 구성하여 사용할 수 있습니다.

* 동작 원리: 모델 제공자 자체가 스키마에 맞춰 출력을 생성하도록 강제합니다. 이는 모델이 응답을 생성하는 과정에서 스키마 유효성 검사를 내부적으로 수행함을 의미합니다. LangChain은 이 출력을 캡처하고 추가적인 유효성 검사(특히 Pydantic 모델의 경우)를 수행하여 structured_response 키에 반환합니다.
* 스키마 정의: schema 매개변수를 통해 정의하며, Pydantic 모델(BaseModel 서브클래스), Python dataclass, TypedDict, 또는 JSON Schema 딕셔너리를 지원합니다. Pydantic 모델의 경우 검증된 Pydantic 인스턴스를 반환하고, 다른 유형은 딕셔너리를 반환합니다.
* Strict 모드: $strict: bool | None = None$ 매개변수는 스키마 준수 여부를 엄격하게 적용할 수 있도록 합니다. 일부 제공자(예: OpenAI, xAI)에서 지원됩니다.
* 자동 선택: create_agent에 스키마 유형을 직접 전달하고 해당 모델이 Native Structured Output을 지원하는 경우, LangChain은 자동으로 ProviderStrategy를 선택합니다. 이는 $response_format=ProductReview$와 $response_format=ProviderStrategy(ProductReview)$가 기능적으로 동일하다는 것을 의미합니다. Native 지원이 없는 경우, ToolStrategy로 폴백(fallback)됩니다.

2. Tool Calling Strategy
Native Structured Output을 지원하지 않는 모델의 경우, LangChain은 Tool Calling을 사용하여 동일한 결과를 달성합니다. 이는 Tool Calling을 지원하는 대부분의 최신 모델에서 작동합니다. ToolStrategy를 구성하여 사용합니다.

* 동작 원리: 에이전트는 사용자가 정의한 스키마를 기반으로 가상의 "구조화된 출력 도구(structured output tool)"를 호출합니다. 모델은 이 도구의 매개변수로 구조화된 데이터를 제공하려고 시도합니다. LangChain은 이 도구 호출을 가로채고, 매개변수들을 지정된 스키마에 따라 유효성을 검사합니다. 검증이 성공하면 데이터는 structured_response 키에 저장됩니다.
* 스키마 정의: schema 매개변수를 통해 정의하며, Pydantic 모델, Python dataclass, TypedDict, JSON Schema 딕셔너리 외에 Union 유형도 지원하여 모델이 상황에 따라 가장 적절한 스키마를 선택할 수 있게 합니다.
* tool_message_content: 구조화된 출력이 생성될 때 대화 기록에 표시되는 Tool Message의 내용을 사용자 정의할 수 있습니다. 기본적으로는 구조화된 응답 데이터를 보여주는 메시지가 표시됩니다.
* 기본 메시지: Returning structured response: {'task': 'update the project timeline', ...}
* 사용자 정의 메시지: Action item captured and added to meeting notes!
* 오류 처리 (Error Handling): Tool Calling을 통한 구조화된 출력 생성 시 모델이 실수를 할 수 있으므로, LangChain은 지능적인 재시도 메커니즘을 제공합니다.
* Multiple structured outputs error: 모델이 여러 개의 구조화된 출력 도구를 잘못 호출한 경우, 에이전트는 Tool Message에 오류 피드백을 제공하고 모델에게 재시도를 지시합니다.
* 오류 메시지 예시: Error: Model incorrectly returned multiple structured responses (ContactInfo, EventDetails) when only one is expected. Please fix your mistakes.
* Schema validation error: 구조화된 출력이 예상 스키마와 일치하지 않을 때, 에이전트는 특정 오류 피드백을 제공합니다.
* 오류 메시지 예시: $Error: Failed to parse structured output for tool 'ProductRating': 1 validation error for ProductRating.rating Input should be less than or equal to 5 [type=less_than_equal, input_value=10, input_type=int]. Please fix your mistakes.$
* handle_errors 매개변수: 오류 처리 전략을 사용자 정의할 수 있습니다.
* True (기본값): 모든 오류를 기본 오류 템플릿으로 처리하고 재시도합니다.
* str: 모든 오류를 지정된 사용자 정의 메시지로 처리하고 재시도합니다.
* type[Exception] 또는 tuple[type[Exception], ...]: 지정된 예외 유형에 대해서만 재시도(기본 메시지 사용)하고, 그 외의 예외는 전파(raise)합니다.
* Callable[[Exception], str]: 사용자 정의 함수를 통해 예외 유형에 따라 다른 오류 메시지를 반환하고 재시도할 수 있습니다.
* 예시: if isinstance(error, StructuredOutputValidationError): return "There was an issue with the format. Try again."
* 예시: elif isinstance(error, MultipleStructuredOutputsError): return "Multiple structured outputs were returned. Pick the most relevant one."
* False: 오류를 재시도하지 않고 예외를 즉시 전파(propagate)합니다.

이처럼 LangChain의 Structured Output 기능은 ProviderStrategy와 ToolStrategy를 통해 모델의 기능에 맞춰 유연하게 구조화된 데이터 추출을 지원하며, 강력한 오류 처리 메커니즘을 내장하여 견고성을 높입니다.