---
title: "JSON 모드와 JSON 스키마 구조화된 출력 차이(코드 포함) | BroadRouter"
description: "JSON 모드는 유효한 JSON을, json_schema는 원하는 구조를 보장합니다. OpenAI 호환 모델에서 각각 요청하는 법, Pydantic 검증, 잘못된 출력을 루프로 고치는 법을 정리했습니다."
url: https://broadrouter.com/ko/blog/structured-output-json-schema/
lang: ko
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/blog/structured-output-json-schema/) (2026-11-14 업데이트).

# JSON 모드 vs json\_schema: 믿고 쓸 수 있는 구조화된 출력

BroadNet Inference 팀 · 4분 분량 · 게시 2026-11-14

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

## 핵심 요약

-   OpenAI 가이드에 따르면 두 모드 모두 유효한 JSON을 만들지만 "only Structured Outputs ensure schema adherence"(번역: 스키마 준수를 보장하는 것은 Structured Outputs뿐입니다).
-   OpenAI 호환 제공업체마다 지원 범위가 다릅니다. json\_schema를 먼저 테스트하고, 안 되면 json\_object, 그다음 프롬프트만 쓰는 방식으로 내려가세요.
-   모든 응답을 검증하세요. max\_tokens에서 잘린 응답은 스키마와 상관없이 깨진 JSON입니다.
-   수정 루프는 정확한 검증 오류를 돌려보낼 때 효과가 있습니다. 시도는 2~3회로 제한하세요.
-   BroadNet Inference에서는 GLM 5.3과 Qwen3.8 27B가 구조화된 출력을 지원 기능으로 표시합니다.

**이 페이지의 내용**

1.  JSON 모드와 json\_schema는 무엇이 다른가요?
2.  json\_schema는 어떻게 요청하나요?
3.  내 제공업체는 어떤 모드를 지원하나요?
4.  잘못된 출력은 어떻게 검증하고 수정하나요?
5.  어떤 스키마 기능이 문제를 일으키나요?
6.  프로덕션에서 구조화된 출력은 어떻게 모니터링하나요?
7.  대신 도구를 써야 하는 경우는 언제인가요?
8.  BroadNet Inference는 어디에 적합한가요?

