Pydantic-AI の使用

Pydantic-AI 使用#

ようこそ pydantic-ai へ。これは生成的 AI アプリケーションのために設計された Python プロキシフレームワークで、開発者がプロダクションレベルのアプリケーションをより簡単に構築できるようにすることを目的としています。Pydantic チームによって開発され、Pydantic の型安全性とデータ検証機能を継承し、大規模言語モデル（LLM）向けに最適化されています。

このドキュメントでは、pydantic-ai のコアモジュールとその使用法について説明します。インストール、基本概念、プロキシの作成、ツールの使用、および高度な機能の例が含まれています。

インストール#

基本インストール#

pip を使用して pydantic-ai をインストールします：

pip install pydantic-ai

スリム版インストール#

特定のモデルのみを使用したい場合、余分な依存関係を避けるためにスリム版を選択できます：

pip install pydantic-ai-slim

オプションの依存関係#

必要に応じて特定のモデルのサポートをインストールします。例えば：

OpenAI モデルのサポート：

pip install pydantic-ai[openai]
完全モデルのサポート（OpenAI、Anthropic、Gemini などを含む）：
pip install pydantic-ai[all]

環境設定#

使用前に API キーを設定する必要があります。例えば：

import os os.environ["OPENAI_API_KEY"] = "あなたのAPIキー"

コアモジュールと概念#

1. Agent（エージェント）#

Agent は pydantic-ai のコアクラスで、LLM と対話するために使用されます。システムプロンプト、ツール、構造化出力をカプセル化します。

主なパラメータ：
- model: 使用する LLM モデルを指定します（例： 'openai' または 'gemini-1.5-flash'）。
- system_prompt: システムプロンプト、エージェントの動作を定義します。
- result_type: 構造化出力のタイプ、Pydantic モデルを使用して定義します。

2. BaseModel（Pydantic モデル）#

Pydantic の BaseModel を継承し、入力と出力のデータ構造を定義して、型安全性と検証を確保します。

3. RunContext（実行コンテキスト）#

実行時のコンテキスト情報を提供し、ツール関数内で依存関係や入力データにアクセスできます。

4. ツール（Tools）#

@agent.tool デコレーターを使用して定義され、エージェントが機能を拡張するためにカスタム関数を呼び出すことを許可します。

クイックスタート#

シンプルなエージェントを作成する#

以下の例は、エージェントを作成し、質問をして構造化された応答を取得する方法を示しています：

from pydantic import BaseModel
from pydantic_ai import Agent


# 出力構造を定義
class Answer(BaseModel):
    text: str
    confidence: float


# エージェントを作成
agent = Agent(
    model="openai:gpt-4", system_prompt="簡潔で正確な回答を提供してください。", result_type=Answer
)
result = agent.run_sync("中国の首都はどこですか？")
print(result.data)
# 出力例：Answer(text='北京', confidence=0.99)

モジュールの詳細と使用方法#

1. エージェントの初期化 (Agent)#

エージェントは複数のモデルをサポートしており、以下は一般的な設定です：

from pydantic_ai import Agent

# Gemini モデルを使用
agent = Agent(
    model="gemini-1.5-flash", system_prompt="中国語で質問に答え、簡潔にしてください。", retries=3
)
# Ollama のローカルモデルを使用
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.openai import OpenAIProvider

ollama_model = OpenAIModel(
    model_name="llama3.2", provider=OpenAIProvider(base_url="http://localhost:11434/v1")
)
agent = Agent(ollama_model)

2. 構造化出力の定義#

Pydantic モデルを使用して出力形式を定義し、一貫性を確保します：

from pydantic_ai import Agent
from pydantic import BaseModel, Field


class CityInfo(BaseModel):
    city: str = Field(description="都市名")
    country: str = Field(description="国名")


agent = Agent(model="openai:gpt-4", result_type=CityInfo)
result = agent.run_sync("2012年のオリンピックはどこで開催されましたか？")
print(result.data)  # 出力例：CityInfo(city='ロンドン', country='イギリス')

3. ツールの追加#

ツールはエージェントが外部操作を実行することを許可します。例えば、データベースクエリ：

from pydantic_ai import Agent, RunContext

agent = Agent(model="openai:gpt-4", system_prompt="ユーザーの入力に基づいて天気を照会します。")


@agent.tool
def get_weather(ctx: RunContext[str]) -> str:
    city = ctx.input_data
    return f"{city}の天気は晴れ、気温は25°Cです。"


result = agent.run_sync("北京の天気はどうですか？")
print(result.data)  # 出力例：'北京の天気は晴れ、気温は25°Cです。'

4. 依存性注入#

