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

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

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

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

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

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

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

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

这一步特别容易变脏：

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

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

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

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

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

代码语言：python

复制

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

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

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

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

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

代码语言：python

复制

from pydantic_ai import Agentagent = 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 结构化对象，差在这一张表：

维度	文本输出	结构化对象
程序解析	自己从文字抠	直接 result.output.name
字段缺失	静默出错	Pydantic 校验即报错
类型	全是字符串	list[str] 明确约束
模型编造	难防	禁止编造 校验兜底
切换模型	重写解析逻辑	改配置即可

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

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

代码语言：python

复制

import osmodel_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 能力做成真正的应用，必须考虑：输出结构是否稳定、字段是否可校验、错误能否被发现、模型是否方便切换。

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