기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 모델에서 검증된 JSON 결과 가져오기
<a name="structured-output"></a>

구조화된 출력은 모델 응답이 사용자 정의 JSON 스키마 및 도구 정의를 준수하도록 하여 프로덕션 AI 배포에서 사용자 지정 구문 분석 및 검증 메커니즘의 필요성을 줄이는 Amazon Bedrock의 기능입니다.

## 이점
<a name="structured-output-benefits"></a>

구조화된 출력은 프로덕션 AI 애플리케이션의 중요한 문제를 해결합니다.
+ **스키마 규정 준수 보장 **- 프롬프트 기반 접근 방식에서 오류 발생률 및 재시도 루프 제거
+ **개발 복잡성 감소** - 사용자 지정 구문 분석 및 검증 로직이 필요하지 않음
+ **운영 비용 절감** - 실패한 요청 및 재시도를 줄입니다.
+ **프로덕션 신뢰성** - 예측 가능하고 기계 판독이 가능한 출력이 필요한 AI 애플리케이션을 자신 있게 배포할 수 있습니다.

## 작동 방식
<a name="structured-output-how-it-works"></a>

구조화된 출력은 특정 스키마를 따르도록 모델 응답을 제한하여 다운스트림 처리를 위한 유효하고 구문 분석 가능한 출력을 보장합니다. 두 가지 보완 메커니즘을 통해 구조화된 출력을 사용할 수 있습니다.

### JSON 스키마 출력 형식
<a name="structured-output-json-schema"></a>

Anthropic Claude 모델이 포함된 InvokeModel API의 경우 `output_config.format` 요청 필드를 사용합니다. 개방형 가중치 모델의 경우 `response_format` 요청 필드를 사용합니다. Converse APIs의 경우 `outputConfig.textFormat` 요청 필드를 사용합니다. 모델의 응답은 지정된 JSON 스키마를 따릅니다.

### 엄격한 도구 사용
<a name="structured-output-strict-tool-use"></a>

도구 정의에 `strict: true` 플래그를 추가하여 도구 이름 및 입력에 대한 스키마 검증을 활성화합니다. 그러면 모델의 도구 호출이 정의된 도구 입력 스키마를 따릅니다.

이러한 메커니즘은 동일한 요청에서 독립적으로 또는 함께 사용할 수 있습니다. 자세한 내용은 [Bedrock API 설명서를](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) 참조하세요.

### 요청 워크플로
<a name="structured-output-request-workflow"></a>

다음은 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. **응답** - 엄격한 스키마 규정 준수로 표준 추론 응답을 받습니다.

## 지원되는 APIs 또는 기능
<a name="structured-output-supported-apis"></a>

다음 Amazon Bedrock 기능에서 구조화된 출력을 사용할 수 있습니다.

**Converse 및 ConverseStream APIs** - 대화 추론을 위해 Converse 및 ConverseStream APIs와 함께 구조화된 출력을 사용합니다.

**InvokeModel 및 InvokeModelWithResponseStream APIs**- 단일 턴 추론을 위해 InvokeModel 및 InvokeModelWithResponseStream APIs와 함께 구조화된 출력을 사용합니다.

**교차 리전 추론** - 추가 설정 없이 교차 리전 추론 내에서 구조화된 출력을 사용합니다.

**배치 추론** - 추가 설정 없이 배치 추론 내에서 구조화된 출력을 사용합니다.

**참고**  
구조화된 출력은 Anthropic 모델의 인용과 호환되지 않습니다. 구조화된 출력을 사용하는 동안 인용을 활성화하면 모델이 400 오류를 반환합니다.

## 지원되는 모델
<a name="structured-output-supported-models"></a>

구조화된 출력은 일반적으로 일부 Amazon Bedrock 서버리스 모델의 모든 상용 AWS 리전에서 사용할 수 있습니다. 지원되는 모델 목록은 기능별 모델 지원을 참조하세요.

### 지원되는 모든 모델 보기
<a name="w2aac13c32c35c11b5b1"></a>

