はじめに
APIドキュメントの整備やクラウドアーキテクチャの設計において、開発現場で頻繁に挙がる課題があります。「生成AIを本番導入したのはいいけれど、APIの請求額が予想以上に跳ね上がっている」というものです。
特に、システム連携のためにLLM（大規模言語モデル）からの出力をJSON形式で受け取る「構造化出力（Structured Outputs）」を多用しているプロジェクトで、この傾向が顕著です。開発者にとって、非構造化データである自然言語を、プログラムで扱いやすい構造化データに変換できる機能は非常に強力です。
しかし、その利便性の裏には「便利税」とも言える隠れたコストが存在します。
「とりあえずJSON Modeにしておけば安心」「Function Callingを使えば確実」と考えて実装したスキーマ定義が、実は不要なトークンを大量に消費し、レスポンス速度（レイテンシー）を悪化させているケースは少なくありません。
この記事では、単なる機能の実装方法ではなく、「いかにトークンを削ぎ落とし、コスト効率とパフォーマンスを最大化するか」という視点に絞って解説します。JSON ModeとFunction Callingの内部挙動の違いから、Pydanticを用いた極限まで無駄を省くスキーマ設計術まで、実践的なノウハウを体系的に整理します。
プロジェクトにおける「トークン漏れ」を防ぎ、効率的なAPI連携を実現するためのヒントとして活用してください。
構造化出力の「便利税」：APIコストを圧迫する隠れた要因
まず、開発現場で直面しやすい問題の正体を明確にします。なぜ、構造化出力を使用するとトークン消費が増加するのでしょうか。
多くの開発者は「出力されるJSONの文字数」に注目しがちです。しかし、それはAPIコストの一部に過ぎません。実際には、より大きな「入力トークン」と「見えない試行錯誤」のコストが潜んでいます。
出力トークンだけではない、入力トークンの肥大化問題
LLMが特定のJSONフォーマットで回答するためには、「どのようなフォーマットで回答すべきか」という明確な指示が必要です。
OpenAI APIなどを利用する場合、PydanticモデルやJSON Schemaを渡して構造を定義します。ここで重要なのは、このスキーマ定義自体がテキストに変換され、システムプロンプトの一部としてLLMに入力されているという事実です。
たとえば、以下のような丁寧なスキーマ定義を想定します。
class CustomerProfile(BaseModel):
customer_full_name: str = Field(..., description="The full name of the customer interacting with the support agent.")
customer_shipping_address: str = Field(..., description="The complete physical address where the product should be shipped.")
interaction_sentiment_score: int = Field(..., description="A score from 1 to 10 indicating the sentiment of the customer during the conversation.")
これは非常に読みやすく、保守性の高いコードです。しかし、LLMのトークン計算の視点ではどうでしょうか。
この定義をLLMに理解させるために、フィールド名（customer_shipping_address）や詳細な説明文（description）はすべてトークンとして消費されます。特に長いキー名や冗長な説明文は、APIリクエストのたびに積み重なる「固定費」として課金され続けます。
仮に、1リクエストあたり500トークンをスキーマ定義に使用し、月間100万リクエストが発生すると仮定した場合、それだけで5億トークン分のコストが発生します。これが「便利税」の正体の一つです。
JSON ModeとFunction Callingの内部挙動と課金ポイント
構造化出力を実現する主な手法として、「JSON Mode」と「Function Calling（またはTools）」があります。これらはAPI上では別のパラメータとして扱われますが、トークン消費の観点では共通の課題と、それぞれの特性を持っています。
- JSON Mode: 基本的にはシステムプロンプト内で「JSONで出力せよ」と指示し、さらにスキーマ情報もプロンプトに含める設計です。プロンプトエンジニアリングへの依存度が高く、入力トークン量は開発者の記述量に直結します。
- Function Calling: API側で定義されたツール定義（関数シグネチャ）としてスキーマを渡します。一見、プロンプトとは別枠に見えますが、内部的にはLLMが理解できる形式（多くの場合はTypeScriptの型定義や独自のXML風フォーマットなど）に変換され、コンテキストウィンドウに挿入されています。つまり、Function Callingを使用しても、スキーマ定義分の入力トークンは確実に消費されるのです。
再試行（リトライ）による二重コストのリスク
もう一つの隠れたコストは「エラー処理と再生成」です。
構造化出力を強制しても、LLMは確率的なモデルであるため、稀にJSONの構文エラーや、指定した型（数値型なのに文字列が入るなど）に合わないデータを出力することがあります。
LangChainなどの主要ライブラリは、こうしたパースエラーが発生した際に自動的に修正を試みる機能を備えています。しかし、最新のライブラリではセキュリティ脆弱性への対策としてスキーマ処理の防御機構が強化されており、型定義に対する検証がより厳格になっています。
さらに、使用するAPIモデルの移行もリトライ頻度に直結する要素です。OpenAIの環境では2026年2月に大きなモデルアップデートがあり、GPT-4oなどのレガシーモデルから、高度な推論能力（ThinkingのExtendedレベル対応など）を持つGPT-5.2が新たな標準モデルとして統合されました。また、コーディングや開発タスクにはエージェント型のGPT-5.3-Codexが提供されています。
API環境ではGPT-4o等のレガシーモデルも継続して利用可能ですが、より高性能なGPT-5.2等へ移行する場合、構造化出力の精度や挙動が変化する可能性があります。以前のモデル（GPT-4o等）で最適化されていたプロンプトが、新モデルの厳格な推論プロセス下では意図しないエラーを引き起こし、ライブラリが自動的に「修正用のプロンプト」を生成してLLMに再リクエストを送る頻度が増加するケースが考えられます。
1回のリクエストで済むはずが、エラー発生時には以下のプロセスが裏で実行されます：
- 失敗した出力（課金対象）
- エラーメッセージと修正指示（課金対象）
- 再生成された出力（課金対象）
エラー率がわずか数パーセントであっても、リトライ時にはコンテキストが長くなるため、全体のトークン消費量は跳ね上がります。特に、GPT-5.2やGPT-5.3-Codexなどの新モデルへ移行する際は、必ずプロンプトを再テストし、自動リトライの設定やスキーマ定義の適合性を確認することが重要です。意図しない「再生成ループ」によるコスト増を防ぐ設計が不可欠です。
このように、構造化出力のコスト最適化は、単なる「節約」ではなく、モデルのアップデートやセキュリティ要件も含めたシステム全体のアーキテクチャに関わる重要な設計課題と言えます。
モード選択の分岐点：JSON Mode vs Function Calling
「結局、JSON ModeとFunction Calling、どちらを使用すべきか」
これは開発現場で頻繁に議論されるテーマの一つです。実装の容易さで選ばれがちですが、ここでは「トークン効率」と「レイテンシー」というエンジニアリングの観点から、明確な判断基準を提示します。
トークン効率の観点から見た両者の決定的な違い
結論から言うと、複雑なネストや厳密な型制約が求められる場合はFunction Calling（またはStructured Outputs）、フラットで単純な構造ならJSON Modeが有利な傾向にあります。特にOpenAI APIなどで導入された「Structured Outputs（厳格なJSONモード）」の登場により、データ抽出における信頼性は飛躍的に向上しています。
Function Calling / Structured Outputs の特徴
モデルが「外部ツールを呼び出すための引数」や「厳格なスキーマに基づいたデータ」を生成することに特化して調整されています。
- メリット: 構造化の精度が極めて高い。事前に定義したJSON Schemaに完全に準拠した出力が保証されます（Structured Outputsの場合）。
- デメリット: 独自の構文やスキーマ定義を含むため、単純なテキスト生成よりも処理コストがかかる場合があります。また、詳細なスキーマ定義自体が入力トークンを消費します。
JSON Mode の特徴
プロンプトで「JSONで返して」と指示する従来のアプローチを、APIレベルで強制するものです。
- メリット: プロンプト内でスキーマを簡潔に記述できれば、入力トークンを制御しやすくなります。非定型のデータ構造に対して柔軟性が高いです。
- デメリット: あくまで「JSON形式の文字列」を生成するだけなので、キー名のスペルミスや型の不一致が起こる可能性があります。
ベンチマーク比較：同じデータを抽出する際の消費量
具体的なシナリオで考えてみましょう。あるニュース記事から「主要な登場人物」と「要約」を抽出するタスクを想定します。
Function Calling / Structured Outputsの場合:
ツール定義として詳細なJSON Schemaを渡します。モデルはこれを厳密に解釈しようとするため、入力トークンはスキーマの複雑さに比例して増加します。しかし、出力は非常に安定しており、パースエラーによるリトライ（再生成）のコストはほぼゼロに抑えられます。JSON Modeの場合:
プロンプトに「出力例（Few-Shot）」を含めることで、スキーマ定義を省略または簡略化できる場合があります。現在でもFew-Shotは最も推奨される強力な手法であり、厳密な型定義を渡さなくても、2〜3個の具体例を提示するだけで、AIは期待するフォーマットや暗黙のルールを正確に理解します。最近のモデルは文脈理解が大幅に向上しており、かつて多用された「あなたはプロの編集者です」といったロールプロンプトよりも、良質な具体例の提示がはるかに効果的です。さらに、Chain-of-Thought（「ステップバイステップで考えてください」）と組み合わせることで推論精度が飛躍的に高まるという報告もあります。これにより入力トークンを最適化できる可能性がありますが、出力の絶対的な確実性はFunction Callingに一歩譲ります。
「確実性」と「効率性」のトレードオフをどう判断するか
一般的に推奨される選択基準（マトリクス）は以下の通りです。
| 判定基準 | 推奨モード | 理由 |
|---|---|---|
| データ構造の複雑さ | 深いネスト / リスト | Function Calling / Structured Outputs |
| データ構造の複雑さ | フラット / 単純 | JSON Mode |
| スキーマの厳密さ | Enum / 特定フォーマット必須 | Function Calling / Structured Outputs |
| レイテンシー要件 | 最速を求める | JSON Mode (Stream) |
| 開発フェーズ | プロトタイプ | Function Calling |
| 開発フェーズ | 本番運用（コスト最適化） | ケースバイケース |
特にOpenAI APIの「Structured Outputs」（response_format: { type: "json_schema", ... }）は、従来のFunction Callingよりもデータ抽出に特化しており、スキーマ遵守率100%を目指して設計されています。信頼性が最優先される本番環境では、この機能が第一の選択肢となるでしょう。
コメント