deps_type を指定して依存性の種類を指定し、実行時データを注入します：

from dataclasses import dataclass


@dataclass
class WeatherDB:
    city: str


agent = Agent(
    model="openai:gpt-4", deps_type=WeatherDB, system_prompt="データベースに基づいて天気情報を提供します。"
)
result = agent.run_sync("今日の天気", deps=WeatherDB(city="上海"))
print(result.data)

5. ストリーミング応答#

ストリーミング出力をサポートし、リアルタイムアプリケーションに適しています：

async def stream_example():
    agent = Agent(model="openai:gpt-4", system_prompt="質問に段階的に答えます。")
    async for chunk in agent.run_stream("Python の歴史について説明してください"):
        print(chunk.data, end="", flush=True)


import asyncio

asyncio.run(stream_example())

高度な機能#

1. リトライメカニズム#

retries パラメータを設定し、検証が失敗した場合に自動的にリトライします：

agent = Agent(model="gemini-1.5-flash", retries=3, result_type=CityInfo)
result = agent.run_sync("オリンピックは2012年にどこで開催されましたか？")

2. Pydantic Logfire 統合#

デバッグとパフォーマンスモニタリングに使用します：

import logfire
from pydantic_ai import Agent

logfire.configure()
agent = Agent(model="openai:gpt-4")
logfire.instrument_pydantic()
# 検証ログを記録 result = agent.run_sync("テストの質問")

3. 複数モデルのフォールバック#

あるモデルが失敗した場合、自動的にバックアップモデルに切り替えます：

from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.models.fallback import FallbackModel

openai_model = OpenAIModel("gpt-4o")
backup_model = OpenAIModel("gpt-3.5-turbo")
fallback = FallbackModel(openai_model, backup_model)
agent = Agent(fallback)
result = agent.run_sync("質問")

例：銀行サポートエージェント#

以下は完全な銀行サポートエージェントの例です：

from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext


@dataclass
class SupportDependencies:
    customer_id: int


class SupportResult(BaseModel):
    advice: str = Field(description="顧客へのアドバイス")
    block_card: bool = Field(description="カードを凍結するかどうか")


agent = Agent(
    model="openai:gpt-4",
    deps_type=SupportDependencies,
    result_type=SupportResult,
    system_prompt="銀行の一次サポートとして、顧客の問題を分析し、アドバイスを提供します。",
)


@agent.tool
def check_account(ctx: RunContext[SupportDependencies]) -> str:
    return f"顧客 {ctx.deps.customer_id} のアカウントは正常です。"


result = agent.run_sync(
    "私のカードを失くしたらどうすればいいですか？", deps=SupportDependencies(customer_id=12345)
)
print(result.data)
# 出力例：SupportResult(advice='すぐにカードを凍結してください。', block_card=True)

pydantic-ai を使用して DeepSeek と Ollama の Qwen モデルに接続する#

pydantic-ai は強力な Python フレームワークで、DeepSeek と Ollama が提供するモデルを含む多くの大規模言語モデル（LLM）との統合をサポートしています。このマニュアルでは、DeepSeek の deepseek-chat モデルと Ollama の qwen モデルを設定して使用する方法を説明し、例を通じてその使用法を示します。

前提条件#

使用する前に、以下の準備を完了してください：

pydantic-ai のインストール
Python 環境に pydantic-ai をインストールします：
```
pip install pydantic-ai
```
DeepSeek の設定
- DeepSeek の API キーを取得します： DeepSeek の公式サイトにアクセスして登録し、API キーを生成します。
- 環境変数を設定します（オプション）：
```
export DEEPSEEK_API_KEY='your-deepseek-api-key'
```
Ollama の設定
- Ollama をインストールします： Ollama の公式ドキュメントに従って Ollama をダウンロードしてインストールします。
- Qwen モデル（例： qwen2.5）をダウンロードします：
```
ollama pull qwen2.5
```
- Ollama サービスがローカルで実行されていることを確認します：
```
ollama serve
```

DeepSeek モデルの設定#

以下は pydantic-ai を使用して DeepSeek の deepseek-chat モデルを設定するためのサンプルコードです：

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.deepseek import DeepSeekProvider
from pydantic import BaseModel

# 戻り値のデータ構造を定義
class BankQueryResult(BaseModel):
    action: str
    details: str

# DeepSeek モデルを設定
deepseek_model = OpenAIModel(
    model_name='deepseek-chat',
    provider=DeepSeekProvider(
        api_key='your-deepseek-api-key',  # あなたの API キーに置き換えてください
    )
)

# エージェントを作成
agent = Agent(model=deepseek_model, result_type=BankQueryResult)

