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 模型) 2. 基础模型(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 代理。通过代理、工具和结构化输出的结合,你可以快速开发从简单问答到复杂业务逻辑的生产级应用。更多信息请参考 官方文档

加载中...
此文章数据所有权由区块链加密技术和智能合约保障仅归创作者所有。