BroadRouter
시작하기

JSON 모드(JSON mode)

업데이트

JSON 모드는 OpenAI 방식 API의 response_format {"type": "json_object"} 같은 LLM API 설정으로, 모델의 응답을 파싱 가능한 유효한 JSON으로 만듭니다. JSON Schema를 쓰는 구조화된 출력과 달리, 객체에 어떤 키와 타입, 값이 들어갈지는 보장하지 않습니다.

다른 이름: JSON 모드, JSON 출력 모드, JSON 응답 모드, response_format json_object, json_object, JSON output mode, JSON response mode

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을 추출하는 방법을 보여 줍니다.

자주 묻는 질문

JSON 모드와 구조화된 출력은 같은 건가요?

아닙니다. OpenAI 가이드에 따르면 둘 다 유효한 JSON을 만들지만, 스키마 준수를 보장하는 것은 Structured Outputs뿐입니다. JSON 모드는 유효하기만 하면 어떤 객체든 반환할 수 있습니다.

JSON 모드에서 JSON이라는 단어와 관련된 오류가 나는 이유는 무엇인가요?

OpenAI는 메시지 어딘가에 JSON을 생성하라는 지시가 있어야 하며, 컨텍스트에 "JSON"이라는 문자열이 없으면 오류를 반환합니다.

JSON 모드에서도 깨진 JSON이 나올 수 있나요?

네. 응답이 max_tokens나 컨텍스트 한도에서 잘리면 그렇습니다. 파싱하기 전에 finish_reason을 확인하세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기