BroadRouter
시작하기

JSON 모드 vs json_schema: 믿고 쓸 수 있는 구조화된 출력

BroadNet Inference 팀 · 4분 분량 · 게시

JSON 모드(response_format json_object)는 유효한 JSON만 보장합니다. 구조화된 출력(response_format json_schema)은 제공업체가 강제하는 경우 정의한 필드와 타입까지 보장합니다. 어느 쪽이든 finish_reason을 확인하고, 파싱하고, Pydantic 모델 같은 스키마로 검증하세요. 검증에 실패하면 오류를 돌려보내 다시 요청하되, 시도 횟수에는 엄격한 상한을 두세요.

코드에는 데이터가 필요하지만 모델은 텍스트를 씁니다. 구조화된 출력이 이 간극을 메우지만, “모델이 JSON을 반환한다”는 말은 요청 방식에 따라 세 가지 다른 뜻이 됩니다. 이 글에서는 OpenAI 호환 오픈 모델에서 쓸 수 있는 방식을 비교하고, 각각을 요청하는 방법과 프로덕션에 바로 넣을 수 있는 검증·수정 루프를 보여 드립니다.

JSON 모드와 json_schema는 무엇이 다른가요?

방식 요청 보장되는 것
프롬프트만 “다음 필드로 JSON으로 답하세요…” 없음. 대개 JSON이지만 가끔 다른 텍스트가 섞임
JSON 모드 response_format: {"type": "json_object"} 유효한 JSON, 구조는 자유
구조화된 출력 response_format: {"type": "json_schema", ...} 스키마에 맞는 JSON(강제되는 경우)

OpenAI의 Structured Outputs 가이드는 이렇게 분명히 말합니다. “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.”(번역: 둘 다 유효한 JSON 생성을 보장하지만, 스키마 준수를 보장하는 것은 Structured Outputs뿐입니다.) 그리고 가능하면 언제나 JSON 모드보다 구조화된 출력을 쓰라고 권장합니다.

오픈 모델 제공업체에서는 이 보장이 서버의 구현 방식에 달려 있습니다. 많은 곳이 스키마를 깨뜨릴 토큰을 막는 제약 디코딩(constrained decoding)을 씁니다. 필드를 받기만 하고 강제하지 않는 곳도 있습니다. 그래서 아래 코드는 어떤 경우든 검증합니다.

json_schema는 어떻게 요청하나요?

import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}

Pydantic이 클래스에서 JSON Schema를 생성하므로 스키마와 검증기가 서로 어긋나지 않습니다. Pydantic을 쓰지 않는다면 JSON 스키마 생성기가 예시 객체로 strict 모드 스키마를 만들어 줍니다. strict 모드에서 OpenAI는 additionalProperties: false와 모든 속성을 required로 나열할 것을 요구합니다.

내 제공업체는 어떤 모드를 지원하나요?

모델 위에 무언가를 만들기 전에, 모델마다 한 번씩 이 테스트를 돌리세요.

  1. 필드를 하나 더 추가하도록 유도하는 프롬프트(“짧은 코멘트도 추가해 줘”)와 함께 json_schema를 보냅니다.
  2. 요청이 오류를 내면 제공업체가 json_schema를 받지 않는 것입니다. json_object를 시도하세요.
  3. 응답에 추가 필드가 있으면 스키마가 강제되지 않는 것입니다. JSON 모드로 취급하세요.
  4. json_object도 오류를 내면 프롬프트만 쓰는 방식에 검증을 더하세요.

BroadNet Inference 문서는 GLM 5.3과 Qwen3.8 27B(나란히 비교)에 구조화된 출력을 표시하지만, 요청 파라미터 이름은 밝히지 않습니다. 실제로 배포할 모델에서 위 테스트를 돌려 보세요.

잘못된 출력은 어떻게 검증하고 수정하나요?

import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")

이 루프가 동작하는 이유는 다음과 같습니다.

  • finish_reason부터 확인합니다. max_tokens에 도달한 응답은 잘린 JSON입니다. 같은 한도로 재시도하면 똑같이 실패합니다. 위의 두 모델은 답하기 전에 추론하며, 추론은 한도에 포함되므로 여유를 두세요.
  • 거부 응답은 따로 처리합니다. OpenAI 가이드에 따르면 거부 응답은 “does not necessarily follow the schema you have supplied”(번역: 제공한 스키마를 반드시 따르지는 않습니다).
  • 정확한 오류를 돌려보냅니다. 무작정 재시도하면 같은 실수가 다시 나오기 쉽습니다. “line_items: field required”라고 알려 주면 모델이 무엇을 고쳐야 할지 압니다.
  • 비즈니스 규칙은 코드로 확인합니다. 스키마로는 합계가 항목의 합과 같아야 한다고 표현할 수 없지만, 위의 검사는 할 수 있습니다.
  • 시도 횟수에 상한을 둡니다. 시도할 때마다 프롬프트 전체가 입력 토큰으로 다시 전송됩니다.

