AI Engineering Academy · レッスン

Instructor：Pydanticによる型付き抽出

instructorライブラリを使ってOpenAIクライアントをラップし、抽出に成功するまでPydanticスキーマに対するレスポンスの検証と自動リトライを行えるようにします。

レッスン 1/413 ステップ

「Instructor：Pydanticによる型付き抽出」はCoddyKit上の無料AI Engineering Academyレッスンです。これはレッスン1/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはAI Engineering Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Engineering Academyコースには全4レッスンが含まれています。

Instructorライブラリとは

instructorライブラリは、構造化抽出を確実にするOpenAIクライアント用の薄いラッパーです。モデルが有効なJSONを返すことを期待する代わりに、instructorはPydanticスキーマを適用し、検証に失敗した場合は自動的に再試行します。これにより、独自のパース処理や再試行ロジックを自分で実装する必要がなくなります。

Instructorのインストール

1つのpipコマンドでinstructorをインストールできます。pydantic v2とopenai SDKが必要です。インストール後、instructor.patch()でOpenAIクライアントにパッチを適用すると、すべての呼び出しでresponse_modelパラメーターをサポートする拡張クライアントを利用できます。

pip install instructor openai pydantic

OpenAIクライアントへのパッチ適用

Instructorは、標準のOpenAIクライアントにパッチを適用して動作します。instructor.from_openai(client)を呼び出すと、新しいクライアントが返されます。このクライアントでは、すべてのchat.completions.create呼び出しがresponse_modelキーワード引数を受け取れます。基盤となるAPI呼び出しは同じで、instructorはその上にスキーマの適用機能を追加するだけです。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

Pydanticスキーマの定義

モデルから返してほしいデータの形を、Pydantic BaseModelとして定義します。フィールド名、型、docstringは自動的にJSON Schemaへ変換され、モデルに送信されます。モデルが何を入力すべきか理解できるよう、明確で説明的なフィールド名を使用してください。ビジネスルールにはバリデーターを追加します。

from pydantic import BaseModel, Field
from typing import Optional

class PersonExtract(BaseModel):
    name: str = Field(description='Full name of the person')
    age: Optional[int] = Field(None, description='Age in years if mentioned')
    email: Optional[str] = Field(None, description='Email address if present')
    company: Optional[str] = Field(None, description='Company or employer')

抽出リクエストの実行

パッチを適用したクライアントのresponse_modelに、Pydanticモデルクラスを渡します。Instructorは内部でツール呼び出しを構築し、モデルがフィールドを埋め、結果を型付きPythonオブジェクトにデシリアライズします。返されたデータでは、IDEの完全な自動補完と型安全性を利用できます。

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[
        {'role': 'user', 'content': 'Alice Smith, 34, works at Acme Corp. Email: alice@acme.com'}
    ]
)
print(result.name)   # Alice Smith
print(result.email)  # alice@acme.com

検証失敗時の自動再試行

モデルがPydanticの検証に失敗するデータを返した場合、instructorは検証エラーを自動的にモデルへ送り返し、応答を修正するよう求めます。max_retriesパラメーターで最大再試行回数を設定できます。この自己修復ループにより、追加のコードを書かなくても、一時的な抽出失敗の大部分を解消できます。

import instructor
from openai import OpenAI
from pydantic import BaseModel, field_validator

client = instructor.from_openai(OpenAI())

class Product(BaseModel):
    name: str
    price_usd: float

    @field_validator('price_usd')
    @classmethod
    def must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('Price must be positive')
        return v

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=Product,
    max_retries=3,
    messages=[{'role': 'user', 'content': 'Widget costs $12.99'}]
)

複雑な構造に対応するネストモデル

InstructorはネストされたPydanticモデルをシームレスに処理します。リスト、オプションのサブオブジェクト、判別共用体を含む、深くネストされたスキーマを定義できます。モデルは完全なJSON Schemaを受け取り、必須フィールドをすべて埋める必要があるため、複数のセクションを持つ請求書や履歴書など、構造化オブジェクトの抽出に適しています。

from pydantic import BaseModel
from typing import List

class LineItem(BaseModel):
    description: str
    quantity: int
    unit_price: float

class Invoice(BaseModel):
    vendor: str
    invoice_number: str
    total_amount: float
    line_items: List[LineItem]

