PydanticモデルをLLMの出力スキーマとして使用し、型安全な構造化レスポンスを取得するPythonライブラリ。OpenAI・Anthropic・Gemini等の主要APIに対応。

Instructorとは？（インストラクター）意味・特徴をわかりやすく解説

Instructor — PydanticベースのLLM構造化出力ライブラリ

Instructorは、LLM（大規模言語モデル）からPydanticモデルに準拠した型安全な構造化出力を取得するためのPythonライブラリ。2023年にJason Liuが公開し、OpenAI Function Calling / Tool Useの複雑さを抽象化して「型安全なLLM呼び出し」を簡潔に記述できる手段として急速に普及した。

コア設計思想

Instructorの中心概念は「response_model パラメータにPydanticクラスを渡すだけでLLMの出力を自動変換する」という一貫性。内部では以下の処理が自動実行される:

スキーマ注入: PydanticモデルのJSON SchemaをOpenAI Tool形式またはプロンプトに自動変換
レスポンス解析: LLMの出力（JSON文字列・関数呼び出し結果）をPydanticモデルに変換
バリデーション&リトライ: Pydantic ValidationErrorが発生した場合、エラー内容をフィードバックして最大N回自動リトライ

import instructor
from openai import OpenAI
from pydantic import BaseModel

client = instructor.from_openai(OpenAI())

class UserProfile(BaseModel):
    name: str
    age: int
    skills: list[str]

profile = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=UserProfile,
    messages=[{"role": "user", "content": "田中太郎、28歳、PythonとRust使いです"}]
)
print(profile.name)  # 田中太郎

マルチプロバイダー対応

Instructorは主要LLMプロバイダーすべてに対応しており、プロバイダーを切り替えてもコードの変更はfrom_*の部分だけで済む:

OpenAI: instructor.from_openai(OpenAI())
Anthropic: instructor.from_anthropic(Anthropic())
Google Gemini: instructor.from_gemini(genai.GenerativeModel(...))
Groq: instructor.from_groq(Groq())
Ollama: instructor.from_openai(OpenAI(base_url="http://localhost:11434/v1"))

ローカルLLM（Ollama・LM Studio）経由でも動作するため、プライバシーを重視するユースケースにも活用される。

バリデーションとリトライ

Instructorの真価はPydanticのバリデーション機能との統合にある。@field_validator を定義すると、LLMの出力がビジネスルールを満たさない場合にエラー内容を含めたフィードバックプロンプトを自動生成してリトライする:

from pydantic import field_validator

class ProductReview(BaseModel):
    rating: int
    comment: str

    @field_validator("rating")
    @classmethod
    def rating_must_be_valid(cls, v):
        if not 1 &lt;= v &lt;= 5:
            raise ValueError("評価は1〜5の整数である必要があります")
        return v

デフォルトのリトライ回数は3回で、max_retriesパラメータで変更可能。

ストリーミング対応

InstructorはPartialモデルを使ったストリーミング出力にも対応。巨大なレスポンスを生成しながらフロントエンドに逐次表示できる:

for partial_profile in client.chat.completions.create_partial(
    model="gpt-4o",
    response_model=UserProfile,
    messages=[...]
):
    print(partial_profile)  # 部分的に埋まっていくPydanticモデル

自作PC・ガジェット管理での活用例

自作PCのパーツ情報をWebスクレイピングや非構造化テキストから抽出する用途に非常に有効:

class PCPart(BaseModel):
    product_name: str
    manufacturer: str
    price_jpy: int
    category: str
    socket_type: str | None = None

# レビュー文やスペック表から構造化データを自動抽出
part_info = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=PCPart,
    messages=[{"role": "user", "content": raw_review_text}]
)

パフォーマンスと注意点

コスト増加: リトライが発生するとAPIコールが増える。バリデーションは緩くして後処理で補う設計も有効
Anthropicの制限: Claude向けにはTool Useモードが使われるが、一部のPydanticフィールド型でスキーマ変換に注意が必要
並列処理: asyncio対応版（instructor.from_openai(AsyncOpenAI())）でバッチ処理を並列化できる

2024年時点でGitHubスター数が急増し、LLMアプリケーション開発の標準ツールの一つとして定着している。

Instructor（インストラクター）