---
title: "JSON モードと JSON Schema の構造化出力（コード付き） | BroadRouter"
description: "JSON モードは正しい JSON を、json_schema は指定した形を保証します。OpenAI 互換モデルでの指定方法、Pydantic での検証、不正な出力をループで修復する方法を解説します。"
url: https://broadrouter.com/ja/blog/structured-output-json-schema/
lang: ja
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 モードと 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”（訳：スキーマへの準拠を保証するのは構造化出力だけ）です。
-   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/ja/glossary/structured-output/)はこの溝を埋めますが、「モデルが JSON を返す」という言葉は、依頼の仕方によって 3 通りの意味になります。この記事では、OpenAI 互換のオープンモデルでの選択肢を比べ、それぞれの指定方法を示し、本番環境にそのまま組み込める検証・修復ループを紹介します。

## JSON モードと json\_schema の違いは？

| 方法 | リクエスト | 保証されること |
| --- | --- | --- |
| プロンプトのみ | 「次のフィールドを持つ JSON で返答してください…」 | 何も保証されない。たいてい JSON だが、余計なテキストが付くこともある |
| JSON モード | `response_format: {"type": "json_object"}` | 正しい JSON（形は問わない） |
| 構造化出力 | `response_format: {"type": "json_schema", ...}` | 強制される場合、スキーマに一致する JSON |

OpenAI の構造化出力ガイドははっきりこう書いています。“While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.”（訳：どちらも正しい JSON の生成を保証しますが、スキーマへの準拠を保証するのは構造化出力だけです。）そして、可能な限り JSON モードより構造化出力を使うよう勧めています。

オープンモデルのプロバイダーでは、保証の有無はサーバーの実装次第です。多くは制約付きデコーディングを使い、スキーマを壊すトークンをブロックします。フィールドを受け付けても強制しないところもあります。だからこそ、以下のコードはどんな場合でも検証します。

