「BAML 対インストラクター：構造化されたLLM出力」

LLM（大規模言語モデル）を本番環境で使用する際には、構造化された、型安全な出力を得ることが極めて重要です。
BAMLおよびInstructorという2つの人気のあるフレームワークは、この問題に対して異なるアプローチを取ります。

この比較は、PythonのLLMアプリケーションに適したツールの選択を助けるものです。

構造化された出力の課題についての理解

LLMは自然に構造化されていないテキストを生成しますが、現代のアプリケーションでは予測可能で解析可能なデータが必要です。チャットボット、データ抽出パイプライン、AIエージェントを構築する際、JSONオブジェクト、検証済みのデータ型、エラーハンドリングが必要であり、自由形式の応答は不要です。

BAMLとInstructorはこの課題に対処しますが、根本的に異なる哲学に基づいています。BAMLはコード生成を伴う契約ファーストアプローチを使用し、Instructorはランタイム検証を伴うPythonの型システムを活用します。構造化された出力アプローチに関するLLMプロバイダーの比較についての幅広い文脈に興味がある場合は、これらのフレームワークの理解はさらに価値があります。

BAML: LLM向けのドメイン固有言語

BAML（BoundaryMLの言語）は、LLMの相互作用を定義するための専用のDSL（ドメイン固有言語）を導入します。.bamlファイルにプロンプト、型、関数を宣言し、BAMLはPython、TypeScript、Rubyを含む複数の言語で型安全なクライアントコードを生成します。

BAMLの主な特徴

言語横断の型安全性: BAMLは同じ.baml定義からPython、TypeScript、Rubyのクライアントを生成し、スタック全体での一貫性を確保します。

プロンプトのバージョン管理: プロンプトは.bamlファイルに保存されており、アプリケーションコードから独立してトラック、レビュー、テストが容易です。

組み込みのテストフレームワーク: BAMLにはデプロイ前のプロンプトの挙動を検証するためのツールが含まれており、開発初期段階で問題を早期に発見できます。

プレイグランドインターフェース: BAMLのプレイグランドではプロンプトを視覚的に反復処理し、即座のフィードバックを得られるため、開発サイクルを加速します。

BAMLの実装例

# まず、.bamlファイルでスキーマを定義します:
# persona.baml

class Person {
  name string
  age int
  occupation string
  skills string[]
}

function ExtractPerson(text: string) -> Person {
  client GPT4
  prompt #"
    テキストから人物情報を抽出してください: {{ text }}
    構造化されたデータを返してください。
  "#
}

生成されたPythonクライアントは型安全なアクセスを提供します:

from baml_client import b
from baml_client.types import Person

# 生成されたクライアントを使用
text = "John Smith, 34, software engineer skilled in Python and Go"
result: Person = b.ExtractPerson(text)

print(f"{result.name}は{result.age}歳です")
print(f"スキル: {', '.join(result.skills)}")

複数のサービスが同じLLM契約を使用する場合や、言語境界を越えたデータ形状について強い保証が必要な場合に、BAMLのアプローチは特に効果的です。

Instructor: PydanticネイティブのPythonフレームワーク

InstructorはPythonファーストのアプローチを取り、PydanticモデルをLLM機能で拡張します。Pydanticを使用して検証および型ヒントをすでに使用しているPython開発者にとっては自然な感覚です。

Instructorの主な特徴

ゼロのボイラープレート: Instructorは既存のPydanticモデルで単純なデコレータを使用して動作し、コード生成やビルドステップは不要です。

豊富な検証: Pydanticの検証エコシステム全体を活用できます。カスタム検証子、フィールド制約、計算フィールド、複雑なネスト構造など。

複数プロバイダサポート: OpenAI、Anthropic、Google、Ollamaを通じて統一インターフェースで動作します。

ストリーミングサポート: ストリーミング応答に対する一等のサポートと、インクリメンタルなPydanticモデル更新を提供します。

リトライロジック: リトライメカニズムが組み込まれており、指数バックオフと検証子ベースのエラーリカバリが可能です。

Instructorの実装例

from pydantic import BaseModel, Field
from instructor import from_openai
from openai import OpenAI

# Pydanticモデルを定義
class Person(BaseModel):
    name: str = Field(description="人物のフルネーム")
    age: int = Field(ge=0, le=120, description="年齢（歳）")
    occupation: str
    skills: list[str] = Field(description="専門スキルのリスト")

# OpenAIクライアントをパッチ
client = from_openai(OpenAI())

# 構造化されたデータを抽出
text = "John Smith, 34, software engineer skilled in Python and Go"
result = client.chat.completions.create(
    model="gpt-4",
    response_model=Person,
    messages=[
        {"role": "user", "content": f"人物情報を抽出してください: {text}"}
    ]
)