# クエリを実行
result = agent.run_sync('友人に100元を送金したいのですが、どうすればいいですか？')
print(result.data)
# 出力例：{'action': '送金', 'details': '銀行アプリにログインし、送金機能を選択し、友人の口座と100元の金額を入力し、確認してください。'}

Ollama の Qwen モデルの設定#

以下は pydantic-ai を使用して Ollama の qwen2.5 モデルを設定するためのサンプルコードです：

from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
from pydantic import BaseModel

# 戻り値のデータ構造を定義
class BankQueryResult(BaseModel):
    action: str
    details: str

# Ollama の Qwen モデルを設定
ollama_model = OllamaModel(
    model_name='qwen2.5',  # このモデルが ollama pull でダウンロードされていることを確認してください
    base_url='http://localhost:11434/v1',  # デフォルトの Ollama ローカルサービスアドレス
)

# エージェントを作成
agent = Agent(model=ollama_model, result_type=BankQueryResult)

# クエリを実行
result = agent.run_sync('私の口座の残高を確認したいのですが、どうすればいいですか？')
print(result.data)
# 出力例：{'action': '残高確認', 'details': '銀行アプリにログインし、アカウントページに移動し、残高確認オプションを選択してください。'}

例：DeepSeek と Ollama の Qwen モデルを使用して銀行クエリを処理する#

以下は、DeepSeek と Ollama の Qwen モデルを組み合わせて、複雑な銀行関連のクエリを処理する例です：

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
from pydantic_ai.providers.deepseek import DeepSeekProvider
from pydantic_ai.models.ollama import OllamaModel
from pydantic import BaseModel

# 戻り値のデータ構造を定義
class ComplexBankQuery(BaseModel):
    question_type: str
    answer: str
    confidence: float

# DeepSeek モデルを設定
deepseek_model = OpenAIModel(
    model_name='deepseek-chat',
    provider=DeepSeekProvider(
        api_key='your-deepseek-api-key',  # あなたの API キーに置き換えてください
    )
)

# Ollama の Qwen モデルを設定
qwen_model = OllamaModel(
    model_name='qwen2.5',
    base_url='http://localhost:11434/v1',
)

# 2つのエージェントを作成
deepseek_agent = Agent(model=deepseek_model, result_type=ComplexBankQuery)
qwen_agent = Agent(model=qwen_model, result_type=ComplexBankQuery)

# DeepSeek エージェントをテスト
deepseek_result = deepseek_agent.run_sync('小額ローンを申請するにはどうすればいいですか？')
print("DeepSeek の回答：", deepseek_result.data)
# 出力例：{'question_type': 'ローン申請', 'answer': '銀行に連絡し、ローン申請書と身分証明書を提出し、承認を待ちます。', 'confidence': 0.95}

# Qwen エージェントをテスト
qwen_result = qwen_agent.run_sync('小額ローンを申請するにはどうすればいいですか？')
print("Qwen の回答：", qwen_result.data)
# 出力例：{'question_type': 'ローン申請', 'answer': '銀行アプリにログインし、小額ローンオプションを選択し、情報を入力して提出してください。', 'confidence': 0.92}

例の注意事項#

DeepSeek API キー
あなたの DeepSeek API キーが有効であることを確認してください。そうでないと認証に失敗します。環境変数またはコード内で直接渡すことができます。
Ollama サービスの実行
Ollama を使用する際は、ローカルサービスが実行中であり、指定されたモデル（例： qwen2.5）がダウンロードされていることを確認してください。
パフォーマンスの違い
- DeepSeek の deepseek-chat はクラウドモデルで、高性能推論が必要なシーンに適していますが、ネットワークに依存します。
- Ollama の qwen2.5 はローカルモデルで、オフライン使用に適していますが、パフォーマンスはローカルハードウェアに制限されます。
デバッグとログ
pydantic-ai は Pydantic Logfire 統合をサポートしており、モデルの動作を監視するためにログを有効にできます：
```
from pydantic_ai import Logfire
Logfire.configure()
```

注意事項#

API キー：環境変数が正しく設定されていることを確認してください。そうでないと認証エラーが発生します。
モデルの互換性：選択したモデルが指定された機能（ストリーミング出力など）をサポートしているか確認してください。
パフォーマンスの最適化：高スループットアプリケーションの場合、ローカルモデル（Ollama など）を使用することをお勧めします。

まとめ#

pydantic-ai は、開発者が型安全な方法で複雑な AI エージェントを構築できる強力なツールセットを提供します。エージェント、ツール、および構造化出力の組み合わせにより、シンプルな Q&A から複雑なビジネスロジックのプロダクションレベルのアプリケーションを迅速に開発できます。詳細については公式ドキュメントを参照してください。