Structured outputs for Anthropic Claude models on Amazon Bedrock

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Amazon Bedrock은 모델이 제공되는 bedrock-runtime과 bedrock-mantle 엔드포인트에서 모든 Anthropic Claude 모델의 구조화된 출력과 엄격한 도구 사용을 지원하며, 생성 단계에서 JSON 스키마 준수를 강제한다.

📌 핵심 요약

• 구조화된 출력은 제약 디코딩으로 JSON 형식, 필드 유형, 필수 필드와 허용 필드를 강제한다. JSON Schema 출력 형식은 응답 구조를, strict tool use는 도구 인자를 통제하며, 원문은 이를 통해 스키마 위반에 따른 파싱·검증·재시도 부담을 줄일 수 있다고 설명한다.
• 배치 추론과 구조화된 응답의 타입 지정 이벤트 스트리밍을 지원하며, bedrock-runtime에서는 교차 리전 추론도 지원한다. 금융·의료 문서와 계약의 정보 추출, 상품 카탈로그 보강, 지원 티켓 분류·라우팅 등이 활용 사례로 제시된다.
• Amazon Bedrock은 지원되는 JSON Schema Draft 2020-12 하위 집합을 검증하고 문법을 컴파일한다. 새 스키마의 첫 요청은 지연될 수 있으며, 컴파일 결과는 계정별로 최초 접근부터 24시간 캐시된다. 스키마 구조 변경은 재컴파일을 유발하지만 name이나 description 필드만 바꾸면 캐시가 유지된다.
• InvokeModel API 예제는 output_config.format에 스키마를 JSON 객체로 전달하며, Claude Sonnet 5.5로 고객 정보를 추출하고 Claude Haiku 5.5로 지원 티켓을 분류한다. 예제는 stop_reason이 end_turn일 때 결과를 파싱하고, max_tokens이면 토큰 한도를 늘려 재시도하도록 안내한다.
• 모든 객체에 additionalProperties: false를 설정해야 스키마가 허용된다. 명확한 필드명·설명과 enum 사용, 최소 필수 필드부터의 점진적 확장, 캐시 활용을 위한 스키마 재사용이 권장되며, 스키마는 Converse API 요청 페이로드 크기에 포함된다.

🧩 주요 포인트

1. 생성 시점의 스키마 강제 → 응답 구조와 도구 인자 오류를 줄이고, 허용 필드 제한으로 출력 토큰과 대량 추론 비용을 낮출 가능성.
2. 시간 문법 캐시와 스키마 구조별 재컴파일 → 스키마 재사용 및 복잡도 관리가 초기 지연과 반복 요청 성능에 영향.
3. Claude Sonnet 5.5의 정보 추출과 Claude Haiku 5.5의 분류 예제 → 업무 데이터 구조를 직접 지정할 수 있지만, max_tokens에 따른 응답 잘림은 별도 처리 필요.

🧠 상세 정리

1. 지원 범위와 산업별 활용

Amazon Bedrock은 Anthropic Claude 모델이 제공되는 bedrock-runtime과 bedrock-mantle 두 엔드포인트에서 모든 해당 모델의 구조화된 출력을 지원한다고 발표한다. Boto3와 bedrock-runtime API를 이용하거나 Messages API와 bedrock-mantle을 이용하는 경우 모두, 정의한 구조에 부합하는 JSON 응답을 받을 수 있다는 설명이다. 활용 사례로는 재무 실적 보고서와 규제 준수 문서의 필수 필드 추출, 임상 기록의 전자건강기록(EHR) 변환, 일관되고 검증된 결과를 이용한 상품 카탈로그 보강을 제시한다. 계약에서 핵심 조건·당사자·의무를 추출하거나, 의도·감정·엔터티가 애플리케이션 데이터 모델에 맞도록 지원 티켓을 라우팅하는 작업도 포함된다. 원문은 이러한 업무에서 맞춤형 파싱, 재시도 로직과 후처리에 대한 필요가 사라진다는 점을 도입 효과로 강조한다.

2. 제약 디코딩과 두 가지 통제 방식

