Amazon Bedrock이 이제 모델을 사용할 수 있는 리전에서 bedrock-runtime 및 bedrock-mantle 엔드포인트 모두에 대해 모든 Anthropic Claude 모델에 대한 구조화된 출력을 지원합니다.
Boto3와 bedrock-runtime API를 통해 Claude를 호출하든, Messages API와 bedrock-mantle 엔드포인트를 통해 호출하든, 이제 정의된 구조를 준수하는 스키마 호환 JSON 응답을 받을 수 있습니다. 더 이상 커스텀 파싱, 재시도 로직 또는 후처리가 필요하지 않습니다.
실용적인 활용 사례
Amazon Bedrock에서 Claude의 구조화된 출력을 사용하면 다양한 산업 분야에서 안정적이고 스키마를 준수하는 작업을 자동화할 수 있습니다. 예를 들어 재무 실적 보고서와 컴플라이언스 문서에서 필요한 모든 필드를 추출하거나, 임상 노트를 전자 건강 기록(EHR)으로 파싱하거나, 일관되고 검증된 결과로 제품 카탈로그를 보강할 수 있습니다. 또한 계약서에서 주요 조항, 당사자 및 의무를 분석하거나, 의도, 감성, 개체가 항상 애플리케이션의 데이터 모델과 일치하는 지능형 지원 티켓 라우팅을 구현할 수도 있습니다.
Amazon Bedrock의 구조화된 출력으로 달라지는 점
구조화된 출력은 제약 디코딩(constrained decoding)을 사용하여 사후가 아니라 토큰 생성 중에 JSON 스키마를 강제 적용합니다. 모델은 스키마를 위반하는 토큰을 생성하지 않습니다. 이를 통해 출력 형식화가 확률적 방식에서 결정론적 방식으로 바뀝니다.
이제 두 Amazon Bedrock 엔드포인트 모두에서 두 가지 상호 보완적인 메커니즘을 사용할 수 있습니다:
| 기능 | 목적 | 사용 사례 |
| JSON Schema 출력 형식 | 모델의 응답 구조 제어 | 데이터 추출, 보고서 생성, API 응답 |
| 엄격한 도구 사용(Strict tool use) | 스키마에 대한 도구 파라미터 검증 | 에이전트형 워크플로, 함수 호출, 다단계 자동화 |
사용자에게 의미하는 것
각 응답은 유효한 JSON이므로 더 이상 JSON.parse() 오류나 파싱 예외를 겪지 않습니다. 응답은 타입 안전성도 갖추고 있습니다. 즉, 필드 타입이 강제 적용되고 필수 필드는 항상 존재합니다. 출력이 항상 스키마를 준수하므로 스키마 위반을 처리하기 위한 재시도가 필요 없어 통합이 더 안정적입니다. 또한 구조화된 출력은 응답을 스키마에 정의된 필드로만 제한하므로 출력 토큰 수가 줄어들어 대량 워크로드에서 추론 비용을 낮출 수 있습니다. 이러한 특성 덕분에 구조화된 출력은 프로덕션 준비가 완료되어 추가적인 스키마 검증 코드 없이도 대규모로 배포할 수 있습니다.
지원 모델 및 가용성
구조화된 출력은 배치 추론과 함께 작동하므로 스키마 호환 출력을 받으면서 대량의 요청을 비동기적으로 처리할 수 있습니다. bedrock-runtime 엔드포인트에서는 크로스 리전 추론과도 함께 작동하므로 추가 설정 없이 AWS 리전 전반에서 사용할 수 있습니다. 실시간 응답이 필요한 경우, 구조화된 응답을 타입화된 이벤트로 스트리밍할 수 있습니다.
작동 방식
JSON 스키마와 함께 요청을 보내면 내부적으로 다음과 같은 일이 일어납니다:
- 스키마 검증 – Amazon Bedrock이 JSON 스키마를 지원되는 JSON Schema Draft 2020-12 하위 집합에 대해 검증합니다.
- 문법 컴파일 – 새로운 스키마의 경우 Amazon Bedrock이 문법 아티팩트를 컴파일합니다(첫 번째 요청은 약간 더 오래 걸릴 수 있습니다).
- 캐싱 – 컴파일된 문법이 24시간 동안 캐시되어 이후 요청이 더 빨라집니다.
- 제약 생성(Constrained generation) – 모델이 스키마와 일치하는 유효한 JSON을 생성하는 토큰을 생성합니다.
성능 고려 사항
성능 면에서, 새로운 스키마를 사용하는 첫 번째 요청은 Amazon Bedrock이 생성이 시작되기 전에 문법 아티팩트를 컴파일하기 때문에 더 오래 걸릴 수 있습니다. 그 초기 컴파일 이후에는 컴파일된 문법이 캐시되어 있기 때문에 동일한 스키마를 사용하는 이후 요청은 최소한의 오버헤드로 실행됩니다. 이 캐시는 계정 범위로 적용되며 첫 액세스 시점부터 24시간 동안 유지됩니다. JSON 스키마의 구조를 변경하면 캐시가 무효화되고 새로운 컴파일이 트리거되는 반면, name 또는 description 필드만 변경하면 캐시된 문법이 그대로 유지됩니다.
시작하기: InvokeModel API(bedrock-runtime)를 사용한 구조화된 출력
InvokeModel API는 Anthropic 네이티브 요청 본문을 받으므로 스키마는 output_config.format JSON 문자열이 아닌 JSON 객체로 전달됩니다. 다음 예제는 boto3와 Anthropic Claude 모델을 사용하여 고객 이메일에서 구조화된 리드 데이터를 추출하는 방법을 보여줍니다:
Python
import boto3
import json
REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)
# Define the JSON schema for structured output
schema = {
"type": "object",
"properties": {
"name": {"type": "string", "description": "Customer name"},
"email": {"type": "string", "description": "Customer email address"},
"plan_interest": {"type": "string", "description": "Product plan of interest"},
"demo_requested": {"type": "boolean", "description": "Whether a demo was requested"}
},
"required": ["name", "email", "plan_interest", "demo_requested"],
"additionalProperties": False
}
# Make a request with structured outputs via the InvokeModel API
# (reusing the schema defined for the Converse example)
response = bedrock_runtime.invoke_model(
modelId="global.anthropic.claude-sonnet-5-5",
body=json.dumps({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 512,
"messages": [
{"role": "user", "content": (
"Paulo Santos (paulo@example.com) is interested in our Enterprise plan "
"and wants to schedule a demo for next Tuesday at 2pm."
)}
],
"output_config": {"format": {"type": "json_schema", "schema": schema}}
})
)
body = json.loads(response["body"].read())
# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
print(json.dumps(json.loads(result_text), indent=2))
elif body["stop_reason"] == "max_tokens":
print("Response truncated: increase max_tokens and retry.")JSON
{
"name": "Paulo Santos",
"email": "paulo@example.com",
"plan_interest": "Enterprise",
"demo_requested": true
}응답은 스키마를 따릅니다. 추가 검증이 필요하지 않습니다.
Messages API를 포함한 추가 API 사용 예제는 함께 제공되는 샘플 노트북.
에이전트형 워크플로우를 위한 엄격한 도구 사용
Amazon Bedrock Mantle 은 서버 측 도구, 백그라운드 추론, 상태 유지 대화를 갖춘 에이전트형 애플리케이션을 위해 설계되었습니다. bedrock-mantle 엔드포인트에서 엄격한 도구 사용을 통해 이제 도구 파라미터가 입력 스키마와 정확히 일치함을 보장할 수 있습니다. 다음 예제는 엄격한 스키마 적용으로 도구를 정의하는 방법을 보여줍니다:
Import json
from anthropic import AnthropicBedrockMantle
# Reusing the client created in the Messages API example
client = AnthropicBedrockMantle(aws_region="us-east-1")
message = client.messages.create(
model="anthropic.claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
tools=[
{
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": True,
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g., San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["location", "unit"],
"additionalProperties": False
}
}
]
)
#Tool inputs conform to the schema
for block in message.content:
if block.type == "tool_use":
print(f"Tool: {block.name}")
print(f"Input: {json.dumps(block.input, indent=2)}")설정 strict: true 은 모델의 도구 입력이 스키마와 정확히 일치하도록 제약합니다. location 필드는 항상 문자열이고, unit 필드는 항상 celsius 또는 fahrenheit입니다. 모델은 스키마 밖의 필드를 추가할 수 없으므로 도구 입력에는 스키마가 지정한 내용만 포함됩니다.
이것은 웹 검색 및 코드 인터프리터와 같은 서버 측 도구로 다단계 워크플로우를 오케스트레이션하는 모델이 사용되는 Amazon Bedrock Mantle의 에이전트형 사용 사례에서 특히 유용합니다.
Claude 구조화된 출력의 주요 사용 사례
구조화된 출력은 다음 세 가지 일반적인 패턴에서 오류 처리 복잡성을 가장 크게 줄여줍니다:
- 데이터 추출: 송장, 계약서, 이메일, 전사(transcript)에서 항상 스키마와 일치하는 JSON으로 필드를 추출하여 데이터베이스나 고객 관계 관리(CRM) 시스템에 바로 로드할 수 있도록 합니다.
- 안정적인 에이전트 도구 호출: 생성 시점에 도구 인수를 해당 스키마와 대조하여 검증하므로, 다단계 에이전트 워크플로우가 잘못된 형식의 입력으로 인한 실패 없이 실행됩니다.
- 대규모 분류: 라우팅, 조정, 평가를 위해 티켓, 리드 또는 콘텐츠를 의도, 우선순위, 감정별로 분류합니다.
Claude Haiku 5.5는 요약, 압축(compaction), 데이터베이스 쿼리, 분류 요청과 같은 빠르고 반복적인 워크로드를 안정적으로 처리합니다. 다음 예제는 Invoke API와 Haiku 5.5를 사용하여 수신 데이터를 분류하고 라우팅하는 방법을 보여줍니다:
import boto3
import json
REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)
# Classification schema: enums restrict output to a fixed set of labels
schema = {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": ["billing", "technical", "account", "sales", "other"],
"description": "Primary ticket category"
},
"priority": {
"type": "string",
"enum": ["low", "medium", "high", "urgent"],
"description": "Urgency based on business impact"
},
"sentiment": {
"type": "string",
"enum": ["positive", "neutral", "negative"],
"description": "Customer sentiment"
},
"escalate": {"type": "boolean", "description": "Whether a human should review immediately"},
"reason": {"type": "string", "description": "One-sentence justification for the classification"}
},
"required": ["category", "priority", "sentiment", "escalate", "reason"],
"additionalProperties": False
}
ticket = (
"Our production API calls have been failing with 500 errors since this morning. "
"We're losing orders every minute. This is the second outage this month!"
)
# Make a request with structured outputs via the InvokeModel API
response = bedrock_runtime.invoke_model(
modelId="global.anthropic.claude-haiku-5-5",
body=json.dumps({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 512,
"system": "You are a support ticket classifier. Classify the ticket accurately.",
"messages": [
{"role": "user", "content": f"Classify this support ticket:\n\n{ticket}"}
],
"output_config": {"format": {"type": "json_schema", "schema": schema}}
})
)
body = json.loads(response["body"].read())
# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
result = json.loads(result_text)
print(json.dumps(result, indent=2))
# Route the ticket based on the guaranteed-valid labels
if result["escalate"]:
print(f"Escalating to on-call: {result['category']} / {result['priority']}")
elif body["stop_reason"] == "max_tokens":
print("Response truncated: increase max_tokens and retry.")요구 사항 및 모범 사례
Amazon Bedrock에서 구조화된 출력을 효과적으로 사용하려면 다음 지침을 따르십시오:
- 모든 객체에 additionalProperties: false 설정: 구조화된 출력이 작동하려면 이것이 필요합니다. 이것이 없으면 스키마가 허용되지 않습니다.
- 설명적인 필드 이름과 설명 사용: 모델은 속성 이름과 설명을 사용하여 추출할 데이터를 이해합니다. 다음과 같은 명확한 이름은
customer_email과 같은 일반적인 이름보다 성능이 뛰어납니다field1. - 제한된 값에는 enum 사용: 필드에 유효한 값의 집합이 제한되어 있는 경우
enum를 사용하여 옵션을 제약하십시오. - 기본으로 시작한 후 복잡성을 점진적으로 추가하세요: 최소한의 필수 필드로 시작하고 복잡성을 점진적으로 추가하십시오. 기본 스키마는 더 빠르게 컴파일되고, 디버깅이 쉬우며, 스키마가 Converse API 페이로드 크기에 포함되기 때문에 요청 페이로드를 가볍게 유지할 수 있습니다.
- 스키마를 재사용하여 캐싱의 이점을 활용하세요: 여러 요청에서 스키마를 재사용하도록 애플리케이션을 구성하십시오. 24시간 문법 캐시는 반복 쿼리의 성능을 향상시킵니다.
- 모든 응답에서 중지 사유(stop reason)를 확인하세요: 두 가지 시나리오에서 비준수 응답이 발생할 수 있습니다: 거부(모델이 안전상의 이유로 거절하는 경우)와 토큰 한도(완료 전에
max_tokens에 도달하는 경우). 코드에서 두 경우를 모두 처리하십시오. - 배포 전에 현실적인 데이터로 테스트하세요: 프로덕션을 대표하는 입력으로 스키마를 검증하십시오. 실제 데이터의 엣지 케이스는 종종 스키마 설계 문제를 드러냅니다.
추가 모범 사례 및 스키마 설계 권장 사항은 Amazon Bedrock 사용 설명서의 Structured outputs 를 참조하십시오.
지원되는 JSON Schema 기능
- 모든 기본 유형:
object,array,string,integer,number,boolean,null. enum(문자열, 숫자, 불리언 또는 null만 해당).const,anyOf,allOf(제한 있음).$ref,$def및definitions(내부 참조만 해당).- 문자열 형식:
date-time,time,date,duration,email,hostname,uri,ipv4,ipv6,uuid. - 배열
minItems(0과 1 값만 해당).
지원되지 않음
이 키워드들은 API에서 허용되지만 생성 과정에서 강제되지 않습니다. 이들을 포함하는 요청은 성공적인 응답을 반환하며, 모델은 여전히 이들을 위반하는 값을 반환할 수 있습니다. 스키마에 의존하여 강제하기보다 애플리케이션에서 이러한 제약 조건을 검증하십시오.
- 재귀 스키마.
- 외부
$ref참조. - 숫자 제약 조건 (
minimum,maximum,multipleOf). - 문자열 제약 조건 (
minLength,maxLength). additionalPropertiesfalse 이외의 값으로 설정된 경우.
결론
Amazon Bedrock에서 Anthropic Claude 모델을 위한 구조화된 출력은 프로덕션 AI 애플리케이션에 필요한 신뢰성을 제공합니다. 현재 bedrock-runtime 및 bedrock-mantle 엔드포인트 모두에서 사용할 수 있습니다. JSON Schema 출력 형식과 strict tool use를 결합하면 추가 검증이 필요 없는 데이터 파이프라인을 구축할 수 있습니다. 또한 사용자 지정 파싱이나 재시도 로직 없이도 신뢰할 수 있는 에이전트 워크플로와 프로덕션 AI 애플리케이션을 만들 수 있습니다.
Amazon Bedrock에서 Claude를 위한 구조화된 출력이 이제 정식 출시되었습니다. 자세한 내용은 Amazon Bedrock 설명서 를 참조하고 저희의 샘플 노트북.
을 살펴보십시오. 검증된 스키마 준수 JSON이 귀하의 조직에서 어떤 워크플로를 개선할 수 있을까요? 의견과 질문을 댓글로 공유해 주십시오.