## 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/ja/models/glm-5.3/) と [Qwen3.8 27B](https://broadrouter.com/ja/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/ja/glossary/max-tokens/) に達した返答は途中で切れた JSON です。同じ上限でリトライしても同じように失敗します。上の 2 つのモデルはどちらも回答前に推論し、[推論は上限に含まれる](https://broadrouter.com/ja/guides/reasoning-tokens-empty-response/)ので、余裕を持たせてください。
-   \*\*拒否は別に扱います。\*\*OpenAI のガイドによると、拒否は “does not necessarily follow the schema you have supplied”（訳：指定したスキーマに従うとは限りません）。
-   \*\*正確なエラーを送り返します。\*\*やみくもにリトライすると、同じ誤りが返ってくることがよくあります。「line\_items: field required」なら、モデルに直すべき点が伝わります。
-   \*\*業務ルールはコードで確認します。\*\*合計が明細と一致しなければならない、といったことはスキーマでは表現できません。上のチェックならできます。
-   \*\*試行回数に上限を設けます。\*\*試行のたびに、プロンプト全体が[入力トークン](https://broadrouter.com/ja/glossary/input-and-output-tokens/)として再送されます。

## 問題を起こしやすいスキーマの機能は？

スキーマは地味に保ちましょう。

1.  \*\*ネストより平坦に。\*\*ほとんどの抽出は 2 階層で十分です。
2.  **カテゴリーは自由な文字列より enum で。**
3.  \*\*何でも入るオブジェクトは避けます。\*\*自由形式の `dict` フィールドは目的を損ないます。
4.  \*\*短いフィールド名に説明を付けます。\*\*スキーマ内の説明がモデルを導きます。
5.  \*\*省略可能なフィールドは nullable に。\*\*strict モードでは、すべてのフィールドを required にしたうえで `null` を許可します。

OpenAI のガイドでは、JSON Schema の一部の機能は strict モードで非対応とされています。オープンモデルのサーバーにも独自の制限があります。スキーマが拒否されたら、モードを変える前にまずスキーマを単純にしてください。

## 本番環境で構造化出力をどう監視するか？

黙って修復するループは、毎日トークンを浪費する問題を隠してしまうことがあります。呼び出し箇所ごとに 3 つの数字を記録してください。

| 指標 | わかること |
| --- | --- |
| 初回成功率 | モデルとスキーマの相性。プロンプトやモデルの変更後に下がることが多い |
| 成功 1 件あたりの平均試行回数 | 修復にかかるトークンコスト |
| 最終的な失敗数 | パイプラインで処理できない入力。手作業で確認する |

初回成功率がいつもの水準を下回ったら、リトライを増やす前に、スキーマを単純にするか別のモデルを試してください。失敗した生の返答のサンプルを残しておけば、実際のケースで修正をテストできます。

## 代わりにツールを使うべきなのはいつか？

**最終的な回答**、つまり抽出、分類、計画には構造化出力を使います。モデルがあなたのコードに何かを**させて**から続ける必要があるときは、[ツール呼び出し](https://broadrouter.com/ja/blog/tool-calling-open-models/)を使います。多くのエージェントは両方を使います。ループの途中ではツールを、最後のステップではスキーマを使うのです。画像から JSON への例は、[ビジョンモデルでアラビア語の請求書を読み取る](https://broadrouter.com/ja/guides/read-arabic-invoices-with-vision/)を参照してください。

## BroadNet Inference が向いているケース

BroadNet Inference は GLM 5.3 と Qwen3.8 27B に構造化出力を記載しており、標準の chat completions 形式で提供しているので、上のコードは [OpenAI Python SDK](https://broadrouter.com/ja/guides/openai-python-sdk/) でそのまま動きます。Qwen3.8 27B は画像も受け付けるので、書類からの抽出に向いています。BroadNet のドキュメントには DeepSeek V4.1 Flash と Gemma 4 VL 26B の構造化出力についての記載がないため、これらではプロンプトのみの方法に検証を組み合わせてください。トークン単価は[料金ページ](https://broadrouter.com/ja/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 Outputs）](https://broadrouter.com/ja/glossary/structured-output/)

構造化出力とは、モデルの回答を開発者が指定した形式（通常は JSON Schema）に制約し、コードで確実に解析できるようにする LLM API の機能です。有効な JSON であることだけを保証し、特定の形までは保証しない JSON モードより厳格です。

[JSON Schema（JSON スキーマ）](https://broadrouter.com/ja/glossary/json-schema/)

JSON Schema とは、JSON データの構造（型、必須フィールド、許可される値、入れ子）を記述・検証するための、JSON で書かれた語彙です。現行バージョンは 2020-12 です。LLM API はツールのパラメーターや、構造化出力が従うべき正確な形の定義に使います。

[トークン（token）](https://broadrouter.com/ja/glossary/token/)

トークンとは、言語モデルが読み書きするテキストの単位です。モデルのトークナイザーが作る単語、単語の一部、句読点、バイト列のいずれかにあたります。LLM API は利用量をトークンで数え、上限を設け、通常はトークン単位で課金します。

[オープンウェイトモデル（open-weight model）](https://broadrouter.com/ja/glossary/open-weight-model/)

オープンウェイトモデルとは、学習済みの重みが公開され、誰でもダウンロードして実行できるモデルで、通常は条件付きのライセンスで提供されます。学習コードや学習データの詳細も公開し、他者が検証・再現できる完全なオープンソース AI とは別物です。

[AI エージェント（AI agent）](https://broadrouter.com/ja/glossary/agent/)

AI エージェントとは、言語モデルが目標に向けて自分で手順を決めるシステムです。どのツールを呼ぶかを決め、結果を読み、最終回答を出すか上限に達するまで繰り返します。決まった箇所でモデルを呼ぶ固定のスクリプトは、ふつうワークフローと呼ばれます。

[Chat Completions API（チャット補完 API）](https://broadrouter.com/ja/glossary/chat-completions-api/)

Chat Completions API とは、OpenAI の HTTP エンドポイント POST /v1/chat/completions で、モデル名とロール付きメッセージのリストを受け取り、モデルの次のメッセージを返します。そのリクエストと応答の形は、OpenAI 互換のプロバイダーや SDK が使う共通形式になりました。

[OpenAI 互換 API（OpenAI-compatible API）](https://broadrouter.com/ja/glossary/openai-compatible-api/)

OpenAI 互換 API とは、POST /v1/chat/completions など OpenAI API と同じリクエスト形式とレスポンス形式を受け付ける HTTP API です。OpenAI の SDK やツールは、ベース URL、API キー、モデル名を変えるだけで利用できます。

[ツール呼び出し（Function Calling、tool calling）](https://broadrouter.com/ja/glossary/tool-calling/)

ツール呼び出し（Function Calling とも呼ばれます）とは、開発者が定義した関数の実行を求める構造化されたリクエストを、モデルが JSON の引数付きで返す LLM API の機能です。関数を実行して結果を返すのはアプリケーションで、モデル自身がコードを実行することはありません。

## よくある質問

### JSON モードと構造化出力の違いは何ですか？

JSON モード（response\_format の type が json\_object）が保証するのは、返答が JSON としてパースできることだけです。構造化出力（type が json\_schema）は、プロバイダーが強制する場合、定義したフィールドと型も保証します。OpenAI は、可能な限り JSON モードより構造化出力を使うよう勧めています。

### オープンモデルは response\_format の json\_schema に対応していますか？

プロバイダーによります。json\_schema を受け付けるところ、json\_object だけのところ、フィールドを無視するところがあります。スキーマ付きで、余分なフィールドを足したくなるようなプロンプトのテストリクエストを送り、返答を確認してください。

### 構造化出力でも検証は必要ですか？

必要です。返答は max\_tokens で途中で切れることがあり、拒否であることもあり、合計が明細の和と一致しなければならないといった、スキーマでは表現できない業務ルールに反することもあります。

### 不正な JSON は何回までリトライすべきですか？

検証エラーを添えて 2〜3 回試せば、たいてい十分です。それでもだめなら入力を記録し、フォールバック、より強いモデル、または人に回してください。上限のないループはトークンの無駄です。

### 構造化出力とツール呼び出しのどちらを使うべきですか？

最終的な回答を決まった形で受け取りたいなら構造化出力を、モデルがあなたのコードに何かをさせてから続ける必要があるならツール呼び出しを使います。

## 続けて読む

-   [LLM によるアラビア語テキスト分類：感情、意図、振り分け](https://broadrouter.com/ja/blog/arabic-text-classification-llm/)
-   [オープンモデルのツール呼び出し：スキーマ、並列呼び出し、リトライ](https://broadrouter.com/ja/blog/tool-calling-open-models/)
-   [OpenAI 互換 API への移行チェックリスト](https://broadrouter.com/ja/blog/openai-compatible-api-migration-checklist/)
-   [n8n の AI Agent を安い LLM で動かす：設定、モデル選び、1 回あたりのコスト](https://broadrouter.com/ja/blog/n8n-ai-agent-cheap-llm/)
-   [LLM が返す不正な JSON の直し方：原因・修復・リトライ](https://broadrouter.com/ja/blog/fix-invalid-json-from-llm/)
-   [LLM によるアラビア語の固有表現抽出：JSON、日付、チェック](https://broadrouter.com/ja/blog/arabic-named-entity-extraction-llm/)
-   [BroadNet の GPU ハードウェアとサービング方式（BroadNet の説明による）](https://broadrouter.com/ja/blog/broadnet-gpu-fleet-and-serving/)
-   [LLM API のレスポンスをキャッシュしてコスト削減：Python の完全一致キャッシュ](https://broadrouter.com/ja/blog/cache-llm-responses-cut-cost/)
-   [ガイド：OpenAI Python SDK を BroadNet Inference で使う](https://broadrouter.com/ja/guides/openai-python-sdk/)
-   [ガイド：ビジョンモデルでアラビア語の請求書とレシートを読み取る](https://broadrouter.com/ja/guides/read-arabic-invoices-with-vision/)
-   [ガイド：推論モデルが空の回答を返す理由](https://broadrouter.com/ja/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=ja-blog-structured-output-json-schema&utm_content=page-cta) ·

**出典**

-   [OpenAI 構造化出力ガイド（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=ja-blog-structured-output-json-schema&utm_content=sources#models)