Anthropic  
+ Claude Haiku 4.5(`anthropic.claude-haiku-4-5-20251001-v1:0`)
+ Claude Sonnet 4.5(`anthropic.claude-sonnet-4-5-20250929-v1:0`)
+ Claude Opus 4.5(`anthropic.claude-opus-4-5-20251101-v1:0`)
+ Claude Opus 4.6(`anthropic.claude-opus-4-6-v1`)

쿠엔  
+ Qwen3 235B A22B 2507(`qwen.qwen3-235b-a22b-2507-v1:0`)
+ Qwen3 32B(집약적)(`qwen.qwen3-32b-v1:0`)
+ Qwen3-Coder-30B-A3B-Instruct(`qwen.qwen3-coder-30b-a3b-v1:0`)
+ Qwen3 Coder 480B A35B 지침(`qwen.qwen3-coder-480b-a35b-v1:0`)
+ Qwen3 다음 80B A3B(`qwen.qwen3-next-80b-a3b`)
+ Qwen3 VL 235B A22B(`qwen.qwen3-vl-235b-a22b`)

OpenAI  
+ gpt-oss-120b(`openai.gpt-oss-120b-1:0`)
+ gpt-oss-20b(`openai.gpt-oss-20b-1:0`)
+ GPT OSS 보호 120B(`openai.gpt-oss-safeguard-120b`)
+ GPT OSS 보호 20B(`openai.gpt-oss-safeguard-20b`)

DeepSeek  
+ DeepSeek-V3.1(`deepseek.v3-v1:0`)

Google  
+ Gemma 3 12B IT(`google.gemma-3-12b-it`)
+ Gemma 3 27B PT(`google.gemma-3-27b-it`)

MiniMax  
+ MiniMax M2(`minimax.minimax-m2`)

Mistral AI  
+ Magistral Small 2509(`mistral.magistral-small-2509`)
+ 미니스트럴 3B(`mistral.ministral-3-3b-instruct`)
+ 미니스트럴 3 8B(`mistral.ministral-3-8b-instruct`)
+ 미니스트럴 14B 3.0(`mistral.ministral-3-14b-instruct`)
+ Mistral Large 3(`mistral.mistral-large-3-675b-instruct`)
+ Voxtral Mini 3B 2507(`mistral.voxtral-mini-3b-2507`)
+ Voxtral Small 24B 2507(`mistral.voxtral-small-24b-2507`)

달샷 AI  
+ 키미 K2 Thinking(`moonshot.kimi-k2-thinking`)

NVIDIA  
+ NVIDIA Nemotron Nano 12B v2 VL BF16(`nvidia.nemotron-nano-12b-v2`)
+ NVIDIA Nemotron Nano 9B v2(`nvidia.nemotron-nano-9b-v2`)

## 요청 예시
<a name="structured-output-examples"></a>

### JSON 스키마 출력 형식
<a name="structured-output-json-schema-examples"></a>

다음 예제에서는 구조화된 출력과 함께 JSON 스키마 출력 형식을 사용하는 방법을 보여줍니다.

#### Converse API
<a name="json-schema-converse"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b3b5b3b1"></a>

```
{
  "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)
<a name="json-schema-invokemodel-claude"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b3b7b3b1"></a>

```
{
  "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 모델)
<a name="json-schema-invokemodel-openweight"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b3b9b3b1"></a>

```
{
  "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"
  }
}
```

### 엄격한 도구 사용
<a name="structured-output-strict-tool-examples"></a>

다음 예제에서는 도구 사용과 함께 엄격한 필드를 사용하는 방법을 보여줍니다.

#### Converse API
<a name="strict-tool-converse"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b5b5b3b1"></a>

```
{
  "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)
<a name="strict-tool-invokemodel-claude"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b5b7b3b1"></a>

```
{
  "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 모델)
<a name="strict-tool-invokemodel-openweight"></a>

##### 예제 보기
<a name="w2aac13c32c35c13b5b9b3b1"></a>

```
{
  "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
}
```