구조화된 출력이란 무엇인가요?

구조화된 출력은 언어 모델이 자유 텍스트 대신 코드가 파싱할 수 있는 JSON을 반환하게 합니다. JSON 모드는 구문적으로 유효한 JSON 객체를 반환하며, JSON 스키마는 더 나아가 응답이 정의한 스키마와 일치하도록 하고, 그 스키마에 필수 필드와 타입을 포함합니다.

개념

왜 구조화된 산출이 중요한가

애플리케이션은 종종 모델 답변을 데이터로 필요로 합니다: 청구서에서 추출한 필드, 지원 티켓의 라벨, 계획의 단계, 저장할 기록 등이 그렇습니다. 프롬프트에서 JSON 요청은 대부분 효과적이지만, JSON보다 먼저 설명이 붙거나, 그 주위에 코드 펜스가 붙거나, 누락된 필드가 있거나, 문자열로 표시된 숫자가 포함된 자유 텍스트가 들어올 수 있습니다. 이 모든 것은 파서를 깨뜨립니다.

구조화된 출력은 생성 자체를 제한합니다. 응답은 유효한 JSON이며, 스키마가 있으면 요청하신 정확한 형태도 포함되어 있습니다.

JSON 모드 및 JSON 스키마

두 가지 수준이 있으며, 둘 다 다음과 같이 설정되어 있습니다. response_format::

  • JSON 모드. {"type": "json_object"} 모델이 유효한 JSON 객체를 반환하도록 합니다. 프롬프트에 원하는 필드를 설명하면, 도형은 강제되지 않습니다.
  • JSON 스키마. {"type": "json_schema", "json_schema": {...}} takes a 이름, a 스키마 그리고 엄격함, 그리고 출력이 해당 JSON 스키마에 맞게 설정되도록 합니다: 필수 필드가 존재하고, 타입이 맞으며, 설정 시 추가 키가 없음 추가속성 로 거짓·.

모델이 이를 지원하고 코드가 정확한 필드에 의존할 때 JSON 스키마를 사용하세요. 코드가 읽는 모든 필드를 필수로 표시하고, 다음을 사용하세요. 열거 고정 선택의 경우, 중첩을 얕게 유지하고 짧은 것을 추가하세요 설명 이름만으로는 의미가 명확하지 않은 어떤 분야든 말이다.

청구서 추출기의 경우, 스키마는 다음을 요구할 수 있습니다 판매자 문자열로서, 합계 숫자로서, 통화 as an 열거 귀하가 수락하는 코드의 중, 그리고 line_items 객체 배열로서 설명 그리고 금액. 함께 엄격함 다음 맞아요각 응답은 해당 타입의 필드를 담고 있어, 코드가 매번 같은 키를 읽게 됩니다. JSON 모드에서는 프롬프트에 짧은 예제 객체를 넣어 모델이 따라갈 도형을 갖게 하세요.

모델 및 엔드포인트별 지원

지원은 모델별로 설정됩니다. 그 structured_output 필드 온 빨리 /v1/models/{model} 읽는 것 json_schema 모델이 스키마를 지원할 때 json_object JSON 모드만 지원하고, 이 페이지의 모델이 각 모델의 레벨을 표시하는 경우. 모델이 지원하지 않는 형식을 보내는 경우 반환 400·.

동일한 기능이 각 텍스트 엔드포인트의 고유한 형태에서 작동합니다:

  • /v1/chat/completions 그리고 /v1/completions:: response_format·.
  • /v1/responses 에:: text.format·.
  • /v1/messages 에:: output_config.포맷, 또는 response_format 나머지 요청 항목 옆에.

In the Playground, 이를 지원하는 채팅 모델은 Off, JSON 모드, JSON 스키마 컨트롤을 가지고 있으며, 스키마 입력란이 있습니다. 이 호환성 가이드 완전한 요청 예제를 제공합니다.

실무 지침

  • 그래도 인정해 주세요. 코드 내 모든 응답을 파싱하고 확인합니다. 출력 제한에 의해 차단된 응답, 다음과 같이 보고됨 finish_reason 길이, 는 불완전한 JSON이므로 설정해 두었습니다 max_tokens 예상하는 가장 큰 물체를 만들 수 있을 만큼 높다.
  • 추론 모델을 확인해 보세요. 일부 모델에서는 다음과 같은 요청이 있습니다 response_format 이성적으로 대답하지 않는 한 그것도 함께 설정되지 않는 한 enable thinking을 활성화·.
  • 지원 없는 모델들. 프롬프트에서 JSON을 요청하고, 도형 예시를 포함시키며, 결과를 검증하세요.
  • 적절한 기능을 선택하세요. JSON이 최종 답변일 때는 구조화된 출력을 사용하세요. 사용하기 함수 호출 모델이 코드가 실행할 동작을 선택해야 할 때입니다.

둘러보기 텍스트 모델 각 레벨을 지원하는 것을 비교하기 위해서입니다.

모델별 구조화 출력 지원

모델 62개. 각 모델 페이지에 요금표, 파라미터, 코드가 있습니다.

