コードが必要とするのはデータですが、モデルが書くのはテキストです。構造化出力はこの溝を埋めますが、「モデルが 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 に列挙することを求めています。
プロバイダーはどのモードに対応しているか?
そのモデルを前提に開発を始める前に、モデルごとに一度このテストを実行してください。
- 余分なフィールドを促すプロンプト(「短いコメントも追加して」)とともに
json_schemaを送ります。 - リクエストがエラーになるなら、プロバイダーは
json_schemaを受け付けていません。json_objectを試してください。 - 返答に余分なフィールドが含まれているなら、スキーマは強制されていません。JSON モードとして扱ってください。
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」なら、モデルに直すべき点が伝わります。
- **業務ルールはコードで確認します。**合計が明細と一致しなければならない、といったことはスキーマでは表現できません。上のチェックならできます。
- **試行回数に上限を設けます。**試行のたびに、プロンプト全体が入力トークンとして再送されます。
問題を起こしやすいスキーマの機能は?
スキーマは地味に保ちましょう。
- **ネストより平坦に。**ほとんどの抽出は 2 階層で十分です。
- カテゴリーは自由な文字列より enum で。
- **何でも入るオブジェクトは避けます。**自由形式の
dictフィールドは目的を損ないます。 - **短いフィールド名に説明を付けます。**スキーマ内の説明がモデルを導きます。
- **省略可能なフィールドは 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 の構造化出力についての記載がないため、これらではプロンプトのみの方法に検証を組み合わせてください。トークン単価は料金ページで比較できます。