구조화된 출력은 응답 생성 후 형식을 고치는 대신, 토큰 생성 중 제약 디코딩을 적용해 JSON 스키마를 강제한다. 모델이 스키마를 위반하는 토큰을 생성하지 못하게 하므로, 원문은 출력 형식이 확률적인 방식에서 결정적인 방식으로 바뀐다고 설명한다. 두 엔드포인트에서 제공되는 상호 보완적 기능 중 JSON Schema 출력 형식은 데이터 추출·보고서 생성·API 응답의 구조를 통제하고, strict tool use는 에이전트 작업·함수 호출·다단계 자동화에 쓰이는 도구 인자를 검증한다. 원문은 유효한 JSON, 필드 유형 준수와 필수 필드 보장을 통해 JSON.parse() 오류와 스키마 위반 재시도를 없앨 수 있다고 주장한다. 또한 스키마에 정의한 필드만 출력하도록 제한하면 출력 토큰 수가 줄어 대량 작업의 추론 비용이 낮아질 수 있으며, 추가 스키마 검증 코드 없이 운영 규모로 배포할 수 있다고 설명한다.

3. 추론 방식, 스키마 컴파일과 캐시

구조화된 출력은 배치 추론과 함께 사용할 수 있어 대량 요청을 비동기로 처리하면서도 스키마에 맞는 결과를 받을 수 있다. bedrock-runtime에서는 별도 설정 없이 교차 리전 추론과 함께 사용할 수 있으며, 실시간 응답이 필요한 경우 구조화된 결과를 타입이 지정된 이벤트로 스트리밍할 수 있다. 요청을 받으면 Amazon Bedrock은 먼저 지원되는 JSON Schema Draft 2020-12 하위 집합에 맞는지 검증하고, 새 스키마라면 문법 산출물을 컴파일한 뒤 이에 맞춰 토큰을 생성한다. 첫 요청은 컴파일 때문에 더 오래 걸릴 수 있지만, 결과는 계정별로 최초 접근부터 24시간 캐시되어 같은 스키마의 후속 요청에는 최소한의 추가 부담만 발생한다고 설명한다. JSON 스키마의 구조를 바꾸면 캐시가 무효화되어 다시 컴파일되지만, name이나 description 필드만 변경하는 경우에는 기존 문법 캐시가 유지된다.

4. InvokeModel을 이용한 고객 정보 추출

InvokeModel API는 Anthropic 고유 요청 본문을 사용하므로, 스키마를 JSON 문자열이 아닌 JSON 객체로 output_config.format에 넣는다. 예제는 Boto3로 us-east-1의 bedrock-runtime 클라이언트를 만들고 global.anthropic.claude-sonnet-5-5를 호출해 고객 이메일에서 정보를 추출한다. 스키마에는 문자열인 name·email·plan_interest와 불리언인 demo_requested를 정의하고, 네 필드를 모두 필수로 지정하며 additionalProperties: false로 다른 필드를 금지한다. 입력에는 Paulo Santos, [email protected], Enterprise 요금제 관심과 다음 화요일 오후 2시 데모 요청이 담겨 있지만, 제시된 출력은 스키마가 지정한 네 필드만 포함한다. 코드는 stop_reason이 end_turn이면 텍스트 블록의 JSON을 파싱하고, max_tokens이면 응답이 잘렸다는 안내와 함께 토큰 한도를 늘려 재시도하도록 하며, 원문은 완성된 응답에 추가 검증이 필요하지 않다고 설명한다.

5. Amazon Bedrock Mantle의 엄격한 도구 사용

Amazon Bedrock Mantle은 서버 측 도구, 백그라운드 추론과 상태를 유지하는 대화를 사용하는 에이전트 애플리케이션을 위해 설계됐다고 소개된다. bedrock-mantle의 strict tool use는 도구 인자가 입력 스키마와 정확히 일치하도록 보장하는 기능이며, 예제는 AnthropicBedrockMantle 클라이언트와 anthropic.claude-sonnet-5 모델을 사용한다. San Francisco의 날씨를 묻는 요청에 대해 get_weather 도구를 정의하고 strict: true를 설정하며, 문자열 location과 온도 단위 unit을 모두 필수 인자로 지정한다. unit은 enum으로 celsius 또는 fahrenheit만 허용하고 additionalProperties: false를 적용하므로, 모델은 스키마 밖의 인자를 추가할 수 없다. 원문은 이러한 제약이 웹 검색이나 코드 인터프리터 같은 서버 측 도구를 모델이 조율하는 다단계 작업에서 특히 유용하다고 설명한다.

6. 오류 처리 부담을 줄이는 세 가지 패턴

