JSON 모드는 “json.loads()가 성공할까?”라는 질문 하나에 답합니다. “이게 내 코드가 기대하는 객체인가?”라는 두 번째 질문에는 답하지 않습니다.
작동 방식
Chat Completions API에서는 필드 하나로 켭니다.
{"response_format": {"type": "json_object"},
"messages": [
{"role": "system", "content": "Return JSON with keys name and email."},
{"role": "user", "content": "Reach me at Sara, sara@example.com"}]}
OpenAI API 레퍼런스는 이를 “the older JSON mode, which ensures the message the model generates is valid JSON.”(번역: 모델이 생성하는 메시지가 유효한 JSON이 되도록 보장하는 예전 방식의 JSON 모드)이라고 부릅니다. 여기에는 두 가지 규칙이 따릅니다. 먼저 메시지에서 JSON을 요청해야 합니다. OpenAI 가이드에 따르면 API는 “will throw an error if the string ‘JSON’ does not appear somewhere in the context.”(번역: 컨텍스트 어딘가에 ‘JSON’이라는 문자열이 없으면 오류를 던진다) 그리고 구조는 모델 마음대로입니다. 가이드는 JSON 모드가 “will not guarantee the output matches any specific schema.”(번역: 출력이 특정 스키마와 일치함을 보장하지 않는다)라고 밝힙니다.
구조화된 출력은 더 엄격한 선택지입니다. {"type": "json_schema", ...}로 JSON Schema를 전달하면 모델은 그 스키마에 맞춰 출력하도록 제약됩니다.
JSON 모드(json_object) |
구조화된 출력(json_schema) |
|
|---|---|---|
| 유효한 JSON | 예 | 예 |
| 필수 키와 타입 | 아니요 | 예 |
| 스키마를 직접 제공 | 아니요 | 예 |
| 프롬프트에 “JSON” 언급 필수 | 예(OpenAI) | 아니요 |
OpenAI는 “always using Structured Outputs instead of JSON mode when possible.”(번역: 가능하면 항상 JSON 모드 대신 Structured Outputs를 사용할 것)을 권합니다.
왜 중요한가
- 검증은 여전히 여러분의 몫입니다. JSON 모드에서는 키가 빠졌거나 숫자가 문자열로 와도 파싱은 성공하고, 나중에 실패합니다. 코드에서 스키마로 검증하세요.
- 잘림. 응답이
max_tokens에 도달하면 JSON이 불완전해집니다. 추론 모델은 생각하는 데도 같은 예산을 쓰므로 더 취약합니다. - 대비책. OpenAI 가이드는
json_schema를 쓸 수 없는 이전 모델에 JSON 모드를 안내합니다. 지원 여부는 제공업체와 모델마다 다르므로, 스키마가 받아들여지지 않을 때는 JSON 모드에 자체 검증을 더하는 것이 대비책입니다.
BroadNet Inference에서는
BroadNet의 API 레퍼런스는 GLM 5.3과 Qwen3.8 27B에 구조화된 출력을 표시합니다. 하지만 지원되는 response_format이 json_object인지 json_schema인지, DeepSeek V4.1 Flash와 BroadNet Gemma 4 VL 26B가 둘 중 하나라도 받는지는 밝히지 않습니다. 사용하는 모델에서 둘 다 테스트하세요. 스키마는 JSON Schema 생성기로 작성할 수 있습니다. JSON 모드와 json_schema 비교 글은 복구와 모니터링을 다루고, 인보이스 가이드는 이미지에서 JSON을 추출하는 방법을 보여 줍니다.