기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 모델에서 검증된 JSON 결과 가져오기
구조화된 출력은 모델 응답이 사용자 정의 JSON 스키마 및 도구 정의를 준수하도록 하여 프로덕션 AI 배포에서 사용자 지정 구문 분석 및 검증 메커니즘의 필요성을 줄이는 Amazon Bedrock의 기능입니다.
## 이점
구조화된 출력은 프로덕션 AI 애플리케이션의 중요한 문제를 해결합니다.
+ **스키마 규정 준수 보장 **- 프롬프트 기반 접근 방식에서 오류 발생률 및 재시도 루프 제거
+ **개발 복잡성 감소** - 사용자 지정 구문 분석 및 검증 로직이 필요하지 않음
+ **운영 비용 절감** - 실패한 요청 및 재시도를 줄입니다.
+ **프로덕션 신뢰성** - 예측 가능하고 기계 판독이 가능한 출력이 필요한 AI 애플리케이션을 자신 있게 배포할 수 있습니다.
## 작동 방식
구조화된 출력은 특정 스키마를 따르도록 모델 응답을 제한하여 다운스트림 처리에 대해 유효하고 구문 분석 가능한 출력을 보장합니다. 두 가지 보완 메커니즘을 통해 구조화된 출력을 사용할 수 있습니다.
### JSON 스키마 출력 형식
Anthropic Claude 모델이 포함된 InvokeModel API의 경우 `output_config.format` 요청 필드를 사용합니다. 개방형 가중치 모델의 경우 `response_format` 요청 필드를 사용합니다. Converse APIs의 경우 `outputConfig.textFormat` 요청 필드를 사용합니다. 모델의 응답은 지정된 JSON 스키마를 따릅니다.
### 엄격한 도구 사용
도구 정의에 `strict: true` 플래그를 추가하여 도구 이름 및 입력에 대한 스키마 검증을 활성화합니다. 그러면 모델의 도구 호출이 정의된 도구 입력 스키마를 따릅니다.
이러한 메커니즘은 동일한 요청에서 독립적으로 또는 함께 사용할 수 있습니다. 자세한 내용은 [Bedrock API 설명서를](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) 참조하세요.
### 요청 워크플로
다음은 Amazon Bedrock이 구조화된 출력으로 요청을 처리하는 방법을 설명합니다.
1. **초기 요청** - `outputConfig.textFormat`, `output_config.format`또는 `response_format` 파라미터를 통한 JSON 스키마 또는 추론 요청에 `strict: true` 플래그가 있는 도구 정의를 포함합니다.
1. **스키마 검증** - Amazon Bedrock은 지원되는 JSON 스키마 초안 2020년 12월 하위 집합과 비교하여 JSON 스키마 형식을 검증합니다. 스키마에 지원되지 않는 기능이 포함된 경우 Amazon Bedrock은 즉시 400 오류를 반환합니다.
1. **최초 컴파일** - 새 스키마의 경우 Amazon Bedrock은 최대 몇 분 정도 걸릴 수 있는 문법을 컴파일합니다.
1. **캐싱** - 성공적으로 컴파일된 문법은 처음 액세스한 후 24시간 동안 캐시됩니다. 캐시된 문법은 AWS 관리형 키로 암호화됩니다.
1. **후속 요청** - 동일한 계정의 동일한 스키마가 캐시된 문법을 사용하므로 오버헤드를 최소화하면서 표준 요청과 비슷한 추론 지연 시간이 발생합니다.
1. **응답** - 엄격한 스키마 규정 준수로 표준 추론 응답을 받습니다.
## 지원되는 JSON 스키마 기능
다음 JSON 스키마 초안 2020년 12월 기능이 지원됩니다.
+ 모든 기본 유형: `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만 해당)
다음 기능은 지원되지 *않습니다*.
+ 재귀 스키마
+ 외부 `$ref` 참조
+ 숫자 제약 조건(`minimum`, `maximum`, `multipleOf`)
+ 문자열 제약 조건(`minLength`, `maxLength`)
+ `additionalProperties`를 이외의 항목으로 설정 `false`
## 지원되는 APIs 또는 기능
다음 Amazon Bedrock 기능에서 구조화된 출력을 사용할 수 있습니다.
**Converse 및 ConverseStream APIs** - 대화 추론을 위해 Converse 및 ConverseStream APIs와 함께 구조화된 출력을 사용합니다.
**InvokeModel 및 InvokeModelWithResponseStream APIs**- 단일 턴 추론을 위해 InvokeModel 및 InvokeModelWithResponseStream APIs와 함께 구조화된 출력을 사용합니다.
**교차 리전 추론** - 추가 설정 없이 교차 리전 추론 내에서 구조화된 출력을 사용합니다.
**배치 추론** - 추가 설정 없이 배치 추론 내에서 구조화된 출력을 사용합니다.
**`bedrock-mantle` 엔드포인트의 Anthropic Messages API** - Anthropic 스타일 Messages API 경로(`https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages`)에서는 구조화된 출력이 지원되지 *않습니다*. `output_config.format` 파라미터가 400 오류와 함께 거부됩니다. Anthropic Claude 모델과 함께 구조화된 출력을 사용하려면 Converse API 또는 `bedrock-runtime` 엔드포인트의 InvokeModel API를 통해 요청을 전송합니다.
**참고**
구조화된 출력은 Anthropic 모델의 인용과 호환되지 않습니다. 구조화된 출력을 사용하는 동안 인용을 활성화하면 모델이 400 오류를 반환합니다.
## 지원되는 모델
구조화된 출력을 지원하는 모델을 확인하려면 [모델로](model-cards.md) 이동하여 관심 있는 모델을 선택하세요.
## 요청 예시
### JSON 스키마 출력 형식
다음 예제에서는 구조화된 출력과 함께 JSON 스키마 출력 형식을 사용하는 방법을 보여줍니다.
#### Converse API
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"text": "..."
}
]
}
],
"outputConfig": {
"textFormat": {
"type": "json_schema",
"structure": {
"jsonSchema": {
"schema": "{\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\", \"description\": \"title\"}, \"summary\": {\"type\": \"string\", \"description\": \"summary\"}, \"next_steps\": {\"type\": \"string\", \"description\": \"next steps\"}}, \"required\": [\"title\", \"summary\", \"next_steps\"], \"additionalProperties\": false}",
"name": "data_extraction",
"description": "Extract structured data from unstructured text"
}
}
}
}
}
```
#### InvokeModel(Anthropic Claude)
##### 예제 보기
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Given the following unstructured data, extract it into the provided structure."
},
{
"type": "text",
"text": "..."
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
}
}
}
```
#### InvokeModel(Open-weight 모델)
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": "Given the following unstructured data, extract it into the provided structure."
},
{
"role": "user",
"content": "..."
}
],
"inferenceConfig": {
"maxTokens": 3000,
"temperature": 1.0
},
"response_format": {
"json_schema": {
"name": "summarizer",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "title"
},
"summary": {
"type": "string",
"description": "summary"
},
"next_steps": {
"type": "string",
"description": "next steps"
}
},
"required": [
"title",
"summary",
"next_steps"
],
"additionalProperties": false
}
},
"type": "json_schema"
}
}
```
### 엄격한 도구 사용
다음 예제에서는 도구 사용과 함께 엄격한 필드를 사용하는 방법을 보여줍니다.
#### Converse API
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": [
{
"text": "What's the weather like in New York?"
}
]
}
],
"toolConfig": {
"tools": [
{
"toolSpec": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"inputSchema": {
"json": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
}
]
}
}
```
#### InvokeModel(Anthropic Claude)
##### 예제 보기
```
{
"anthropic_version": "bedrock-2023-05-31",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's the weather like in San Francisco?"
}
]
}
],
"max_tokens": 3000,
"temperature": 1.0,
"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": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
],
"additionalProperties": false
}
}
]
}
```
#### InvokeModel(Open-weight 모델)
##### 예제 보기
```
{
"messages": [
{
"role": "user",
"content": "What's the weather like in San Francisco?"
}
],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a specified location",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": [
"fahrenheit",
"celsius"
],
"description": "The temperature unit to use"
}
},
"required": [
"location",
"unit"
]
}
}
}
],
"tool_choice": "auto",
"max_tokens": 2000,
"temperature": 1.0
}
```