使用 Pydantic AI 构建类型安全的 LLM 智能体

作者
  • avatar
    姓名
    Nino
    职业
    Senior Tech Editor

在大语言模型（LLM）的应用开发中，最让开发者头疼的问题莫过于模型输出的不确定性。通常情况下，LLM 返回的是非结构化的字符串，这使得在生产环境中对其进行解析和处理变得异常困难。为了解决这一痛点，Pydantic AI 应运而生。作为一个专门为 Python 开发者设计的框架，它继承了 Pydantic 和 FastAPI 的设计哲学，旨在通过类型提示（Type Hints）和自动验证，为 LLM 的交互流程注入严谨的工程化标准。借助 Pydantic AI，开发者可以轻松构建出返回经过验证的对象、而非原始文本的智能体（Agents）。

为什么选择 Pydantic AI？

在过去，为了从 LLM 的响应中提取特定信息，开发者往往需要编写复杂的正则表达式，或者祈祷模型能够返回完美的 JSON 格式。一旦模型输出稍有偏差（例如多了一个逗号或字段名拼写错误），整个下游业务逻辑就会崩溃。Pydantic AI 的核心优势在于它将“模式定义”（Schema Definition）置于首位。通过定义 Pydantic 的 BaseModel，你可以明确要求模型返回的数据结构。如果模型输出不符合预期，框架会自动捕获错误并尝试修复。

在开发此类应用时，选择一个稳定且支持多种主流模型的 API 平台至关重要。n1n.ai 提供了一站式的 API 聚合服务，让开发者能够无缝切换 DeepSeek-V3、GPT-4o 或 Claude 3.5 Sonnet，从而测试不同模型在处理复杂 Pydantic 模型时的表现。

Pydantic AI 的核心组件解析

1. 智能体（Agent）类

Agent 是 Pydantic AI 的核心。它不仅仅是一个 LLM 的封装器，更是一个集成了系统提示词、模型配置和结果验证的逻辑单元。你可以直接在实例化时指定 result_type，告诉框架你期望得到的 Python 对象类型。

2. 类型安全的工具调用（Tool Calling）

工具调用是智能体与外部世界交互的关键。Pydantic AI 使用 @agent.tool 装饰器将普通 Python 函数注册为智能体可调用的工具。最精妙之处在于，框架会根据函数的类型签名和文档字符串（Docstring）自动生成供 LLM 理解的 JSON Schema。这意味着，如果你的函数定义要求输入一个整数，LLM 就绝不会（或者说极难）传入一个字符串。

3. 依赖注入（Dependency Injection）

对于复杂的企业级应用，智能体往往需要访问数据库连接、配置文件或用户会话。Pydantic AI 引入了类似 FastAPI 的依赖注入机制。通过 deps_type 参数，你可以将这些运行时上下文安全地传递给工具函数，而无需依赖全局变量。这种设计极大地提升了代码的可测试性和并发安全性。

实战演练：构建一个天气建议智能体

下面我们通过一个具体的代码示例，展示如何结合工具调用和依赖注入来构建一个实用的智能体。

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

# 定义依赖项
@dataclass
class UserContext:
    user_id: str
    preferred_unit: str = '摄氏度'

# 定义结构化输出模型
class WeatherResponse(BaseModel):
    location: str
    temperature: float
    advice: str

# 创建智能体
weather_agent = Agent(
    'openai:gpt-4o',
    deps_type=UserContext,
    result_type=WeatherResponse,
    system_prompt='你是一个专业的天气助手。'
)

# 注册工具
@weather_agent.tool
async def fetch_weather(ctx: RunContext[UserContext], city: str) -> str:
    # 在实际场景中，这里会调用第三方天气 API
    unit = ctx.deps.preferred_unit
    return f'{city}当前气温为 22 {unit}，天气晴朗。'

# 执行任务
user_deps = UserContext(user_id='dev_001')
result = weather_agent.run_sync('上海现在的天气怎么样？适合穿什么？', deps=user_deps)

print(f'城市: {result.data.location}')
print(f'建议: {result.data.advice}')

验证重试机制：提升鲁棒性的双刃剑

Pydantic AI 提供了一个非常实用的功能：验证重试（Validation Retries）。当 LLM 返回的数据无法通过 Pydantic 验证时（例如某个必填字段缺失），框架不会立即报错，而是会将错误信息反馈给 LLM，并要求其重新生成。这种机制显著提高了智能体的成功率，但也带来了额外的 Token 消耗。因此，建议开发者在 n1n.ai 控制台中实时监控 API 的调用成本，并根据实际需求调整重试次数限制。

不同模型的兼容性分析

在构建类型安全的应用时，模型的选择至关重要：

  • OpenAI (GPT-4o): 对结构化输出的支持最为完善，支持“严格模式（Strict Mode）”，解析成功率最高。
  • Anthropic (Claude 3.5): 在遵循复杂指令和长文本处理方面表现优异，非常适合作为逻辑复杂的智能体大脑。
  • DeepSeek-V3: 极具性价比的选择，在逻辑推理和工具调用准确度上已逼近顶级模型，非常适合大规模部署。
  • Google Gemini: 拥有超长上下文窗口，适合处理需要引用大量背景信息的任务。

通过 n1n.ai，你可以轻松测试这些模型在同一套 Pydantic 模式下的表现，找到性能与成本的最优平衡点。

专家建议与最佳实践

  1. 精简 Schema: 尽量避免定义过于深层嵌套的 Pydantic 模型。模型层级越深，LLM 生成正确结构的难度就越大。
  2. 强化文档字符串: 不要吝啬在工具函数的 Docstring 中添加详细描述和示例。这是 LLM 学习如何使用该工具的唯一信息来源。
  3. 异常处理: 尽管有重试机制，但在生产环境中仍需处理最终验证失败的情况。设置合理的 max_retries 能够有效防止 Token 浪费。
  4. 环境隔离: 利用 Pydantic AI 的依赖注入功能，将开发环境和生产环境的 API 密钥、数据库地址等敏感信息隔离开来。

总结

Pydantic AI 的出现标志着 LLM 开发进入了“类型安全”的新阶段。它不仅简化了开发流程，更重要的是为 AI 应用带来了确定性和可维护性。结合 n1n.ai 提供的强大 API 聚合能力，开发者可以更加自信地构建出足以应对复杂业务挑战的智能体系统。

立即在 n1n.ai 获取免费 API 密钥，开启你的类型安全 AI 开发之旅。

参考来源：https://realpython.com/courses/building-type-safe-llm-agents-with-pydantic-ai/