各ツールが解決する問題
📍 In One Sentence
構造化出力のツールは、生成時にスキーマを強制する、生成後に結果を検証する、壊れた出力を修復するという三つの異なる問題を解決しますが、多くの構成で必要になるのは最初の二つだけです。
💬 In Plain Terms
機能一覧で選ばないでください。実際に起きている不具合はどれかを問うべきです。形式を無視されるのか、形式は守られるが値が誤っているのか、そもそもパースできない JSON が返るのか。それぞれ対処法は異なります。
Structured Outputには3つの相互依存する問題の解決が必要です:スキーマ定義、API強制、バリデーション。 各ツールは異なるアプローチで解決します。InstructorはPythonでリトライを用いて3つすべてを処理。OutlinesはConstrained Decodingでバリデーションステップを排除。Pydantic AIはエージェントに型安全性を追加。BAMLはスキーマをコンパイル可能なファイルに移し、不完全な出力を修復。LangChainはProvider APIをラップ。Marvinは開発速度を優先。PromptQuorumは全モデルの一貫性を検証します。
問題 | Instructor | Outlines | Pydantic AI | BAML | LangChain | Marvin |
|---|---|---|---|---|---|---|
| スキーマ定義 | Pydanticモデル | JSON Schema / GBNF | Pydanticモデル | .bamlクラスファイル | ツール定義 | Pythonの型ヒント |
| API呼び出し時の強制 | リトライ + バリデーション | トークンレベル制約 | ネイティブ / ツール / プロンプト | 生成プロンプト + パーサー | Provider JSONモード | Pydantic AIの出力型 |
| レスポンス検証 | 自動 | 生成時に保証 | 型検証済み | Schema-aligned parsing | 手動 | 自動 |
Instructor:Pydantic抽出
InstructorはStructured Outputライブラリとして最も広く採用されています。あらゆるLLM API — OpenAI GPT-5.6、Claude Opus 5、Gemini 3.1 Pro、Ollama、vLLM — をラップし、生テキストではなく検証済みPydanticモデルを返します。 バリデーション失敗時のリトライを自動処理し、追加のエラー処理なしで本番対応です。
- 主要Providerすべてに対応(OpenAI、Anthropic、Google、Groq、Mistral)、OllamaやvLLM経由のローカルモデルにも対応
- Pydantic v2スキーマ:型ヒント、バリデーションルール、スキーマに埋め込まれたdocstring説明
- バリデーション失敗時のバックオフ付き自動リトライ — 手動エラー処理不要
- 6つの公式実装:Python、TypeScript、Ruby、Go、Elixir、Rust
- MITライセンスのオープンソース、活発にメンテナンス中、現在は1.x系
- 料金:無料(LLM APIコスト以外の追加コストなし)
import instructor
from pydantic import BaseModel
from openai import OpenAI
class User(BaseModel):
name: str
age: int
client = instructor.from_openai(OpenAI())
user = client.chat.completions.create(
model="gpt-5.6",
response_model=User,
messages=[{"role": "user", "content": "Extract: John is 25 years old"}]
)
# user.name == "John", user.age == 25Outlines:Constrained Decoding
OutlinesはConstrained Decodingによりトークン生成時にスキーマ準拠を強制します。トークンを生成してから検証するのではなく、各ステップでスキーマに一致する有効なトークンのみに制限します。 出力がスキーマに対して必ずパースできることが保証され、構造面の幻覚リスクはゼロです。これがローカルモデルでの定番選択となっている理由です。
- ローカルバックエンド:transformers、llama.cpp、MLX、あらゆるHugging Faceモデル
- サーバーバックエンド:vLLM、Ollama、NVIDIA NIM
- ホスト型API(OpenAI、Gemini)にも対応 — 同じコードでローカルとクラウドを行き来できる
- スキーマはPydanticモデル、JSON Schema、正規表現パターン、リテラル選択、文脈自由文法で指定
- 構造面の準拠を保証 — 後処理バリデーションやリトライ不要
- Apache 2.0オープンソース、現在は1.x系、高速化のためのRustコア(outlines-core)を採用
Pydantic AI:型安全エージェント
Pydantic AIはPydantic本体を開発するチームによるエージェントフレームワークです。Pydanticモデルとマルチターンエージェント会話の一級サポートを組み合わせ、各ターンでStructured Outputを強制しながらエージェントループに完全な型安全性を追加します。 すでに2.x系に到達し、実験ではなく本番で使われています。
- Pydantic v2型システム — 完全なIDEサポートと、エージェントの戻り値に対する静的型チェック
- 3つの出力モード:Providerネイティブの構造化出力、ツール呼び出し、フォールバックとしてのプロンプトJSON
- 高スループットアプリケーション向けAsync-firstデザイン
- OpenAI、Anthropic、Google、Bedrock、Azure AI Foundry、Groq、Mistral、xAI、Ollamaをサポート
- 永続実行の連携(Temporal、DBOS、Prefect)により長時間稼働のエージェントが再起動を乗り越えられる
- ツール呼び出し内蔵 — 型ヒント付きPython関数としてツールを定義
- MITライセンスで無料(LLM APIコスト以外の追加コストなし)
BAML:スキーマファーストのプロンプトファイル
BAMLはPythonライブラリ群とは逆のアプローチを取ります。スキーマとプロンプトはバージョン管理された.bamlファイルに置かれ、コンパイラが各言語向けの型付きクライアントを生成します。 スキーマ整合パーサーは、モデルが実際に犯す誤り — JSONを囲むマークダウンのコードフェンス、末尾のカンマ、引用符なしのキー、オブジェクトの前に置かれた推論テキスト — をエラーにせず修復するため、リトライを浪費しません。
- スキーマとプロンプトを.bamlファイルにまとめ、他のソースコードと同じようにバージョン管理・レビューできる
- PythonとTypeScript向けにネイティブな型付きクライアントを生成、加えてGo・Java・Ruby・PHP・Rust・C#は生成されたOpenAPIクライアント経由で利用可能
- schema-aligned parsing(SAP)が不完全な出力から有効なオブジェクトを復元し、失敗させない
- ネイティブのtool-useやJSONモードを一切持たないモデルでも動作
- 型安全なストリーミング — 部分オブジェクトが型付きで届き、生成中にフィールドを描画できる
- Apache 2.0オープンソース。ホスト型の可観測性製品Boundary Studioは別途有料
LangChain:統一API
LangChainはすべての主要チャットモデルにwith_structured_output()を提供し、OpenAI、Anthropic、Google、ローカルモデルにわたるStructured Outputを単一のメソッドで統一します。 1.x系での書き直し以降、各Providerのネイティブ構造化出力対応をハードコードせずモデルプロファイルから読み取るようになり、create_agentで作ったエージェントはresponse_formatを直接受け取れます。
- 統一API:.with_structured_output()メソッド1つが全Providerで機能
- LangChainツール定義をProvider固有のスキーマ形式に自動変換
- create_agentで作成したエージェントは最終回答用にresponse_formatを受け取る
- 1.1系以降、ネイティブ構造化出力の対応可否はProviderのプロファイルデータからモデルごとに読み取られる
- Pydanticモデル、TypedDict、dataclass、生のJSON Schemaをサポート
- LangChainまたはLangGraphに既に投資しているチームに最適
Marvin:タスクベース抽出
Marvin 3.xは非構造化テキストから型付きPythonオブジェクトへの最短ルートです。Pydantic AIの上に構築されているため、同じProviderカバレッジとバリデーションをはるかに少ないコードで得られます。 注意点として、Marvin 2のデコレータ中心APIは廃止されました。@marvin.fnは3.0で削除され、トップレベルのヘルパー関数とタスク中心のエージェントエンジンに置き換えられています。
- 1行のヘルパー:marvin.extract、marvin.cast、marvin.classify、marvin.generate
- Pydantic AIの上に構築 — Providerサポートと出力バリデーションは再実装ではなく継承
- 多段階の処理向けタスク中心エンジン:marvin.run、marvin.Task、marvin.Agent、marvin.Thread
- Pythonの型ヒントがスキーマになる — 抽出と分類に必要なボイラープレートは最小限
- 移行時の注意:Marvin 2の@marvin.fnデコレータは存在しないため、該当箇所は書き直しが必要
- Apache 2.0オープンソース、Prefectがメンテナンス、無料で利用可能
PromptQuorum:クロスモデルテスト
PromptQuorum自体はStructured Outputライブラリではなく、モデル間のStructured Output一貫性を検証するためのテストプラットフォームです。 GPT-5.6、Claude Opus 5、Gemini 3.1 Pro、20以上の他のモデルに対して同じプロンプトを同時に実行します。モデルごとのスキーマ準拠率、レイテンシ、コストを測定します。
- 単一API呼び出しでマルチモデルディスパッチ — 25以上のモデルに対してプロンプトをテスト
- Structured Output準拠メトリクス — 合格率、レイテンシ、モデルごとのコスト
- スキーマで幻覚するモデルを特定 — 信頼性の低いモデルへのデプロイを回避
- コンセンサスモード — 独立したモデル実行間の一致を発見
- Instructor、Outlines、Pydantic AI、BAML、LangChain、または生LLM APIと連携
- 無料ティア利用可能、高ボリュームテスト向けエンタープライズ料金
並列比較
ツール | 最適用途 | スキーマ形式 | 言語 | ローカルモデル | ライセンス | 学習コスト |
|---|---|---|---|---|---|---|
| Instructor | Python API + リトライ | Pydanticモデル | Python, TS, Ruby, Go, Elixir, Rust | あり(Ollama、vLLM) | MIT、無料 | 低 |
| Outlines | ローカルモデルデプロイ | Pydantic, JSON Schema, 正規表現, CFG | Python | あり(ネイティブ) | Apache 2.0、無料 | 中 |
| Pydantic AI | 型安全エージェント | Pydanticモデル | Python | あり(Ollama) | MIT、無料 | 低 |
| BAML | 多言語チーム、出力が不安定なモデル | .bamlクラスファイル | Python, TS + OpenAPI経由で6言語 | あり(OpenAI互換) | Apache 2.0、可観測性は有料 | 中 |
| LangChain | チェーン + エージェント | ツール定義 | Python, JS | あり | MIT、無料 | 中 |
| Marvin | 高速なextractとclassify | 型ヒント | Python | あり | Apache 2.0、無料 | 非常に低 |
| PromptQuorum | マルチモデルテスト | API非依存 | APIファースト | OpenAIプロキシ経由 | 無料ティア + エンタープライズ | 低 |
適切なツールの選び方
3つの質問から始めてください:(1) 実際にモデルを呼び出すサービスはどの言語で書かれていますか? (2) ローカルモデルサポートが必要ですか? (3) バリデーションの複雑さはどのくらいですか?
- Instructorを使用する場合: PythonのAPIを構築し、バリデーション失敗時の自動リトライが必要な場合。最良の汎用選択肢。
- Outlinesを使用する場合: ローカルモデル(llama.cpp、vLLM、MLX)をデプロイし、生成時にスキーマ準拠を保証したい場合。
- Pydantic AIを使用する場合: すべてのステップにわたる型安全性でマルチターンエージェントワークフローを構築する場合、または永続実行が必要な場合。
- BAMLを使用する場合: Python・TypeScript・Goのサービスが1つのスキーマを共有する必要がある場合、またはモデルに信頼できるネイティブJSONモードがない場合。
- LangChainを使用する場合: すでにLangChainやLangGraphを使用している場合 — with_structured_output()が最も簡単な追加。
- Marvinを使用する場合: extractやclassifyを1回呼ぶだけで済み、独自のバリデーションロジックが不要な場合。
- PromptQuorumを使用する場合: 本番前にGPT、Claude、Geminiにわたるstructured output一貫性をテストする必要がある場合。
Structured Outputを段階的に導入する方法
- 1出力スキーマを定義する — LLMに返してほしいフィールド、型、制約を記述したPydanticモデル(Python)、.bamlクラス(BAML)、TypeScriptインターフェース、またはJSON Schemaを作成します。
- 2ライブラリを選択する — Python APIにはInstructor、ローカルモデルにはOutlines、エージェントにはPydantic AI、多言語チームにはBAML、すでに使用中ならLangChain、1行で抽出したいならMarvin。
- 3インストールしてLLM呼び出しをラップする — `pip install instructor`(Python)、次にスキーマをAPI呼び出しに渡します。Instructorがバリデーションとリトライを処理します。
- 4PromptQuorumでテストする — PromptQuorumにデプロイし、GPT、Claude、Geminiに対してプロンプトを実行します。モデルごとのスキーマ準拠率を測定します。
- 5失敗に基づいてスキーマを改善する — モデルがバリデーションに失敗した場合、プロンプトに例を追加するかスキーマ制約を調整します。すべてのモデルが合格するまで反復します。
Structured Outputでよくある間違い
❌ どのJSONモードもスキーマの保証だと思い込む
Why it hurts: 単純なJSONモード(response_format json_object、Anthropic JSON制御)は応答が有効なJSONであることしか保証せず、あなたのフィールドや型に一致することは保証しません。厳格なスキーマモードはさらに踏み込んで形を保証しますが、いずれも値の正しさは保証しません。整った形のオブジェクトでも、でっち上げの価格や幻覚した日付を含みうるのです。
Fix: いずれの場合もバリデーションを重ねてください:Instructor、Outlines、Pydantic AI、またはBAML。業務ルールはスキーマだけでなくPydanticのバリデータに書きます。PromptQuorumでモデルごとの準拠失敗を検出してください。
❌ 厳格すぎるスキーマを設計する
Why it hurts: 過度に制約されたスキーマ(小さなenum リスト、非常に具体的な正規表現パターン)はLLMがバリデーションに頻繁に失敗する原因となります。高いリトライ回数はトークンとお金を無駄にします。
Fix: PromptQuorumを使用してモデル間のスキーマ厳格さをテストします。95%以上の準拠率を達成するために制約を緩和します。可能な場合は必須フィールドの代わりにオプションフィールドを使用します。
❌ ローカルとAPIモデルの違いをテストしない
Why it hurts: llama.cpp上のOutlinesはGPT-5.6上のInstructorとは異なる動作をします。スキーマ準拠率はモデルによって異なります。フロンティアのAPIモデルだけで構築してから小さなローカルモデルにデプロイすると、本番障害が発生します。
Fix: すべての予定モデルバックエンドを早期にテストします。PromptQuorumを使用して、ローカル(vLLM、Ollama)とホスト型(OpenAI、Anthropic、Google)のモデルで同じプロンプトを実行します。
❌ レイテンシとトークンコストの影響を無視する
Why it hurts: リトライ付きのStructured Outputはより多くのトークンを消費します。Instructorは失敗時にリトライします。OutlinesのConstrained Decodingは自由生成に比べトークンあたりのオーバーヘッドが増えます。モデルごとのコストが測定されていません。
Fix: PromptQuorumのコスト追跡を使用します。モデル間のレイテンシを比較します。予算重視のワークフローにはOutlinesまたはBAML(リトライループなし)を優先します。柔軟なスキーマで精度を優先するならInstructorのリトライコストを受け入れます。
❌ バリデーション方法を混在させる(一貫性なし)
Why it hurts: 一部のリクエストはInstructorを使用し、他は生のJSON解析を使用します。一部のモデルはバリデーション済み、他はそうでありません。これにより本番で一貫性のないエラーが発生します。
Fix: コードベースごとに1つのバリデーションアプローチを標準化します。すべてのリクエストがInstructorを使用するか、すべてOutlinesを使用します。一貫性によりデバッグ時間が10倍削減されます。
❌ 置き換えられた古いAPI向けのチュートリアルをコピーする
Why it hurts: Structured Outputライブラリの変化は速いです。Marvinは3.0で@marvin.fnデコレータを削除し、LangChainは1.x系の書き直しでドキュメントを再編成し、Outlinesは1.0でimportの構成を変えました。古いチュートリアルからコピーしたコードはインストール段階で失敗します。
Fix: 開発対象のメジャーバージョンを固定し、APIの仕様は最新のドキュメントで確認してください。ブログ記事よりも公式リポジトリのREADMEを優先し、メジャーバージョンを上げるたびに再確認します。
日本企業向けのStructured Output導入ガイド
日本のエンタープライズ環境でLLM Structured Outputを導入する際は、METIのAIガバナンスガイドラインと個人情報保護法(APPI)への準拠が重要です。
- METI AIガバナンスガイドライン2024: 経済産業省は、企業がAIシステムを導入する際にリスク管理体制を整備することを推奨しています。Structured OutputによりLLMの出力を予測可能な形式に制限することで、AIガバナンスの要件を満たしやすくなります。
- 個人情報保護法(APPI): 個人情報を含むデータをLLM APIに送信する場合、第三者提供規制への対応が必要です。Outlinesとローカルモデルによりデータをオンプレミスまたはプライベートクラウドに保持できます。
- 金融・医療・法務セクター: これらの規制が厳しい業界では、機密データ処理にローカルモデルとOutlinesの組み合わせが推奨されます。PromptQuorumで複数モデルの一貫性を検証後、本番環境に移行できます。
- BAMLとオンプレミス運用: BAMLはOpenAI互換エンドポイントであれば動作するため、同じ.baml契約を社内のvLLMデプロイに向けられます。PythonとTypeScriptのサービスがスキーマを共有しつつ、データを社外に出したくない場合に有効です。
- アジア太平洋地域展開: 日本のほか、シンガポール、韓国、オーストラリアへのデプロイでは各国のデータ保護法を確認してください。ローカルモデルによるデータ在地化は多くの規制要件を満たします。
LLMのStructured Outputとは何ですか?
Structured OutputはLLMの応答を特定のスキーマ(JSON形式、定義されたフィールド、型制約)に制限します。自由形式のテキストの代わりに、コードが直接解析・検証できるデータを返します。
Python開発者に最適なツールは何ですか?
Instructorが最も人気のあるPython選択肢です。Pydanticモデルでスキーマを定義し、リトライとバリデーションを自動的に処理し、主要なLLM APIすべてとOllamaやvLLM経由のローカルモデルをサポートします。型安全なマルチターンエージェント会話も必要ならPydantic AIが適し、extractやclassifyを1行で済ませたいだけならMarvinが最速です。
LlamaなどのローカルモデルでStructured Outputを使用できますか?
はい。OutlinesはローカルモデルのConstrained Decodingに特化しています — transformers、llama.cpp、MLX、vLLM、Ollamaで動作し、生成時に出力がスキーマに対してパースできることを保証します。InstructorとPydantic AIもOllamaやvLLMをAPIとして実行する場合にサポートし、BAMLはOpenAI互換エンドポイントであれば動作します。
InstructorとMarvinの違いは何ですか?
Instructorは自分のLLMクライアントをラップし、自動リトライ付きで検証済みPydanticモデルを返すため、呼び出しを自分で制御できます。Marvin 3.xはPydantic AIの上に構築され、marvin.extract、marvin.cast、marvin.classifyといった1行のヘルパーを提供します。Instructorはより明示的で複雑なバリデーションに向き、Marvinは単純な抽出により簡潔です。なお、Marvin 2の@marvin.fnデコレータはMarvin 3で削除されました。
LangChainはStructured Outputをサポートしますか?
はい。LangChainはChatOpenAI、ChatAnthropic、ChatGoogleGenerativeAIなどのチャットモデルクラスにwith_structured_output()を提供し、create_agentで構築したエージェントはresponse_formatを受け取れます。1.x系以降、各Providerのネイティブ構造化出力対応はハードコードではなくモデルプロファイルのデータから読み取られます。すでにLangChainやLangGraphを使用していて、ライブラリを切り替えずにスキーマ強制を追加したい場合に使用してください。
Structured Outputが信頼性を高いかテストするにはどうすればよいですか?
PromptQuorumを使用して、複数のモデルで同じプロンプトを実行し、スキーマ準拠を測定します。GPT-5.6、Claude Opus 5、Gemini 3.1 Proといったモデルごとに信頼性は異なり、小さなローカルモデルではさらに差が開きます。本番デプロイ前にテストし、ローカルではInstructorやPydanticで検証してください。
「Constrained Decoding」とはどういう意味ですか?
Constrained Decodingはトークン生成をスキーマに従う有効な値のみに制限します。Outlinesは各ステップで有効な次のトークンセットを計算します。これにより、後処理バリデーションやリトライなしに出力がスキーマに対してパースできることが保証され、単純なAPIレベルのJSONモードより信頼性が高くなります。制約されるのは構造であって真実ではありません。フィールドは正しくなりますが、値は依然として確認が必要です。
BAMLとは何ですか。Instructorの代わりにいつ使うべきですか?
BAMLはスキーマファーストの言語です。スキーマとプロンプトを.bamlファイルに書き、各言語向けの型付きクライアントをコンパイルします。同じプロンプトを複数の言語から呼ぶ場合(PythonのワーカーとフロントエンドのTypeScriptが1つの契約を共有するケース)や、モデルがほぼ有効なJSONを返す場合にInstructorより適しています。BAMLのスキーマ整合パーサーはマークダウンのコードフェンス、末尾のカンマ、先頭の推論テキストをリトライせずに修復するためです。スタックがPythonだけで、スキーマを通常のPydanticコードとして保ちたいならInstructorのままで構いません。
ライブラリなしでStructured Outputを使用できますか?
技術的には可能ですが、モデルが依然として生成する壊れた出力で解析が失敗し、フィールド名や型を強制する仕組みもありません。7つのツールはそれぞれ、リトライによるバリデーション(Instructor、Marvin)、デコード時の強制(Outlines)、解析時の修復(BAML)、Provider APIのラップ(LangChain、Pydantic AI)によってこれを解決します。
どのツールが最も優れたドキュメントを持っていますか?
LangChainとPydantic AIは企業支援のため最も充実したドキュメントを持っています。BAMLのドキュメントは、言語そのものを教える必要があるため若いプロジェクトとしては異例に良質です。Instructorはコミュニティ保守ながら優れたチュートリアルと例があります。Outlinesのドキュメントは技術的ですが徹底しています。Marvinのドキュメントは簡潔です — Marvin 2の古い情報がまだ出回っているため、3.x系のページを狙って参照してください。
7つのツールすべてが必要ですか、それとも1つだけでよいですか?
1つから始めてください。Python開発者はInstructorかPydantic AIを試してください。ローカルモデルチームはOutlinesを試してください。多言語チームはBAMLを試してください。LangChainユーザーはwith_structured_output()を試してください。PromptQuorumで全モデルの一貫性を検証してください。
METIのAIガバナンスガイドラインとStructured Outputの関係は?
METIの2024年AIガバナンスガイドラインは、AIシステムの出力管理と監査可能性を求めています。Structured Outputはこれらの要件を満たす具体的な技術手段です。スキーマ定義により出力を予測可能な形式に制限し、PromptQuorumで準拠率を記録・監査できます。
日本のエンタープライズ環境でのStructured Output導入の推奨手順は?
まずOutlinesとローカルモデルで概念実証を構築し、機密データがオンプレミスに留まることを確認します。次にPromptQuorumで複数モデルの準拠率をテストし、最も適したモデルを選択します。本番環境ではInstructorまたはPydantic AIで型安全な実装を行い、継続的なモニタリングにPromptQuorumを活用してください。
出典
- Instructor GitHubリポジトリ — Instructorライブラリの公式リポジトリとドキュメント
- Outlines GitHubリポジトリ — スキーマ準拠保証のためのConstrained Decoding
- Pydantic AIドキュメント — Structured Output付き型安全エージェントフレームワーク
- LangChain Structured Outputガイド — LangChain統一Structured Output API
- BAMLドキュメント — スキーマファーストのプロンプト言語とschema-aligned parsing
- Marvin GitHubリポジトリ — Pydantic AIの上に構築されたタスク中心の抽出ライブラリ