어떤 스키마 기능이 문제를 일으키나요?

스키마는 단순하게 유지하세요.

  1. 중첩보다 평평한 구조. 대부분의 추출에는 두 단계면 충분합니다.
  2. 카테고리에는 자유 문자열 대신 enum.
  3. 열린 객체는 쓰지 않기. 자유 형식 dict 필드는 스키마의 의미를 없앱니다.
  4. 짧은 필드 이름에 설명 붙이기. 스키마 안의 설명이 모델을 안내합니다.
  5. 선택 필드는 nullable로. strict 모드에서는 모든 필드를 required로 나열하고 null을 허용하세요.

OpenAI 가이드에 따르면 strict 모드에서는 일부 JSON Schema 기능이 지원되지 않습니다. 오픈 모델 서버에도 각자의 제한이 있습니다. 스키마가 거부되면 모드를 바꾸기 전에 먼저 스키마를 단순하게 만드세요.

프로덕션에서 구조화된 출력은 어떻게 모니터링하나요?

조용히 고치는 루프는 매일 토큰을 잡아먹는 문제를 숨길 수 있습니다. 호출 지점마다 세 가지 숫자를 기록하세요.

지표 알려 주는 것
첫 시도 성공률 모델과 스키마가 얼마나 잘 맞는지. 프롬프트나 모델을 바꾼 뒤 떨어지는 경우가 많음
성공당 평균 시도 횟수 수정에 드는 토큰 비용
최종 실패 파이프라인이 처리하지 못하는 입력. 직접 검토 필요

첫 시도 성공률이 평소보다 떨어지면 재시도를 늘리기 전에 스키마를 단순화하거나 다른 모델을 시도하세요. 실패한 원본 응답의 샘플을 보관해 두면 실제 사례로 수정 사항을 테스트할 수 있습니다.

대신 도구를 써야 하는 경우는 언제인가요?

최종 답변에는 구조화된 출력을 쓰세요. 추출, 분류, 계획 같은 것입니다. 모델이 코드에 무언가를 시키고 이어서 진행해야 한다면 도구 호출을 쓰세요. 많은 에이전트가 둘 다 씁니다. 루프 중에는 도구를, 마지막 단계에는 스키마를 씁니다. 이미지를 JSON으로 바꾸는 예시는 비전 모델로 아랍어 인보이스 읽기를 참고하세요.

BroadNet Inference는 어디에 적합한가요?

BroadNet Inference는 GLM 5.3과 Qwen3.8 27B에 구조화된 출력을 표시하며 표준 chat completions 형식을 쓰므로, 위 코드는 OpenAI Python SDK로 수정 없이 실행됩니다. Qwen3.8 27B는 이미지도 받으므로 문서 추출에 적합합니다. BroadNet 문서는 DeepSeek V4.1 Flash나 Gemma 4 VL 26B의 구조화된 출력 지원을 밝히지 않으므로, 이 모델들에서는 프롬프트만 쓰는 방식에 검증을 더하세요. 토큰당 가격은 가격 페이지에서 비교하세요.

자주 묻는 질문

JSON 모드와 구조화된 출력은 무엇이 다른가요?

JSON 모드(response_format type json_object)는 응답이 JSON으로 파싱된다는 것만 보장합니다. 구조화된 출력(type json_schema)은 제공업체가 강제하는 경우 정의한 필드와 타입까지 보장합니다. OpenAI는 가능하면 JSON 모드보다 구조화된 출력을 쓰라고 권장합니다.

오픈 모델도 json_schema response_format을 지원하나요?

제공업체에 따라 다릅니다. json_schema를 받는 곳도 있고, json_object만 받는 곳도 있고, 이 필드를 무시하는 곳도 있습니다. 스키마와 함께, 모델이 필드를 하나 더 추가하고 싶어지도록 유도하는 프롬프트로 테스트 요청을 보낸 뒤 응답을 확인하세요.

구조화된 출력도 검증해야 하나요?

네. 응답은 max_tokens에서 잘릴 수 있고, 거부 응답일 수 있으며, 합계가 맞아야 한다는 규칙처럼 스키마로 표현할 수 없는 비즈니스 규칙을 어길 수 있습니다.

잘못된 JSON은 몇 번까지 재시도해야 하나요?

검증 오류를 포함해 2~3회 시도하면 대개 충분합니다. 그래도 실패하면 입력을 기록하고 대체 경로, 더 강한 모델, 또는 사람에게 넘기세요. 상한 없는 루프는 토큰을 낭비합니다.

구조화된 출력과 도구 호출 중 무엇을 써야 하나요?

최종 답변을 고정된 구조로 받고 싶다면 구조화된 출력을 쓰세요. 모델이 코드에 무언가를 시킨 뒤 이어서 진행해야 한다면 도구 호출을 쓰세요.

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