banner
aki

aki

keyboard warrior

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. 多模型 fallback#

當一個模型失敗時,自動切換到備用模型:

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 框架,支持與多種大語言模型(LLM)集成,包括 DeepSeek 和 Ollama 提供的模型。本手冊將介紹如何配置和使用 DeepSeek 的 deepseek-chat 模型以及 Ollama 的 qwen 模型,並通過一個示例展示其用法。

前置條件#

在使用之前,請確保完成以下準備工作:

  1. 安裝 pydantic-ai
    在您的 Python 環境中安裝 pydantic-ai

    pip install pydantic-ai
    
  2. DeepSeek 配置

    • 獲取 DeepSeek 的 API 密鑰:訪問 DeepSeek 官網 註冊並生成 API 密鑰。

    • 設置環境變量(可選):

      export DEEPSEEK_API_KEY='your-deepseek-api-key'
      
  3. 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',
)

# 創建兩個代理
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}

示例注意事項#

  1. DeepSeek API 密鑰
    確保您的 DeepSeek API 密鑰有效,否則會導致認證失敗。可以通過環境變量或直接在代碼中傳入。

  2. Ollama 服務運行
    使用 Ollama 時,必須確保本地服務正在運行,且指定的模型(如 qwen2.5)已下載。

  3. 性能差異

    • DeepSeek 的 deepseek-chat 是雲端模型,適合需要高性能推理的場景,但依賴網絡。
    • Ollama 的 qwen2.5 是本地模型,適合離線使用,但性能受限於本地硬件。
  4. 調試與日誌
    pydantic-ai 支持與 Pydantic Logfire 集成,可以啟用日誌來監控模型行為:

    from pydantic_ai import Logfire
    Logfire.configure()
    

注意事項#

  1. API 密鑰:確保正確配置環境變量,否則會拋出認證錯誤。
  2. 模型兼容性:檢查所選模型是否支持指定功能(如流式輸出)。
  3. 性能優化:對於高吞吐量應用,建議使用本地模型(如 Ollama)。

總結#

pydantic-ai 提供了強大的工具集,使開發者能夠以類型安全的方式構建複雜的 AI 代理。通過代理、工具和結構化輸出的結合,你可以快速開發從簡單問答到複雜業務邏輯的生產級應用。更多信息請參考 官方文檔

載入中......
此文章數據所有權由區塊鏈加密技術和智能合約保障僅歸創作者所有。