BroadRouter
始める

JSON モードと json_schema:壊れない構造化出力の作り方

BroadNet Inference チーム · 約 4 分で読めます · 公開日

JSON モード(response_format の json_object)が保証するのは正しい JSON であることだけです。構造化出力(response_format の json_schema)は、プロバイダーが強制する場合、フィールドと型も保証します。どちらでも finish_reason を確認し、パースして、Pydantic モデルなどのスキーマで検証します。失敗したらエラーを返して再度依頼し、試行回数には厳密な上限を設けます。

コードが必要とするのはデータですが、モデルが書くのはテキストです。構造化出力はこの溝を埋めますが、「モデルが 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 はどう指定するか?

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 です。同じ上限でリトライしても同じように失敗します。上の 2 つのモデルはどちらも回答前に推論し、推論は上限に含まれるので、余裕を持たせてください。
  • **拒否は別に扱います。**OpenAI のガイドによると、拒否は “does not necessarily follow the schema you have supplied”(訳:指定したスキーマに従うとは限りません)。
  • **正確なエラーを送り返します。**やみくもにリトライすると、同じ誤りが返ってくることがよくあります。「line_items: field required」なら、モデルに直すべき点が伝わります。
  • **業務ルールはコードで確認します。**合計が明細と一致しなければならない、といったことはスキーマでは表現できません。上のチェックならできます。
  • **試行回数に上限を設けます。**試行のたびに、プロンプト全体が入力トークンとして再送されます。

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

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

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

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

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

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

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

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

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

最終的な回答、つまり抽出、分類、計画には構造化出力を使います。モデルがあなたのコードに何かをさせてから続ける必要があるときは、ツール呼び出しを使います。多くのエージェントは両方を使います。ループの途中ではツールを、最後のステップではスキーマを使うのです。画像から 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 モードより構造化出力を使うよう勧めています。

オープンモデルは response_format の json_schema に対応していますか?

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

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

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

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

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

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

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

Markdown で読むChatGPT に聞くClaude に聞くPerplexity に聞く