원문은 구조화된 출력이 오류 처리 복잡도를 특히 크게 줄이는 공통 패턴으로 데이터 추출, 신뢰할 수 있는 에이전트 도구 호출, 대규모 분류를 제시한다. 데이터 추출은 송장·계약·이메일·대화 기록의 필드를 스키마에 맞는 JSON으로 변환해 데이터베이스나 고객관계관리(CRM) 시스템에 적재할 수 있도록 하는 방식이다. 도구 호출에서는 생성 시점에 인자가 스키마를 따르도록 하여, 잘못된 형식의 입력으로 다단계 에이전트 작업이 실패하는 문제를 줄인다고 설명한다. 대규모 분류는 티켓·잠재 고객·콘텐츠의 의도·우선순위·감정을 구분해 라우팅, 콘텐츠 조정과 평가에 사용하는 패턴이다. 이어 Claude Haiku 5.5가 요약, 압축, 데이터베이스 질의와 분류 요청처럼 빠르고 반복적인 작업을 안정적으로 처리한다고 소개하고, 이를 지원 티켓 분류 코드로 구체화한다.

7. Claude Haiku 5.5의 티켓 분류와 응답 종료 처리

분류 예제는 global.anthropic.claude-haiku-5-5와 InvokeModel API를 사용하고, category·priority·sentiment·escalate·reason을 모두 필수 출력 필드로 지정한다. category는 billing·technical·account·sales·other, priority는 low·medium·high·urgent, sentiment는 positive·neutral·negative로 제한하며, escalate는 불리언이고 reason은 분류 근거를 담는 문자열이다. 입력 티켓은 운영 API 호출에서 아침부터 500 오류가 발생해 매분 주문을 잃고 있으며, 이번 달 두 번째 장애라는 내용을 담지만, 원문에는 이 요청의 실제 분류 결과가 제시되지 않는다. 코드는 정상 종료인 end_turn에서 결과를 파싱하고 escalate가 참이면 category와 priority를 이용해 당직 담당자에게 에스컬레이션한다는 메시지를 출력한다. max_tokens로 끝나면 토큰 한도를 늘려 재시도하도록 안내하므로, 스키마 형식 보장과 별개로 응답이 완성됐는지 확인하는 절차가 예제에 포함된다.

8. 스키마 작성 요구사항과 적용 시 유의점

원문은 구조화된 출력을 사용하려면 모든 객체에 additionalProperties: false를 설정해야 하며, 이를 빠뜨린 스키마는 허용되지 않는다고 명시한다. 모델은 속성 이름과 설명을 바탕으로 추출할 데이터를 이해하므로, field1처럼 일반적인 이름보다 customer_email처럼 의미가 분명한 이름을 권장한다. 허용 값이 제한된 필드에는 enum을 사용하고, 처음에는 최소 필수 필드만 정의한 다음 복잡도를 점진적으로 높이라는 지침도 제시한다. 단순한 스키마는 컴파일이 빠르고 디버깅하기 쉬우며, 스키마 자체가 Converse API 페이로드 크기에 포함되므로 요청 크기를 작게 유지하는 데도 도움이 된다고 설명한다. 마지막으로 캐시 활용을 위한 스키마 재사용을 권장하지만, 제공된 원문은 해당 항목의 설명 도중 끝나므로 이후의 구체적인 지침이나 결론은 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 원문이 강조하는 결정성은 JSON 구조와 도구 인자의 스키마 준수에 관한 것이다. 제시된 분류 예제에는 실제 결과가 없어, 형식 보장만으로 분류 내용의 정확성까지 확인할 수는 없다.
• 스키마는 출력 제약인 동시에 성능에 영향을 주는 요소다. 필드 제한은 출력 토큰 절감에 기여할 수 있고, 구조의 재사용은 24시간 문법 캐시를 활용하는 조건이 된다.
• 스키마 위반 재시도가 불필요하다는 설명과 max_tokens 재시도 예제는 구분해서 읽을 필요가 있다. 출력 구조를 강제하더라도 토큰 한도로 응답이 잘리는 상황은 별도 처리가 필요하다.

✅ 액션 아이템

• 적용할 JSON 스키마의 모든 객체에 additionalProperties: false를 설정하고, 제한된 값에는 enum을 적용.
• 24시간 문법 캐시를 활용하도록 스키마를 재사용하고, 구조 변경에 따른 재컴파일과 첫 요청 지연을 고려.
• InvokeModel API 결과는 stop_reason을 확인해 end_turn에서 파싱하고, max_tokens이면 토큰 한도 증가 후 재시도.

❓ 열린 질문

• 데이터 추출, 지원 티켓 분류·라우팅, 도구 인자 통제 중 구조화된 출력을 먼저 적용할 업무는 무엇인가?
• 24시간 문법 캐시를 활용할 수 있도록 재사용할 스키마와 구조 변경이 필요한 스키마는 각각 무엇인가?
• Claude Sonnet 5.5 또는 Claude Haiku 5.5를 사용하는 요청에서 max_tokens로 응답이 잘리면 토큰 한도를 얼마나 늘려 재시도할 것인가?