Posted inPython

PythonでのInstructorとPydantic活用ガイド：LLMから高精度な構造化データを取得する

Python tutorial - IT technology blog
Python tutorial - IT technology blog

LLM開発者を悩ませるJSONDecodeErrorという悪夢

LLMを本番システムに組み込む際、常に立ちはだかる永遠の課題があります。それは、「いかにしてバックエンドが即座にパースできる正確なJSONフォーマットをモデルに出力させるか」という点です。

自動化やバックエンド開発に携わるエンジニアなら、一度はこの光景に見覚えがあるはずです。スクリプトを100回実行して85回はスムーズに動いたとしても、86回目にOpenAIが突如```json ... ```のようなコードブロックを含めたり、末尾に余計なカンマを付けたり、必須フィールドを欠落させたりします。その結果、深夜2時にjson.loads()がJSONDecodeErrorを吐き出してパイプラインが突然クラッシュすることになります。

現在主流のStructured Outputs（構造化出力）取得アプローチ4選

要件の複雑さに応じて、通常は次の4つのアプローチのいずれかが選ばれます：

  • アプローチ1：プロンプトによる指示のみ。プロンプトの末尾に「マークダウンや説明は含めず、純粋なJSONのみを返してください」というお決まりの指示を追加します。その後、受け取った文字列をjson.loads()でパースします。
  • アプローチ2：OpenAI Function Calling / Tool Calling。toolsパラメータにJSON Schemaを渡します。モデルはそのスキーマに沿って引数（arguments）を生成しようと試みます。
  • アプローチ3：Native Structured Outputs。OpenAI APIのresponse_formatにJSON SchemaやPydanticクラスを直接指定して有効化します（2024年8月にリリースされた機能）。
  • アプローチ4：InstructorライブラリとPydanticの組み合わせ。OpenAI、Anthropic、Geminiなどのクライアントをラップするライブラリです。InstructorはPydanticクラスをスキーマに変換し、出力データを自動パースするだけでなく、スキーマ違反が発生した際には自動で自己修復（self-healing）ループを実行します。

実環境での比較：プロジェクトにはどれを選ぶべきか？

1. 純粋なPrompt Engineering

メリット：非常に素早く実装可能。追加のライブラリをインストールする必要がなく、Llama 3 8BやQwenのような軽量なローカルモデルでも動作します。

デメリット：安定性に欠ける点です。複雑な1,000件のリクエストでテストした場合、パースエラー率は通常8%〜15%程度に達します。さらに重要なのは、プロンプトの指示だけではメールアドレスの正規表現チェックや整数の範囲指定といった厳密なバリデーションを強制できないことです。

2. Function CallingとNative Structured Outputs

メリット：gpt-4oなどの最新モデルにおいて、スキーマ準拠率がほぼ100%に達します。

デメリット：ネイティブAPIが保証するのはJSON構文の妥当性と基本的なデータ型のみです。例えば「身分証番号が12桁であること」や「生年月日が過去の日付であること」のような複雑なビジネスロジックの検証は自動で行えません。バリデーションに失敗した場合、リクエストはエラーとなり、開発者自身で手動のリトライループを記述する必要があります。

3. Instructorライブラリ

メリット：

  • Pydantic v2のパワーをフル活用：型ヒントを完備し、VS CodeやPyCharmでの正確な自動補完に対応。
  • 極めてスマートなSelf-Healing（自己修復）機構：バリデータでエラーが検出されると、Instructorがエラーのトレースログを自動で収集してLLMに差し戻し、自己修正させます。
  • あらゆるモデルに対応する統一シンタックス：バリデーションロジックを変更することなく、OpenAIからAnthropic Claude 3.5 Sonnet、Google Gemini 1.5 Pro、Groqなどへ簡単に切り替え可能です。

デメリット：プロジェクトへの依存関係（dependency）が増加します。また、モデルが修正のためにリトライするたびに追加のトークンを消費し、レイテンシが500ms〜1.5秒ほど増加します。

どんな場面でInstructorを使うべきか？

1回限りの個人のスクレイピングスクリプト程度であれば、手軽なプロンプト指示だけでも十分でしょう。一方で、本番向けのAPI、カスタマーサポートボット、決済や取引を処理するワーカーなどを構築している場合、InstructorはLLMに起因する予期せぬクラッシュを根絶するための強力な救世主となります。