print(f"{result.name}は{result.age}歳です")
print(f"スキル: {', '.join(result.skills)}")

Instructorの強みはそのシンプルさと、Pythonエコシステムとの統合にあります。Pydanticを使用している場合は学習曲線は最小限です。Pythonに新しい開発者やPython特有のパターンのクイックリファレンスが必要な場合は、Pythonチートシートが役立ちます。

詳細な比較: BAML vs Instructor

開発体験

BAMLは追加のビルドステップとツール設定が必要です。.bamlファイルを記述し、ジェネレータを実行し、生成されたコードをインポートします。これにより、プロンプトエンジニアリングとアプリケーション論理の間に明確な分離が生まれ、これは大きなチームにとって有益です。

Instructorはゼロのセットアップ摩擦があります。pip installで準備が完了します。プロンプトはコードの隣に配置されるため、小さなプロジェクトやプロトタイプでは迅速な反復が容易です。

型安全性と検証

BAMLは生成されたコードでコンパイル時型チェックを提供します。IDEは実行前にどのフィールドが利用可能か正確に把握します。同じ.bamlファイルがすべてのサポート言語でクライアントを生成するため、言語横断の一貫性が保証されます。

InstructorはPydanticを通じてランタイム検証を提供します。Pythonの型ヒントはIDEサポートを提供しますが、エラーは実行時に表面化します。これはPythonの標準ですが、BAMLの生成コードよりも静的な保証は少なくなります。

ローカルLLMとの連携

両方のフレームワークはローカルモデルをサポートしており、これはプライバシー、コスト管理、オフライン開発において極めて重要です。Ollamaや他のローカルLLMプロバイダーを使用する際には、外部API依存なしに構造化出力の利点を維持できます。Ollama、Qwen3およびPythonまたはGoを使用してLLMを構造化出力で制約するについてさらに詳しく知りたい場合は、これらのフレームワークは下位APIに対する生産性の高い抽象化を提供します。

BAMLは.bamlファイルでクライアントを設定することでOllamaに接続します:

# .bamlファイル内で:
client OllamaLocal {
  provider ollama
  options {
    model "llama2"
    base_url "http://localhost:11434"
  }
}

InstructorはOpenAI互換APIを通じてOllamaと連携します:

from openai import OpenAI
from instructor import from_openai

client = from_openai(OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # ダミーのキー
))

ローカルモデルを使用する際には、OllamaおよびGPT-OSSモデルにおける構造化出力の潜在的な問題に注意する必要があります。すべてのモデルが構造化出力を同等の信頼性で処理するわけではありません。

エラーハンドリングとリトライ

BAMLはフレームワークレベルでリトライを処理し、構成可能な戦略を提供します。スキーマ検証エラーは自動的にエラーコンテキスト付きでリプロンプトをトリガーします。

Instructorはデコレータによるリトライロジックを提供し、カスタム動作のためのフックが可能です。検証子でリトライをトリガーするプロンプトを定義できます:

from instructor import patch
from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(3))
def extract_with_retry(text: str) -> Person:
    return client.chat.completions.create(
        model="gpt-4",
        response_model=Person,
        messages=[{"role": "user", "content": text}]
    )

テストと観測性

BAMLにはテストフレームワークが含まれており、.bamlファイル内でテストケースを直接記述して、さまざまな入力に対するプロンプトの挙動を検証できます。プレイグランドは視覚的なデバッグを提供します。

Instructorは標準のPythonテストフレームワークと統合しています。pytestのフィクスチャ、モッキングライブラリ、アサーションヘルパーをPythonコードのように使用できます。

パフォーマンスの考慮

実行時パフォーマンスは比較的同等です。両フレームワークは最終的には同じLLM APIコールを行います。検証および解析のオーバーヘッドはネットワーク遅延やモデル推論時間と比較して無視できるほどです。

開発速度は大きく異なります:

• BAMLのコード生成により、より良いオートコンプリートと早期エラー検出が可能ですが、ビルドステップが必要です
• Instructorのデコレータアプローチにより、イテレーションが速くなりますが、実行時エラーの発見がされます

数百万のリクエストを処理する生産システムでは、両フレームワークは同等に負荷を処理できます。あなたの選択はパフォーマンス特性よりも開発ワークフローの好みに依存します。

BAMLを選択するべきケース

BAMLを選択するべき状況:

• 多言語サポート: Python、TypeScript、Rubyサービスから同じLLM契約にアクセス
• 契約ファースト開発: 実装前のLLMインターフェースの設計
• チーム協力: プロンプトエンジニアリングワークフローとアプリケーション開発の分離
• 強力な型の保証: 全スタックでのコンパイル時チェック
• 視覚的なプロンプト開発: プレイグランド駆動のプロンプト反復処理