모델구조화된 출력컨텍스트 창
DeepSeek V4 Pro DeepSeekJSON Schema1M 토큰
DeepSeek V4 Pro 0813 DeepSeekJSON Schema1M 토큰
Fugu Max Sakana AIJSON Schema1M 토큰
Fugu Ultra v1.1 Sakana AIJSON Schema1M 토큰
Fugu Ultra v2.0 Sakana AIJSON Schema1M 토큰
Gemma 4 26B-A4B GoogleJSON Schema256K 토큰
Kimi K2.6 Moonshot AIJSON Schema256K 토큰
Kimi K2.7 Code Moonshot AIJSON Schema256K 토큰
모델 62개 모두 보기
모델구조화된 출력컨텍스트 창
Kimi K2.7 Code Highspeed Moonshot AIJSON Schema256K 토큰
Kimi K3 Moonshot AIJSON Schema1M 토큰
Kimi K3.1 Pro Moonshot AIJSON Schema1M 토큰
MiMo V2.6 Flash XiaomiJSON Schema1M 토큰
MiMo V2.6 Pro XiaomiJSON Schema1M 토큰
MiMo V2.6 Pro UltraSpeed XiaomiJSON Schema1M 토큰
Mistral Small 3.1 Mistral AIJSON Schema89.6K 토큰
Muse Glimmer 30B Meta AIJSON Schema128K 토큰
Muse Spark 1.1 Meta AIJSON Schema1M 토큰
Muse Spark 1.2 Meta AIJSON Schema1M 토큰
Muse Spark 1.3 Meta AIJSON Schema1M 토큰
Qwen3.5 4B Alibaba CloudJSON Schema256K 토큰
Qwen3.5 9B Alibaba CloudJSON Schema256K 토큰
Qwen3.5 Omni Plus Alibaba CloudJSON Schema192K 토큰
Qwen3.6 35B A3B Alibaba CloudJSON Schema128K 토큰
Qwen3.7 Flash Alibaba CloudJSON Schema983.6K 토큰
Qwen3.7 Max Alibaba CloudJSON Schema983.6K 토큰
Qwen3.7 Plus Alibaba CloudJSON Schema983.6K 토큰
Qwen3.8 27B Alibaba CloudJSON Schema256K 토큰
Qwen3.8 Flash Alibaba CloudJSON Schema983.6K 토큰
Qwen3.8 Max Alibaba CloudJSON Schema983.6K 토큰
Qwen3.8 Max 0902 Alibaba CloudJSON Schema983.6K 토큰
Qwen3.8 Omni Flash Alibaba CloudJSON Schema1.01M 토큰
Qwen4 Max Alibaba CloudJSON Schema983.6K 토큰
Seed 2.0 Lite ByteDanceJSON Schema229.1K 토큰
Seed 2.0 Mini ByteDanceJSON Schema229.2K 토큰
Seed 2.0 Pro ByteDanceJSON Schema229.1K 토큰
Seed 2.1 Turbo ByteDanceJSON Schema229.1K 토큰
Step 5 Preview StepFunJSON Schema1.02M 토큰
DeepSeek V4 Flash 0731 DeepSeekJSON 모드1M 토큰
DeepSeek V4.1 Flash 1017 DeepSeekJSON 모드1M 토큰
Fugu Ultra v1.0 Sakana AIJSON 모드1M 토큰
GLM 4.5 Flash Z.aiJSON 모드128K 토큰
GLM 4.6V Flash Z.aiJSON 모드128K 토큰
GLM 4.6V FlashX Z.aiJSON 모드128K 토큰
GLM 4.7 Flash Z.aiJSON 모드202.8K 토큰
GLM 4.7 FlashX Z.aiJSON 모드202.8K 토큰
GLM 5.1 Z.aiJSON 모드202.7K 토큰
GLM 5.2 Z.aiJSON 모드1M 토큰
GLM 5.3 Z.aiJSON 모드1M 토큰
GLM 5.3 Flash Z.aiJSON 모드1M 토큰
Mistral Small 4 Mistral AIJSON 모드256K 토큰
Qwen3.5 122B-A10B Alibaba CloudJSON 모드258K 토큰
Qwen3.5 27B Alibaba CloudJSON 모드258K 토큰
Qwen3.5 35B-A3B Alibaba CloudJSON 모드258K 토큰
Qwen3.5 397B-A17B Alibaba CloudJSON 모드258K 토큰
Qwen3.5 Flash Alibaba CloudJSON 모드995.9K 토큰
Qwen3.5 Plus Alibaba CloudJSON 모드983.6K 토큰
Qwen3.6 27B Alibaba CloudJSON 모드224K 토큰
Qwen3.6 Flash Alibaba CloudJSON 모드983.6K 토큰
Qwen3.6 Plus Alibaba CloudJSON 모드983.6K 토큰
Step 3.7 Flash StepFunJSON 모드256K 토큰
StepAudio 2.5 Chat StepFunJSON 모드256K 토큰
StepAudio 3 Chat StepFunJSON 모드256K 토큰

자주 묻는 질문

JSON 모드와 JSON 스키마의 차이점은 무엇인가요?

JSON 모드는 유효한 JSON 객체를 반환하지만, 그 형태는 프롬프트에 따라 남겨둡니다. JSON 스키마는 응답이 필수 필드와 타입을 포함한 제공한 스키마와 일치하도록 만듭니다.

어떤 모델들이 구조화된 출력을 지원하나요?

지원은 모델별로 적용됩니다. 각 모델의 structured_output 필드는 스키마 지원의 경우 json_schema, JSON 모드의 경우 json_object로 표시되며, 지원되지 않는 형식 요청은 400 오류를 반환합니다.

그래도 JSON을 검증해야 하나요?

네. 응답은 출력 제한에 의해 차단될 수 있고, 애플리케이션에는 스키마가 표현할 수 없는 규칙이 있을 수 있으니 모든 응답을 구문 분석하고 검증하세요.

Responses 또는 Messages 엔드포인트와 함께 구조화된 출력을 사용할 수 있나요?

예. Responses 엔드포인트는 text.format을 사용하며, Messages 엔드포인트는 output_config.format 또는 response_format 필드를 허용합니다.

더 나은 엔드포인트를 사용할 준비가 되셨나요?

저희 가격을 확인하시거나 저희 스택에 자체 모델을 배포하고 싶으시면 연락해 주세요.