result = client.chat.completions.create(
    model='gpt-4o',
    response_model=Invoice,
    messages=[{'role': 'user', 'content': invoice_text}]
)

部分抽出のストリーミング

大規模な抽出処理では、instructorはinstructor.Partial[YourModel]による部分ストリーミングをサポートします。モデルがトークンを生成すると、部分的に値が入力されたモデルインスタンスをリアルタイムで受け取れます。完全な応答を待つのではなく、UIで進捗を表示したり、フィールドが届いた時点で処理したりする場合に便利です。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

for partial in client.chat.completions.create_partial(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': long_text}]
):
    print(partial.name, partial.email)

オブジェクトのリストの抽出

1つのドキュメントから複数のエンティティを抽出する必要がある場合は、モデルをList[YourModel]でラップします。InstructorがJSON配列のスキーマを処理し、各要素を型付きPythonオブジェクトにデシリアライズします。このパターンは、記事に登場するすべての人物、明細書内のすべての取引、契約書内のすべての日付を抽出する場合などに適しています。

from pydantic import BaseModel
from typing import List

class Mention(BaseModel):
    entity: str
    entity_type: str  # PERSON, ORG, DATE, LOCATION
    context: str

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=List[Mention],
    messages=[{'role': 'user', 'content': article_text}]
)
for mention in result:
    print(f'{mention.entity} ({mention.entity_type})')

抽出に適したモデルの選択

すべての抽出にGPT-4oが必要なわけではありません。10フィールド未満の単純なフラットスキーマでは、gpt-4o-miniが10分の1のコストでほぼ同じ結果を生成します。複雑なネストスキーマ、長いドキュメント、または再現率が重要なケースではGPT-4oを使用してください。本番用のモデルを選ぶ前に、必ず実際のデータのサンプルでベンチマークを実施しましょう。

# Cost comparison for 1000 extractions
# GPT-4o-mini: ~$0.002 per call = $2.00 total
# GPT-4o: ~$0.015 per call = $15.00 total
# Test both on 50 samples and compare F1 score
# before committing to the expensive model

抽出のログ記録とデバッグ

Instructorは可観測性のためのhooksシステムを提供します。on_completionコールバックを登録して、各抽出の生のAPIレスポンス、トークン使用量、再試行回数をログに記録できます。これにより、どの種類のドキュメントで失敗が最も多いかを特定し、それに応じてスキーマやプロンプトを調整できます。

import instructor
from openai import OpenAI

client = instructor.from_openai(OpenAI())

@client.on('completion:response')
def log_usage(response):
    usage = response.usage
    print(f'Tokens: {usage.prompt_tokens}+{usage.completion_tokens}')

result = client.chat.completions.create(
    model='gpt-4o-mini',
    response_model=PersonExtract,
    messages=[{'role': 'user', 'content': text}]
)

理解度チェック

型付き抽出におけるinstructorライブラリについての理解度を確認しましょう。

対話的なレッスンで答える

レッスンのまとめ

このレッスンでは、instructorがOpenAIクライアントにパッチを適用することでresponse_modelパラメーターを受け付け、Pydanticスキーマを適用できること、検証失敗時の自動再試行によって手動のエラー処理なしでも抽出を堅牢にできること、そしてネストモデルとリスト抽出によって、複雑な複数エンティティのドキュメントを完全に型付けされたPythonオブジェクトとして解析できることを学びました。次は、抽出スキーマ内の部分データと欠損データを扱います。

無料で開始

AI チューターと学ぶ Python — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース: 30
レッスン: 120

無料で学習を始めるコース全体を表示

よくある質問

「Instructor：Pydanticによる型付き抽出」レッスンは無料ですか？

はい。「Instructor：Pydanticによる型付き抽出」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Engineering Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Engineering Academyコースには全4レッスンが含まれています。

「Instructor：Pydanticによる型付き抽出」で何を学びますか？

instructorライブラリを使ってOpenAIクライアントをラップし、抽出に成功するまでPydanticスキーマに対するレスポンスの検証と自動リトライを行えるようにします。ブラウザで直接実行するハンズオンコードでAI Engineering Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

AI Engineering Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのAI Engineering Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン1/4です。

「Instructor：Pydanticによる型付き抽出」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このAI Engineering Academyレッスンでコードを書いて実行できますか？

はい。すべてのAI Engineering Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← AI Engineering Academyに戻る