実践：Instructorの実装ステップ

ステップ1：環境のセットアップ

pipを使用して主要な3つのパッケージをインストールします：

pip install instructor openai pydantic

ステップ2：クライアントの初期化

Instructorは既存の接続設定を変更することなく、instructor.from_openai()関数を用いてOpenAIクライアントをラップします：

import os
from openai import OpenAI
import instructor

# 標準クライアントの初期化
raw_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# Instructorで構造化出力機能をパッチ
client = instructor.from_openai(raw_client)

ステップ3：Pydanticでデータ構造を定義

BaseModelを継承したクラスを構築します。モデルが各フィールドの抽出意図を明確に理解できるよう、Field(description=...)を積極的に活用しましょう：

from typing import List
from pydantic import BaseModel, Field

class DeveloperProfile(BaseModel):
    name: str = Field(description="エンジニアの氏名")
    years_of_experience: int = Field(description="実務経験年数")
    primary_skills: List[str] = Field(description="習熟している言語やフレームワークのリスト")
    is_senior: bool = Field(description="実務経験が5年以上の場合はTrue、それ以外はFalse")

ステップ4：APIを呼び出して型付けされたオブジェクトを取得

作成したクラスをresponse_modelパラメータに渡すだけです：

raw_text = """
グエン・ヴァン・アンはPythonの開発歴が6年以上あります。FastAPI、
Docker、PostgreSQLを得意とし、最近ではLangChainを使用したRAGプロジェクトにも参加しました。
"""

profile: DeveloperProfile = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=DeveloperProfile,
    messages=[
        {"role": "user", "content": f"候補者情報を抽出してください: {raw_text}"}
    ],
)

# IDEが属性を正確に補完するため、キーのタイプミスを防げます
print(f"氏名: {profile.name}")
print(f"経験年数: {profile.years_of_experience}年")
print(f"主なスキル: {', '.join(profile.primary_skills)}")
print(f"シニア判定: {profile.is_senior}")

ステップ5：カスタムバリデータの作成とSelf-Healingの有効化

これこそがInstructorの最大の強みです。@field_validatorを使って独自の検証ロジックを組み込むことができます：

from pydantic import BaseModel, Field, field_validator

class CustomerLead(BaseModel):
    full_name: str = Field(description="顧客氏名")
    phone_number: str = Field(description="10桁のベトナムの電話番号")
    requirement: str = Field(description="顧客の要望")

    @field_validator("phone_number")
    @classmethod
    def validate_phone(cls, v: str):
        cleaned = "".join(filter(str.isdigit, v))
        # 10桁かつベトナムの有効な市外局番（0始まり）かをチェック
        if len(cleaned) != 10 or not cleaned.startswith("0"):
            raise ValueError(f"無効な電話番号です ({v})。0から始まる10桁の数字である必要があります。")
        return cleaned

# フォーマットが乱れた入力文字列でテスト
lead_text = "顧客名：チャン・ミン・フン、折り返し先：0912-345-678、16コアサーバープランの購入について問い合わせ。"

lead = client.chat.completions.create(
    model="gpt-4o-mini",
    response_model=CustomerLead,
    max_retries=3,  # LLMによるバリデーションエラー自動修正の最大試行回数
    messages=[
        {"role": "user", "content": f"次のリード情報を処理してください: {lead_text}"}
    ],
)

print(lead.model_dump_json(indent=2))

もしLLMがハイフンを残したまま出力し、バリデータがValueErrorを発生させた場合でも、Instructorが即座にそれを捕捉します。エラーメッセージをAPIに再送信して修正を促すことで、LLMは自動的にハイフンを除去した0912345678へと整形し直し、バックエンドを停止させることなく正常な結果を返します。

実践で役立つベストプラクティス

  • Fieldの説明文（description）は明確に記述する：LLMはdescriptionの内容を基に推論を行います。説明が具体的であるほど、初回のAPIコールでの抽出精度が向上します。
  • gpt-4o-miniによるコスト最適化：高価な大規模モデルを使わずとも、データ抽出タスクの95%はgpt-4o-miniとInstructorの組み合わせで高速かつ低コストに処理できます。
  • 必ずmax_retriesを設定する：安全のためリトライ回数は2〜3回に制限しましょう。入力テキストに必要な情報が全く含まれていない場合、リトライを繰り返すと無駄にトークンを消費してしまいます。
Share:
Tags: