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

在 LLM（大语言模型）开发领域，从简单的提示词工程（Prompt Engineering）向成熟的软件工程转型，其核心标志在于对可靠性、可维护性和可预测性的追求。早期的 AI 应用大多依赖于原始文本的交互，但现代企业级智能体（Agents）需要结构化的数据和严格的类型安全。这正是 Pydantic AI 大显身手的地方。由广受欢迎的 Pydantic 库团队开发，Pydantic AI 提供了一个专门设计的框架，旨在利用 Python 的类型提示（Type Hinting）系统构建生产级的智能体。为了充分发挥这些智能体的潜力，开发者通常会将其与高性能的基础设施集成，例如 n1n.ai，它提供了对 Claude 3.5 Sonnet 和 DeepSeek-V3 等顶尖模型的统一高速访问。

核心理念：为什么类型安全至关重要？

在标准的 LLM 交互中，模型返回的是字符串。如果你需要该字符串作为一个表示客户记录的 JSON 对象，通常必须编写复杂的正则表达式或使用脆弱的解析逻辑。如果 LLM 漏掉了一个逗号或写错了键名，你的应用程序就会崩溃。

类型安全通过确保流经系统的数据符合预定义的模式（Schema）来解决这个问题。Pydantic AI 使用 Python 类来定义这些模式。当智能体运行时，框架会强制 LLM 输出符合类结构的数据。如果输出无效，框架会自动触发“验证重试循环”（Validation Retry Loop），根据收到的具体验证错误要求 LLM 自行修正。这种架构模式显著减少了运行时错误，使 AI 的行为更像是一个确定性的软件组件。

Pydantic AI 的关键组件

1. Agent 类

该库的核心是 Agent 类。它封装了模型逻辑、系统提示词以及预期的返回类型。与通用的封装器不同，Pydantic AI 的智能体在结果类型上是泛型的，这意味着你的 IDE 和静态分析工具（如 mypy 或 pyright）能够准确知道智能体返回的对象结构。

2. 使用 result_type 的结构化输出

通过定义 result_type，你可以精确地告诉智能体你想要什么。例如，如果你正在构建一个提取航班信息的工具，你会定义一个 FlightInfo Pydantic 模型。智能体随后将使用函数调用（Function Calling）或专门的提示词技术，确保 LLM 返回一个有效的 FlightInfo 实例。

3. 依赖注入与 RunContext

Pydantic AI 最强大的特性之一是其状态管理方法。通过 RunContext，你可以将外部依赖（如数据库连接、API 客户端或用户偏好）直接注入到工具和逻辑中。与在其他框架中常见的全局状态模式相比，这使得测试和模块化变得更加容易。在处理复杂的生产环境时，通过 n1n.ai 接入稳定的 API 接口，可以确保依赖注入后的逻辑执行更加顺畅。

实现指南：创建一个类型安全的智能体

以下是一个用于分析代码质量的类型安全智能体的概念实现。对于希望获得最低延迟和最高吞吐量来驱动这些智能体的开发者，强烈建议使用 n1n.ai 提供的 API 网关。

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
from typing import List

# 定义结构化输出模型
class CodeReview(BaseModel):
    score: int = Field(description="评分，范围 1 到 10")
    issues: List[str] = Field(description="识别出的 Bug 或代码异味列表")
    fix_suggestion: str

# 定义依赖项
class ReviewDeps:
    def __init__(self, api_key: str):
        self.api_key = api_key

# 初始化智能体
review_agent = Agent(
    'openai:gpt-4o',
    deps_type=ReviewDeps,
    result_type=CodeReview,
    system_prompt="你是一位资深的专家工程师。请审查提供的代码片段。"
)

@review_agent.tool
def check_security_vulnerabilities(ctx: RunContext[ReviewDeps], code: str) -> str:
    # 此处模拟调用安全扫描 API
    return "未发现重大安全漏洞。"

# 运行智能体
# result = review_agent.run_sync("def add(a, b): return a + b", deps=ReviewDeps(api_key="..."))
# print(result.data.score)

框架对比：Pydantic AI vs. LangChain vs. CrewAI

进阶模式：生产环境中的验证重试

当 LLM 未能通过验证检查（例如，缺少字段或值越界）时，Pydantic AI 不仅仅是抛出异常。它会执行“验证重试”。它将错误信息发回给 LLM：“你之前的响应未通过验证，错误信息为：[error]。请重试。”

这对于可靠性至关重要的生产环境至关重要。然而，重试会增加延迟和成本。为了缓解这一问题，开发者应使用具有高推理能力的模型。像 n1n.ai 这样的平台允许你在不同模型之间轻松切换，以找到推理准确性与成本效率之间的完美平衡。例如，在初次尝试时使用较小的模型，如果触发重试，则通过 n1n.ai 路由到更强大的模型如 GPT-4o 或 Claude 3.5。

知识测验：测试你的理解程度

为了巩固你的知识，请考虑在构建 Pydantic AI 应用时遇到的这些常见场景：

1. 如果 LLM 在多次重试后仍无法满足 result_type 会发生什么？ 库最终会抛出 ValidationError。最佳实践是将智能体调用包装在 try-except 块中，以优雅地处理这些边缘情况。

2. Pydantic AI 能处理流式结构化数据吗？ 是的，它支持流式结构化输出，允许你在整个 JSON 对象生成完毕之前，就开始处理模型输出的前几个字段。这对于提升用户体验（降低首字延迟）非常有效。

3. RunContext 如何提高可测试性？ 通过上下文注入依赖项，你可以在单元测试期间轻松地将真实的数据库连接替换为模拟对象（Mocks），而无需更改智能体的内部逻辑。这意味着你可以测试智能体的决策流程，而无需产生真实的 API 消耗或数据库副作用。

总结

Pydantic AI 代表了 AI 开发专业化进程中的重要一步。通过将 LLM 视为具有严格签名的函数，它允许开发者构建像传统软件一样可靠的复杂智能体。无论你是在构建 RAG 系统、编码助手还是自主智能体，专注于类型安全都将为你节省无数的调试时间。其核心优势在于将 Python 社区成熟的类型校验工具直接引入 AI 原生开发中，降低了系统性风险。

为了获得最佳性能并访问驱动 Pydantic AI 智能体的最新模型，请在 n1n.ai 获取免费 API 密钥。