Instructorを選択するべきケース

Instructorを選択するべき状況:

• Python専用プロジェクト: 言語横断の一貫性の必要がない
• 迅速なプロトタイピング: 構造化出力の動作をすぐに開始したい
• Pydantic統合: 既存のPydanticモデルと検証子を活用
• 単純なデプロイ: ビルドステップや生成コードの管理が不要
• 豊富なPythonエコシステム: Python特有のライブラリやパターンを使用

アプローチの組み合わせ

いくつかのプロジェクトでは、両フレームワークを使用することでメリットがあります。例えば、顧客向けAPIでクロス言語クライアントが必要な場合はBAMLを使用し、内部のPythonサービスで迅速な反復が必要な場合はInstructorを使用します。

プロジェクトが成熟するにつれて、フレームワークの間で移行することも可能です。最初はInstructorで迅速な検証を行い、広範な言語サポートや厳格な契約が必要になる場合はBAMLに移行します。

実際のユースケース

データ抽出パイプライン（BAML）

ドキュメント処理システムは、BAMLを使用して請求書、契約、領収書から構造化されたデータを抽出します。.baml定義はMLチームとバックエンドサービス間の契約として機能し、ウェブダッシュボードにはTypeScriptクライアント、バッチ処理にはPythonクライアントが使用されます。

顧客サポートボット（Instructor）

サポートボットは、Instructorを使用してチケットを分類し、ユーザーの意図を抽出し、応答を生成します。チームはPydanticモデルを使用してプロンプトを迅速に反復処理し、検証子で抽出された電話番号、メールアドレス、チケットIDがフォーマット要件を満たすことを保証します。

マルチモーダルAIエージェント（両方）

AIエージェントシステムは、BAMLを使用してエージェント間の通信契約を確立し、分散システム全体で型安全性を確保します。個々のエージェントは内部でInstructorを使用して、ユーザー入力の柔軟なPythonネイティブ処理を行います。PythonでMCPサーバーを構築する場合も同様のパターンが適用され、構造化された出力によりAIアシスタントとの信頼性のあるツール統合が可能になります。

移行と統合の経路

LLMと基本的なJSONパースを使用している場合、両フレームワークは移行経路が簡単です:

JSONからBAMLへの移行: JSONスキーマをBAMLの型定義に変換し、プロンプトを.bamlファイルに移動し、クライアントを生成し、手動のパースを生成された型で置き換えます。

JSONからInstructorへの移行: JSON構造に一致するPydanticモデルを追加し、instructorをインストールし、OpenAIクライアントをパッチし、JSONパースをresponse_modelパラメータで置き換えます。

両方の移行は段階的に行うことができます。一度にコードベース全体を変換する必要はありません。

今後の展望とコミュニティ

両フレームワークは活発に開発されており、強いコミュニティがあります:

BAML（BoundaryML）は、言語サポートの拡張、プレイグランドの改善、テスト機能の強化に注力しています。商業的なバックアップがあるため、長期的な安定性が期待できます。

Instructorは、頻繁な更新、豊富なドキュメント、拡大する採用を特徴とする強力なオープンソースコミュニティを維持しています。プロジェクトはJason Liuと貢献者によって良好にメンテナンスされています。

結論

BAMLとInstructorは、構造化されたLLM出力に関して2つの優れたが異なるアプローチを代表しています。BAMLの契約ファースト、多言語哲学は、厳密な型要件を持つ分散システムを構築するチームに最適です。InstructorのPythonネイティブ、Pydanticベースのアプローチは、迅速な開発とPython中心のスタックに適しています。

どちらも普遍的に優れているわけではありません。チームの規模、言語の好み、開発ワークフロー、型安全性の要件によって選択が決まります。多くのチームが、プロトタイピングにはInstructorを、生産環境のマルチサービスアーキテクチャにはBAMLを採用することで、両方の利点を享受できると見込まれます。

有用なリンク

このサイトの関連記事

• 構造化された出力でLLMを制約: Ollama、Qwen3およびPythonまたはGo
• 人気LLMプロバイダー（OpenAI、Gemini、Anthropic、Mistral、AWS Bedrock）における構造化出力の比較
• Ollama GPT-OSS構造化出力の問題
• PythonでMCPサーバーを構築する: ネット検索とスクレイピング
• Pythonチートシート
• Ollamaチートシート

外部参照

• BAML公式ドキュメント
• BAML GitHubリポジトリ
• Instructorライブラリドキュメント
• Instructor GitHubリポジトリ
• Pydanticドキュメント
• OpenAI構造化出力ガイド
• Ollama Pythonライブラリ