코드에는 데이터가 필요하지만 모델은 텍스트를 씁니다. [구조화된 출력](https://broadrouter.com/ko/glossary/structured-output/)이 이 간극을 메우지만, “모델이 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는 어떻게 요청하나요?

```python
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 스키마 생성기](https://broadrouter.com/tools/json-schema-generator/)가 예시 객체로 strict 모드 스키마를 만들어 줍니다. strict 모드에서 OpenAI는 `additionalProperties: false`와 모든 속성을 required로 나열할 것을 요구합니다.

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

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

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

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

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

```python
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`](https://broadrouter.com/ko/glossary/max-tokens/)에 도달한 응답은 잘린 JSON입니다. 같은 한도로 재시도하면 똑같이 실패합니다. 위의 두 모델은 답하기 전에 추론하며, [추론은 한도에 포함되므로](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/) 여유를 두세요.
-   **거부 응답은 따로 처리합니다.** OpenAI 가이드에 따르면 거부 응답은 “does not necessarily follow the schema you have supplied”(번역: 제공한 스키마를 반드시 따르지는 않습니다).
-   **정확한 오류를 돌려보냅니다.** 무작정 재시도하면 같은 실수가 다시 나오기 쉽습니다. “line\_items: field required”라고 알려 주면 모델이 무엇을 고쳐야 할지 압니다.
-   **비즈니스 규칙은 코드로 확인합니다.** 스키마로는 합계가 항목의 합과 같아야 한다고 표현할 수 없지만, 위의 검사는 할 수 있습니다.
-   **시도 횟수에 상한을 둡니다.** 시도할 때마다 프롬프트 전체가 [입력 토큰](https://broadrouter.com/ko/glossary/input-and-output-tokens/)으로 다시 전송됩니다.

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

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

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

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

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

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

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

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

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

**최종 답변**에는 구조화된 출력을 쓰세요. 추출, 분류, 계획 같은 것입니다. 모델이 코드에 무언가를 **시키고** 이어서 진행해야 한다면 [도구 호출](https://broadrouter.com/ko/blog/tool-calling-open-models/)을 쓰세요. 많은 에이전트가 둘 다 씁니다. 루프 중에는 도구를, 마지막 단계에는 스키마를 씁니다. 이미지를 JSON으로 바꾸는 예시는 [비전 모델로 아랍어 인보이스 읽기](https://broadrouter.com/ko/guides/read-arabic-invoices-with-vision/)를 참고하세요.

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

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

관련 무료 도구 (영어)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[무료 도구 (영어)](https://broadrouter.com/tools/)

## 이 글의 용어

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[JSON Schema(JSON 스키마)](https://broadrouter.com/ko/glossary/json-schema/)

JSON Schema는 JSON으로 작성하는 어휘로, 타입, 필수 필드, 허용 값, 중첩 같은 JSON 데이터의 구조를 기술하고 검증합니다. 현재 버전은 2020-12입니다. LLM API는 이를 사용해 도구 파라미터와 구조화된 출력이 따라야 할 정확한 형태를 정의합니다.

[오픈 웨이트 모델(open-weight model)](https://broadrouter.com/ko/glossary/open-weight-model/)

오픈 웨이트 모델은 학습된 가중치를 공개해 누구나 내려받아 실행할 수 있게 한 머신러닝 모델로, 보통 조건이 붙은 라이선스로 배포됩니다. 학습 코드와 학습 데이터에 대한 상세한 정보까지 공개해 다른 사람이 모델을 연구하고 재현할 수 있게 하는 완전한 오픈 소스 AI와는 다릅니다.

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[입력 토큰과 출력 토큰(input and output tokens)](https://broadrouter.com/ko/glossary/input-and-output-tokens/)

입력 토큰은 언어 모델이 요청에서 읽는 토큰으로, 시스템 프롬프트, 대화 기록, 도구 정의, 이미지가 포함됩니다. 출력 토큰은 모델이 응답으로 생성하는 토큰으로, 추론도 포함됩니다. LLM API는 보통 둘에 따로 가격을 매기며, 대개 출력이 더 비쌉니다.

[Chat Completions API](https://broadrouter.com/ko/glossary/chat-completions-api/)

Chat Completions API는 OpenAI의 HTTP 엔드포인트인 POST /v1/chat/completions로, 모델 이름과 역할이 붙은 메시지 목록을 받아 모델의 다음 메시지를 반환합니다. 이 요청과 응답 구조는 OpenAI 호환 제공업체와 SDK가 재사용하는 공통 형식이 되었습니다.

[JSON 모드(JSON mode)](https://broadrouter.com/ko/glossary/json-mode/)

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

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

## 자주 묻는 질문

### 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회 시도하면 대개 충분합니다. 그래도 실패하면 입력을 기록하고 대체 경로, 더 강한 모델, 또는 사람에게 넘기세요. 상한 없는 루프는 토큰을 낭비합니다.

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

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

## 이어서 읽기

-   [LLM으로 아랍어 텍스트 분류하기: 감성 분석, 의도, 티켓 분류](https://broadrouter.com/ko/blog/arabic-text-classification-llm/)
-   [오픈 모델 도구 호출: 스키마, 병렬 호출, 재시도](https://broadrouter.com/ko/blog/tool-calling-open-models/)
-   [OpenAI 호환 API로 전환하기: 마이그레이션 체크리스트](https://broadrouter.com/ko/blog/openai-compatible-api-migration-checklist/)
-   [저렴한 LLM으로 n8n AI Agent 쓰기: 설정, 모델 선택, 실행당 비용](https://broadrouter.com/ko/blog/n8n-ai-agent-cheap-llm/)
-   [LLM이 잘못된 JSON을 반환할 때 해결법: 원인, 복구, 재시도](https://broadrouter.com/ko/blog/fix-invalid-json-from-llm/)
-   [LLM으로 아랍어 개체명 추출하기: JSON, 날짜, 검증](https://broadrouter.com/ko/blog/arabic-named-entity-extraction-llm/)
-   [BroadNet의 GPU 하드웨어와 서빙 방식: BroadNet이 밝힌 내용](https://broadrouter.com/ko/blog/broadnet-gpu-fleet-and-serving/)
-   [LLM API 응답 캐싱으로 비용 줄이기: Python 정확 일치 캐시](https://broadrouter.com/ko/blog/cache-llm-responses-cut-cost/)
-   [가이드: BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [가이드: 비전 모델로 아랍어 인보이스와 영수증 읽기](https://broadrouter.com/ko/guides/read-arabic-invoices-with-vision/)
-   [가이드: 추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-structured-output-json-schema&utm_content=page-cta) ·

**출처**

-   [OpenAI Structured Outputs 가이드(2026-11-14 확인)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [OpenAI API 레퍼런스, chat completion 생성(response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Pydantic 문서, JSON Schema와 검증](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [BroadNet Inference API 레퍼런스, 모델 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-structured-output-json-schema&utm_content=sources#models)
