코드는 예측 가능한 입력을 필요로 합니다. 구조화된 출력은 모델의 자유로운 텍스트를 프로그램이 믿고 쓸 수 있는 데이터로 바꿉니다.
작동 방식
제어 수준은 세 가지입니다.
| 방법 | 얻는 결과 |
|---|---|
| 프롬프트로 요청 | 보통 JSON이지만, 때때로 추가 텍스트가 붙거나 필드가 빠짐 |
| JSON 모드 | 유효한 JSON, 구조는 자유 |
| 스키마를 지정한 구조화된 출력 | 스키마와 일치하는 JSON |
OpenAI 형식에서 JSON 모드는 response_format: {"type": "json_object"}입니다. 구조화된 출력은 스키마를 전달합니다.
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "invoice",
"strict": true,
"schema": {
"type": "object",
"properties": {
"vendor": { "type": "string" },
"total": { "type": "number" }
},
"required": ["vendor", "total"],
"additionalProperties": false
}
}
}
OpenAI 레퍼런스는 json_schema 타입이 “ensures the model will match your supplied JSON schema.”(번역: 모델이 제공한 JSON 스키마와 일치하도록 보장한다)고 설명합니다. 많은 제공업체는 이를 제약 디코딩(constrained decoding)으로 구현합니다. 각 단계에서 모델이 생성할 수 있는 토큰을 제한해, 스키마를 깨는 출력이 아예 생성되지 않게 하는 방식입니다.
왜 중요한가
- 파싱 오류 감소. 정보 추출 파이프라인, 분류기, 에이전트가 필드를 바로 읽을 수 있습니다.
- 더 간단한 프롬프트. 긴 형식 지시문을 스키마가 대신합니다.
- 완전한 보장은 아닙니다. OpenAI 가이드는 앱에서 여전히 거절, 불완전한 응답, 오류를 처리해야 한다고 말합니다.
max_tokens에서 잘린 응답은 스키마와 상관없이 깨진 JSON입니다.
OpenAI 호환 API마다 지원 범위가 다릅니다. json_schema만 받는 곳, json_object만 받는 곳, 이 필드를 무시하는 곳이 있습니다. 의존하기 전에 확인하세요.
BroadNet Inference에서는
BroadNet 문서는 GLM 5.3과 Qwen3.8 27B에서 구조화된 출력을 지원한다고 안내합니다. 문서에 요청 파라미터 이름은 나와 있지 않으므로 사용하는 모델에서 response_format을 테스트하고, 어떤 경우든 오류 처리를 갖춘 JSON 파서를 유지하세요. LLM JSON 출력 검증 도구는 응답이 어디서 깨지는지 보여 주고 스키마와 대조해 검사합니다. 두 모델 모두 먼저 추론하므로 max_tokens에 생각용 토큰과 JSON을 모두 담을 여유를 두세요.
구조화된 출력은 비전 모델과 잘 어울립니다. 아랍어 청구서 가이드는 이미지를 보내고 필드를 JSON으로 요청합니다. 답변이 아니라 동작이 필요하다면 도구 호출을 쓰세요.
흔한 실수
- strict 모드에서
additionalProperties: false를 빠뜨리거나, 모든 필드를required에 나열하지 않는 것. - 파싱하기 전에
finish_reason을 확인하지 않는 것.