Pydantic AI：在 Python 中构建类型安全的 LLM 智能体

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

大语言模型（LLM）编排框架的领域正在发生深刻变革。早期的框架（如 LangChain）主要关注提示词链（Prompt Chaining），而现代生产环境则对可靠性、可观测性以及最重要的“类型安全”提出了更高要求。Pydantic AI 应运而生，它是一个专门为弥合 LLM 的非确定性输出与企业级 Python 应用的严谨要求而设计的框架。通过结合 Pydantic V2 的强大功能，该框架允许开发者将 LLM 的输出视为经过验证的 Python 对象，而不是不可预测的字符串。

在本教程中，我们将探讨如何构建健壮的智能体（Agents），并利用 Claude 3.5 Sonnet、DeepSeek-V3 和 OpenAI o3 等尖端模型。为了通过统一、高速的接口访问这些模型，许多开发者选择使用 n1n.ai，它为所有主流 LLM 供应商提供了一个统一的 API 网关。

为什么选择 Pydantic AI？

传统的 LLM 交互往往会导致“字符串解析地狱”，开发者必须编写复杂的正则表达式或 JSON 加载逻辑来处理模型响应。Pydantic AI 通过在框架层强制执行 Schema 验证解决了这一问题。如果模型返回的字段不符合定义的 BaseModel，框架会自动触发重试机制，并根据验证错误信息要求模型修正其错误。

核心优势对比

特性Pydantic AILangChainLlamaIndex
核心焦点类型安全智能体生态系统集成数据索引/RAG
验证机制原生 Pydantic V2手动/部分支持部分支持
依赖注入内置支持较弱较弱
学习曲线低（熟悉 FastAPI 者秒上手）高中等
性能优化极简开销插件较多，开销大专注于向量库

环境配置与安装

要开始构建，你需要 Python 3.9+ 环境以及 LLM 供应商的访问权限。虽然你可以安装特定供应商的 SDK，但在生产环境中使用 n1n.ai 这样的统一聚合器是更明智的选择，这能确保在高并发下的故障转移和更低的延迟。

# 安装核心框架和常用供应商支持
pip install pydantic-ai

如果你通过 n1n.ai 访问 DeepSeek-V3 或 GPT-4o，你可以直接配置 OpenAI 兼容的 Base URL，从而极大地简化你的技术栈。

构建你的第一个类型安全智能体

Pydantic AI 的核心是 Agent 类。与普通的 API 包装器不同，它是关于结果类型（Result Type）和依赖类型（Dependency Type）的泛型实现。

from pydantic import BaseModel
from pydantic_ai import Agent

# 定义期望的结构化输出
class InventoryCheck(BaseModel):
    product_id: str
    in_stock: bool
    price: float
    estimated_delivery: str

# 定义一个必须返回 InventoryCheck 对象的智能体
agent = Agent(
    'openai:gpt-4o',
    result_type=InventoryCheck,
    system_prompt='你是一名物流助手。请准确提取产品详情。'
)

# 运行智能体
result = agent.run_sync("商品 SKU-99 还有货吗？它的价格是 45 美元，预计 2 天送达。")
print(result.data.product_id)  # 输出: SKU-99
print(type(result.data))       # 输出: <class '__main__.InventoryCheck'>

高级特性：依赖注入（Dependency Injection）

Pydantic AI 最强大的功能之一是其状态管理方案。它没有使用全局变量或复杂的上下文管理器，而是采用了一套类型安全的依赖注入系统。这对于测试以及在运行时为智能体提供数据库连接或外部 API 密钥至关重要。

from dataclasses import dataclass
from pydantic_ai import RunContext

@dataclass
class MyDeps:
    db_connection: str
    api_key: str

# 指定 deps_type
agent_with_deps = Agent('anthropic:claude-3-5-sonnet', deps_type=MyDeps)

@agent_with_deps.tool
def get_user_balance(ctx: RunContext[MyDeps], user_id: str) -> str:
    # 安全地访问注入的依赖项
    return f"用户 {user_id} 在数据库 {ctx.deps.db_connection} 中的余额为 $500"

验证重试机制（Validation Retries）

LLM 并非完美无缺。有时它们会产生幻觉或遗漏必填字段。Pydantic AI 通过 retries 参数优雅地处理了这一问题。当验证失败时，框架会将错误消息推回给 LLM，并明确告知哪里出错了，要求其重新生成符合格式的数据。

专家提示： 虽然重试提高了可靠性，但也会增加 Token 消耗。建议使用提供透明计费和详细日志的供应商来监控成本，例如 n1n.ai 的管理控制台。

结构化输出性能基准

并非所有模型处理结构化输出的能力都相同。根据最新的技术基准：

  1. OpenAI o3 / GPT-4o: 在遵循严格 JSON Schema 方面表现卓越，适合复杂逻辑。
  2. Claude 3.5 Sonnet: 在复杂的工具调用（Tool Calling）场景中可靠性极高。
  3. DeepSeek-V3: 对于大规模结构化数据提取任务，性价比极高，是成本敏感型项目的首选。

生产环境实施策略

  1. 定义 Schema：从清晰的 Pydantic BaseModel 开始。尽量避免过深的嵌套结构，因为 LLM 在处理多层递归时可能会出现理解偏差。
  2. 系统提示词优化：明确单位和格式要求（例如：“价格必须始终保留两位小数”）。
  3. 工具说明（Docstrings）：Pydantic AI 会利用函数的 Docstrings 来向 LLM 解释工具的用途。务必编写清晰、简洁的文档注释。
  4. 可观测性：利用 Logfire（与 Pydantic AI 深度集成）来追踪智能体逻辑的每一步，这对于调试复杂的依赖注入问题非常有帮助。

总结

Pydantic AI 代表了 Python 开发者在使用 LLM 时的重大进步。通过将类型提示和验证的严谨性引入 AI 领域，它使得构建的智能体不仅聪明，而且可预测、易维护。无论你是在构建简单的聊天机器人，还是复杂的 RAG（检索增强生成）流水线，Pydantic AI 配合 n1n.ai 这样强大的 API 聚合器，都能为现代 AI 应用提供坚实的基础。

在 n1n.ai 获取免费 API 密钥。

参考来源：https://realpython.com/pydantic-ai/