Pydantic-AI输出约束技术深度剖析

引言

与大型语言模型（LLM）交互时，一个核心的挑战在于如何确保其输出的稳定性和格式一致性。尽管 LLM 在自然语言理解和生成方面表现出色，但其输出的非确定性常常导致下游应用程序难以处理。开发者们尝试了各种提示工程（Prompt Engineering）技巧，但效果并不稳定。

pydantic-ai 是一个旨在解决此问题的 Python 库，它通过深度整合 Pydantic 的数据验证和模式（Schema）生成能力，为 LLM 的输出提供了一套强大而可靠的结构化约束机制。本文将深入剖析 pydantic-ai 的内部实现，揭示其如何将 Python 类型定义转化为对 LLM 输出的精确控制。

核心设计思想：万物皆工具（Everything as a Tool）

pydantic-ai 最核心的设计思想是将期望的结构化输出抽象为一种特殊的、必须调用的“工具”。它没有将输出结构仅仅作为提示信息的一部分，而是利用了现代 LLM（如 GPT-4、Gemini）强大的工具调用（Tool Calling）或函数调用（Function Calling）API。

这种设计的优势在于：

1. 统一的抽象层：无论是执行外部 API 调用（例如查询天气），还是格式化最终的答案，其底层逻辑都被统一为“工具使用”，大大简化了 Agent 的内部状态管理。

2. 利用模型原生能力：它直接利用了模型厂商为工具调用所做的深度优化，这比简单的文本解析更为可靠和高效。

3. 强制性与可靠性：通过 API 参数，pydantic-ai 可以强制模型必须调用指定的输出工具，从而从根本上保证了返回数据的结构，避免了模型返回普通文本或其他无关内容。

实现流程深度剖析

下面，我们将以一个 Agent 的完整生命周期为例，分步解析其技术实现。

当用户创建一个 Agent 实例并指定 output_type 时，一系列的初始化工作便开始了。

from pydantic import BaseModelfrom pydantic_ai import Agentclass CityLocation(BaseModel):    city: str    country: str# 初始化 Agent 并指定输出类型agent = Agent('google:gemini-1.5-flash', output_type=CityLocation) 

1. Agent.__init__: 在 agent.py 中，Agent 的构造函数接收 output_type 参数。它立即调用 _output.OutputSchema.build() 方法，将 CityLocation 这个 Python 类型转化为内部表示。

2. OutputSchema.build(): 这个位于 _output.py 的类方法是模式转换的起点。它会为 CityLocation 类型创建一个 OutputTool 实例。这个 OutputTool 内部包含一个 OutputObjectSchema。

3. 生成 JSON Schema: OutputObjectSchema 的核心职责是利用 Pydantic 的 TypeAdapter 对 CityLocation 进行自省，并生成一份完全兼容的 JSON Schema。这份 Schema 详细描述了 city 和 country 字段及其类型，它将作为与 LLM 沟通的“技术合同”。同时，它还会创建一个 Pydantic SchemaValidator，用于后续的数据验证。

当 agent.run_sync() 被调用时，pydantic-ai 会根据目标模型（如 Google Gemini）的 API 规范，将上一步生成的通用 JSON Schema 包装成特定格式。

1. 特定于模型的转换: 在 models/google.py 中，GoogleModel 类在其 _generate_content 方法中调用 _get_tools。此方法会将 OutputTool 转换为 Google API 所要求的 FunctionDeclarationDict 格式，其中包含了工具的名称、描述以及最重要的 parameters（即第一步生成的 JSON Schema）。

2. 强制工具调用: 这是确保结构化输出的关键。GoogleModel 调用 _get_tool_config 方法，生成一个 ToolConfigDict。通过将 mode 设置为 ANY 并提供允许的函数名，它指示 Google API 必须调用这个工具，从而排除了模型返回非结构化文本的可能性。

LLM 执行后，会返回一个包含工具调用结果的响应。

1. 解析响应: GoogleModel._process_response 方法解析来自 Google API 的响应，提取出 function_call 部分，并将其封装成一个通用的 ToolCallPart 消息。

2. 数据验证与实例化: 在 _agent_graph.py 的驱动下，这个 ToolCallPart 被传递给 OutputTool.process 方法。该方法进而调用 OutputObjectSchema.process，并使用在初始化时创建的 SchemaValidator 来验证 LLM 返回的参数。如果验证通过，LLM 提供的 JSON 数据就会被成功实例化为一个 CityLocation Python 对象。如果验证失败，则会触发重试机制。

高级特性与鲁棒性设计

多模式输出 (Sequence/Union): output_type 支持接收一个类型列表（如 [Flight, Hotel]）。pydantic-ai 会为每个类型创建独立的 OutputTool，让 LLM 根据上下文选择最合适的一个进行“调用”，实现了动态输出格式。

函数即模式 (output_type=function): 用户可以直接传入一个带有类型注解和文档字符串的 Python 函数。_function_schema.py 模块会对函数进行自省，自动生成对应的 JSON Schema，这遵循了 DRY（Don't Repeat Yourself）原则，极为便利。

当 Pydantic 验证失败并抛出 ValidationError 时，pydantic-ai 不会立即失败。

它会捕获该错误，并将其中的详细信息（如哪个字段缺失或类型错误）包装成一个 RetryPromptPart 消息。

这个包含修正指令的消息会被添加到对话历史中，并重新发送给 LLM。

LLM 看到自己的错误和修正建议后，有很大几率在下一次尝试中生成正确的数据。这个“请求 → 验证 → 失败 → 修正 → 重试”的闭环大大增强了系统的鲁棒性。

所有这些复杂的交互流程由 _agent_graph.py 中的一个内部图状态机进行调度。它定义了 UserPromptNode（接收输入）、ModelRequestNode（调用模型）、CallToolsNode（处理工具调用）和 End（结束）等状态节点。这个状态机确保了无论对话进行多少轮、工具被调用多少次、重试发生多少回，整个流程始终清晰、有序且可控。

结论

pydantic-ai 通过将结构化输出巧妙地抽象为一种强制性的工具调用，并深度整合 Pydantic 的模式生成与验证能力，实现了一套极为可靠的 LLM 输出约束机制。其设计不仅优雅地统一了多种交互逻辑，还通过闭环重试和精巧的状态机管理保证了系统的鲁棒性。这种从“提示”到“编程”的范式转变，使得构建可预测、生产级别的 AI 应用成为可能。

原文始发于微信公众号（赛博攻防悟道）：Pydantic-AI输出约束技术深度剖析