让大模型不再是"聊天框"：用 PydanticAI 把输出变成可校验的 Python 对象

上个月我给团队搭了个小工具：把一堆散落的简历自动塞进人才库。第一版我图省事，直接让大模型把信息"总结"成一段文字，再让下游代码去抠字段。

上线第一天就出了三个 bug。

这让我第一次认真想一个问题：AI 应用进入工程阶段后，核心不是让模型说得更漂亮，而是让它的输出能被程序稳定接住。

PydanticAI 解决的正是这个——它不是另一个"更会聊天的 Agent 框架"，而是让大模型的输出从自然语言文本，变成可校验、可复用的 Python 对象。

一、先说痛点：让大模型返回文本，等于让同事用嘴汇报数据

你让模型从简历里抽关键信息，它返回得很漂亮：

李明是一位资深数据工程师，熟悉 Python、Spark、Flink 和 LangChain。

人读着没问题。但下一步你要把姓名写进数据库、把技能列表传给岗位匹配接口、把背景展示在前端——你拿到的只是一段自然语言，得自己从文字里把字段重新抠出来。

这一步特别容易变脏：

• 字段可能漏掉。模型心情好就给你省了背景。
• JSON 格式不稳定。多一个逗号下游就炸。
• 技能变成一整句话。本该是列表，它给你写成"精通 Python 与 Spark 等"。
• 模型可能编造。原文根本没有 LangChain，它自己加戏。
• 代码不知道信谁。解析出来了，你却不敢往库里写。

说白了，让大模型直接吐文本再让程序去解析，就像让同事看完简历用嘴给你汇报，你再凭记忆记笔记——总会漏、会错、还会加戏。

结构化输出，就是给这个同事一张固定格式的 Excel 模板：姓名一格、技能一格，填错格式他交不进来。

二、Pydantic：第一层地基，也是一份业务契约

PydanticAI 建立在 Pydantic 之上。第一步不是写 Agent，而是定义你想要的形状：

from pydantic import BaseModel, Field

class ResumeSummary(BaseModel):
    name: str = Field(description="候选人姓名")
	    summary: str = Field(description="一句话总结候选人的核心背景")
    skills: list[str] = Field(min_length=1, description="从简历中抽取出的技能")

这里的关键不在于定义了三个字段，而是定义了一份业务契约：它告诉大模型和所有调用方，输出必须按这个规矩来——name 是字符串、skills 是列表且不能为空、错了或不齐都不行。

Pydantic 模型不只是"定义字段"，它是在给数据立规矩。

三、PydanticAI 的 Agent：把模型和契约焊在一起

定义好契约后，连接发生在 Agent 这一层：

from pydantic_ai import Agent

agent = Agent(
    model="deepseek:deepseek-chat",
    output_type=ResumeSummary,
    instructions=(
        "你是一个简历结构化助手。"
        "严格从简历原文抽取信息，禁止编造内容。"
        "提取姓名、一句话职业背景总结、技能清单。"
    ),
)

result = agent.run_sync(resume_text)
print(result.output.name)      # 李明
print(result.output.skills)    # ['Python', 'Spark', 'Flink', 'LangChain']

最关键的就一行：output_type=ResumeSummary。

这行代码干的事，和给函数声明返回类型一模一样——你不是在说"返回一段字"，而是在说"返回的是一个 ResumeSummary 形状的东西"。模型一旦不照这个形状来，Pydantic 立刻在校验阶段报错，而不是等你的下游代码崩了才发现。

拿到结果后，它是一个标准 Pydantic 实例，直接 .model_dump() 转字典、.model_dump_json() 转 JSON、塞数据库，全程不用再解析文本。

文本输出 vs 结构化对象，差在这一张表：

四、模型切换：把供应商变成配置项

PydanticAI 另一个爽点是用字符串切模型，格式统一是 provider:model-name：

import os
model_name = os.getenv("MODEL_NAME", "deepseek:deepseek-chat")

# .env 里控制到底用谁
# MODEL_NAME=deepseek:deepseek-chat
# DEEPSEEK_API_KEY=你的 Key

# 换成 OpenAI？只改 .env，业务代码一行不动
# MODEL_NAME=openai:gpt-5-mini
# OPENAI_API_KEY=你的 Key

deepseek:deepseek-chat、openai:gpt-5-mini、anthropic:claude-sonnet-4-6、google:gemini-3-flash-preview——模型供应商从写死的业务代码，变成了配置文件里的一行。这点和把数据库密码放进 .env 是同一个思路：供应商是基础设施，不该污染你的逻辑。

总结

回头看，PydanticAI 解决的不是"怎么让模型更聪明"，而是一个更工程化的问题：

好的 AI 应用，不是让模型说得更漂亮，而是让它说得"程序听得懂"。

如果要把 AI 能力做成真正的应用，必须考虑：输出结构是否稳定、字段是否可校验、错误能否被发现、模型是否方便切换。

PydanticAI 让大模型不再只是一个聊天接口，而是变成 Python 工程里一个有输入、有输出、有类型约束的可靠组件。