Python
21 pydantic 数据建模
结构化输出与工具 schema 的基石(LangChain 必备)
- Python
- 进阶
目标:学会用「类 + 类型注解」声明数据结构,让 pydantic 自动完成校验、类型转换、序列化和 JSON Schema 生成——从此 LLM 吐回来的 JSON 字符串,一行代码变成安全可用的对象。 与 LangChain 的关系:LangChain 全家桶建立在 pydantic v2 之上。
PydanticOutputParser、with_structured_output、@tool的参数 schema,本质都是「把一个 pydantic 模型交给 LLM 当答题卡」。本章是通往 LangChain 最重要的一章。
前置:类型注解见 13-类型注解实战,装饰器见 14-函数进阶:lambda、高阶函数与装饰器。
1. 为什么需要:LLM 给你的是文字,程序要的是对象
LLM 的输出是一段文本。哪怕你要求它「输出 JSON」,拿到的也只是长得像 JSON 的字符串:
llm_output = '{"name": "小明", "age": "18", "email": null}'
程序要用它,先得 json.loads 变成 dict——但 dict 是不设防的。不用 pydantic,手写一个「安全拿到 age 整数」大概要这么多代码:
import json
data = json.loads(llm_output) # 第 1 步:字符串 → dict
if "name" not in data or not isinstance(data["name"], str):
raise ValueError("name 缺失或不是字符串") # 第 2 步:逐字段查缺失、查类型
age = data.get("age") # 第 3 步:age 是字符串 "18"!
if not isinstance(age, int): # isinstance("18", int) 是 False
if isinstance(age, str) and age.isdigit():
age = int(age) # 手动转换
else:
raise ValueError("age 无法转为整数")
if not 0 <= age <= 150: # 第 4 步:业务范围校验
raise ValueError("age 不在合理范围")
每一个字段都要重写一遍这套 if,嵌套结构(列表套对象)更是灾难。pydantic 的完整等价物只有声明:
from pydantic import BaseModel, Field
class Person(BaseModel):
name: str
age: int = Field(ge=0, le=150)
email: str | None = None
p = Person.model_validate_json(llm_output) # 从 LLM 的 JSON 字符串直接构造
print(p.age, type(p.age)) # → 18 <class 'int'>("18" 已自动转成 int)
声明一次结构,校验、转换、缺字段检查全部自动完成,失败抛统一格式的异常——「把数据的形状写成类,库负责把关」。
2. 第一个模型:类型注解就是校验规则
安装(LangChain 会自带,独立项目单独装):
python3 -m pip install "pydantic>=2"
继承 BaseModel 定义模型。pydantic 在类创建时读出所有带类型注解的字段(第 13 章:name: str 这行本身在纯 Python 里不强制任何事),接管 __init__:传入的每个值先校验、再转换成注解的类型,最后才存到实例上。
from pydantic import BaseModel
class Person(BaseModel):
name: str
age: int
email: str | None = None # 有默认值 → 可不传
p = Person(name="小明", age="25") # 故意传字符串
print(repr(p)) # → Person(name='小明', age=25, email=None)
print(p.age, type(p.age)) # → 25 <class 'int'>
四个行为都值得记住(均为实测):
- 宽松转换:能安全转 int 的字符串
"25"被自动转成int 25(int("25")的逻辑内建了);"25 岁"、"abc"转不动则抛错(第 5 节)。 - 自动
__repr__:repr(p)是Person(name='小明', age=25, email=None),print(p)更短、只列字段——都不用手写__repr__(对比第 09 章手写类的麻烦)。 - bool 最宽松:
"yes"、"on"、1、"true"都转成True;"no"得到False而不是报错。 - 多余字段默认被忽略:不报错,也不会存下来;要严格模式可设
model_config = ConfigDict(extra="forbid")(传入多余字段报extra_forbidden,ConfigDict见第 9 节)。
3. Field:给字段加默认值、约束和说明书
= 5 只能给不可变的默认值;Field(...) 是全功能版本,四个最常用的能力:
from pydantic import BaseModel, Field
class Product(BaseModel):
name: str = Field(min_length=1, max_length=50, description="商品名称,用于展示")
price: float = Field(gt=0, description="价格,单位元")
stock: int = Field(default=0, ge=0, description="库存数量")
tags: list[str] = Field(default_factory=list, description="标签列表")
| 能力 | 写法 | 效果 |
|---|---|---|
| 默认值 | default=0 或 = 0 | 不传时用默认值,该字段退出 required |
| 工厂默认值 | default_factory=list | 可变默认值的唯一正确写法(第 9 节) |
| 数值约束 | ge=0, le=150 / gt=0, lt=1 | 大于等于/小于等于/严格大于/严格小于 |
| 字符串约束 | min_length=1, max_length=50 | 长度限制(list 同样适用,约束元素个数) |
实测约束失败的样子(三个字段同时错,错误一次性全报,不是遇到第一个就停):
('name',) string_too_short String should have at least 1 character
('price',) greater_than Input should be greater than 0
('stock',) greater_than_equal Input should be greater than or equal to 0
description 是本章的灵魂参数:它不参与运行时校验,而是进入模型生成的 JSON Schema(第 6 节)——这是「写给 LLM 看的说明书」。约束(ge/le/min_length…)同样会进 schema:ge=0 变成 "minimum": 0。也就是说,你写在 Field 里的每个字,既约束校验、又会原样展示给模型。写清楚 description="问题答案的可信度评分,满分 100",LLM 返回的 confidence 才会落在 0~100;只写 int,模型可能还你 100% 这种字符串。
alias(概念级):Python 里 class、from 是关键字,不能当字段名;而外部数据(API、LLM)可能就叫这个名。Field(alias="class") 让「字段名(Python 侧)」与「数据键名(JSON 侧)」分离:输入按 alias 找,model_dump(by_alias=True) 输出时也还原成 alias。LangChain 里更常见的是反过来——用 docstring 或 Annotated 描述参数,第 10 节见。
4. 嵌套模型与容器:拼出任意复杂结构
字段类型可以是另一个模型、模型列表、模型字典——声明即递归校验:
from pydantic import BaseModel, Field
class Address(BaseModel):
city: str
street: str = Field(description="街道地址")
class Person(BaseModel):
name: str
address: Address # 模型套模型
friends: list[Address] = Field(default_factory=list) # 列表装模型
offices: dict[str, Address] = Field(default_factory=dict) # 字典装模型:键→子模型
phone: str | None = None # 可选字段
p = Person.model_validate({
"name": "小明",
"address": {"city": "北京", "street": "中关村大街1号"}, # 普通 dict
"friends": [{"city": "上海", "street": "南京东路100号"}],
"offices": {"hq": {"city": "深圳", "street": "科技园"}},
})
print(type(p.address), p.address.city)
# → <class '__main__.Address'> 北京 —— dict 已递归变成子模型实例,属性访问不用 p["address"]["city"]
print(p.offices["hq"].city) # → 深圳:每个值也都是 Address 实例
机制:model_validate(接受 dict 等对象)沿类型注解递归下降——address 注解是 Address,就把内层 dict 再交给 Address 校验构造;list[Address] 逐个元素处理;dict[str, Address] 逐个值处理(键仍要求是 str)。传 dict 进 Person(...) 构造器也走同样的路。
Optional[X] = None 的语义(LangChain 信息提取的防幻觉标配,第 10 节):X | None 只表示「默认值可以是 None」,即这个字段允许缺省;一旦传了值,仍按 X 校验。所以 age: int | None = None 的含义是「文本里提到年龄必须是 int,没提到就存 None」——而不是「什么都行」。缺了必填字段(如 address)会报 ('address',) missing。
5. 校验失败:ValidationError 精读
校验失败时 pydantic 收集所有错误再一次性抛出 ValidationError。先看完整报错文本:
ValidationError: 1 validation error for Person
age
Input should be a valid integer, unable to parse string as an integer
[type=int_parsing, input_value='不是数字', input_type=str]
结构:第 1 行是错误总数和模型名,随后每个错误一段——字段名、人话消息、type(错误分类,机器可读)、input_value(原始输入)。程序里不要解析这段文本,用 e.errors() 拿结构化列表,每项四个关键键:
from pydantic import BaseModel, ValidationError
class Person(BaseModel):
name: str
age: int
class Team(BaseModel):
name: str
members: list[Person] # 第 4 节:列表装模型,内层逐个校验
try:
Team.model_validate({
"name": "A队",
"members": [{"name": "小明", "age": 18},
{"name": 123, "age": "abc"}], # 第 2 个成员两个字段都错
})
except ValidationError as e:
for err in e.errors():
print(err["loc"], "|", err["type"], "|", err["input"])
('members', 1, 'name') | string_type | 123
('members', 1, 'age') | int_parsing | abc
loc是定位路径(元组):('members', 1, 'name')读作「members 的第 2 个(下标 1)元素的 name 字段」——嵌套再深也能精确指路,这是手写校验几乎做不到的。type是错误分类:missing(缺字段)、string_type/int_parsing(类型不对)、greater_than(越界)、value_error(自定义校验失败,第 7 节)……按 type 写分支处理,比匹配英文消息可靠。- 一个字段可以报多个错:
Union类型最典型——score: int | float传"abc",两个分支各报一个,loc为('score', 'int')与('score', 'float'),error_count()为 2。
上面例子的 except ValidationError as e + e.errors() 循环就是标准处理姿势(与第 18 章的异常分层思想一致):按 type 写分支决定「重试 / 报给用户 / 记日志」,或把 loc + msg 拼成文案喂回 LLM 让它自己修正——LangChain 的工具参数校验失败时回传给模型的正是这类信息(第 10 节用法三)。
6. 输出三件套:dump 与 JSON Schema
实例 → 数据,模型类 → 说明书,方向相反的三件事:
p.model_dump() # 实例 → dict(含嵌套 dict)
p.model_dump_json() # 实例 → JSON 字符串
Person.model_json_schema() # 模型类 → JSON Schema(注意是类方法,不需要实例)
前两个好理解(dump 即「倒出来」,是 pydantic v1 dict()/json() 的 v2 名字)。重头是第三个。JSON Schema 是描述 JSON 数据结构的通用标准(一个 JSON 对象,说明「什么数据算合法」),OpenAI/Anthropic 等所有 LLM 厂商的结构化输出接口都说这门语言。Product 的真实 schema 输出(实测,为排版重排了换行):
{'title': 'Product', 'type': 'object', 'required': ['name', 'price'],
'properties': {
'name': {'title': 'Name', 'type': 'string', 'description': '商品名称,用于展示',
'minLength': 1, 'maxLength': 50},
'price': {'title': 'Price', 'type': 'number', 'description': '价格,单位元',
'exclusiveMinimum': 0},
'stock': {'title': 'Stock', 'type': 'integer', 'description': '库存数量',
'default': 0, 'minimum': 0},
'tags': {'title': 'Tags', 'type': 'array', 'items': {'type': 'string'},
'description': '标签列表'}}
逐字段解读这张「数据身份证」:
- 整个模型:
type: 'object'(一个 JSON 对象),properties逐字段登记。 - 每个字段:Python 类型 → JSON 类型(
str→string、int→integer、float→number、list[str]→array+items);第 3 节的约束同步翻译(ge=0→minimum: 0、gt=0→exclusiveMinimum: 0、min_length→minLength);description原样进入。 required:没有默认值的字段(name、price)才进名单——这就是第 4 节int | None = None能防幻觉的机制:带默认值的字段不要求 LLM 必填,文本里没有就允许缺省。
一句话串起来:类型注解和 Field 是「源代码」,JSON Schema 是编译后的「通用答题卡格式」,LLM 按卡作答,答完的 JSON 再 model_validate_json 回到实例——这个闭环就是下一节所有 LangChain 用法的骨架。
7. 自定义校验:@field_validator
内置约束不够用时,用 @field_validator("字段名") 挂一个自己的函数(装饰器机制见第 14 章:函数被登记到该字段的校验链上,轮到这个字段时被调用)。完整例子:规范化手机号 + 拒绝未来日期:
from datetime import date
from pydantic import BaseModel, Field, field_validator
class Signup(BaseModel):
phone: str = Field(description="手机号,11 位数字")
birth: date = Field(description="出生日期,格式 YYYY-MM-DD")
@field_validator("phone")
@classmethod
def norm_phone(cls, v: str) -> str:
v = v.replace(" ", "").replace("-", "") # 先规范化:去空格和横线
if not (v.isdigit() and len(v) == 11):
raise ValueError("手机号必须是 11 位数字")
return v # 返回值才是存进实例的值
@field_validator("birth")
@classmethod
def no_future(cls, v: date) -> date:
if v > date.today():
raise ValueError("出生日期不能在未来")
return v
s = Signup(phone="138-0013 8000", birth="2000-01-01")
print(s.phone, s.birth) # → 13800138000 2000-01-01
print(type(s.birth)) # → <class 'datetime.date'>("2000-01-01" 自动转了)
四个机制要点:
- 校验顺序:先跑内置校验与转换,再跑你的 validator——
v拿到的birth已是date对象、phone已确认是 str,函数里不用再转。同一字段挂多个 validator 按声明顺序执行,第一个失败即短路(实测只报第一个错)。 - return 不可省:返回值替代原值存入实例。上面靠它顺手做了规范化(
138-0013 8000→13800138000),这是 validator 最实用的模式:先清洗、再检查、最后返回干净值。 - 抛
ValueError即校验失败:pydantic 捕获后包成type='value_error'的错误项,ctx里还留着原始异常。抛其他异常(如 RuntimeError)不会被包装,会直接炸穿。 @classmethod必写(v2 要求):函数第一个参数是类本身,惯例命名cls。
8. dataclass vs pydantic:何时用谁
标准库的 @dataclass(15-面向对象进阶 §8 已系统讲过:自动生成 __init__/__repr__ 的轻量数据类)与 pydantic 模型长得像,分工完全不同:
@dataclass | pydantic BaseModel | |
|---|---|---|
| 依赖 | 标准库,零依赖 | 第三方 |
| 类型注解 | 只当文档,不校验(age="abc" 照存) | 运行时强制校验 + 宽松转换 |
| 错误报告 | 无 | ValidationError,loc 定位,全量收集 |
| 序列化 | 无内置(asdict 简版) | model_dump / model_dump_json |
| JSON Schema | 无 | 一行生成,LLM 通用语言 |
判断标准一句话:纯内存里的临时结构(配置对象、中间计算结果)用 dataclass;凡是数据从「外面」进来——用户输入、API 响应、LLM 输出——或要「出去」(序列化、给 LLM),用 pydantic。LangChain 世界里几乎只有后者。
9. 常见坑
- 可变默认值:
tags: list[str] = []在类定义时就被拒绝,报PydanticUserError: A non-annotated attribute was detected: 'tags = []'——pydantic 把「所有实例共享同一个列表」这个经典 Python 坑防死了。修法:tags: list[str] = Field(default_factory=list)——每个新实例调用一次list()现造一个。 - 注解漏写或写成 Any:
tags = [](无注解)报同一个PydanticUserError。但data: Any = None合法——Any 等于放弃校验,[1, "混合", None]照单全收,见到Any字段要警惕:这里没有安全网。 - 赋值不校验:默认配置下,构造时把关、构造后洞开——
m.port = "hello"不报错,int 字段从此装着字符串(实测如此)。两个修法概念级:model_config = ConfigDict(frozen=True)让实例完全不可改(改了抛frozen_instance,顺带获得可哈希性,能放进 set / 当 dict 键);ConfigDict(validate_assignment=True)则让每次赋值也走校验。 - 字段名撞关键字:
from、class、id(常与内置函数撞)不能直接当字段名。惯例:尾下划线from_+Field(alias="from")(第 3 节),或换个不撞的名字。
10. 在 LangChain 里的样子:一份模型 = 一张答题卡
本章所有机制在 LangChain 里收敛成一个模式:把 pydantic 模型交给 LangChain → 它调 model_json_schema() 生成答题卡 → LLM 按卡作答 → 输出经校验回到模型实例。三处真实用法。
用法一:PydanticOutputParser(摘编自 ../langchain-book-python/03-输出解析器.md):
from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser
class AnswerWithConfidence(BaseModel):
answer: str = Field(description="用户问题的答案")
confidence: int = Field(description="问题答案的可信度评分,满分 100", ge=0, le=100)
parser = PydanticOutputParser(pydantic_object=AnswerWithConfidence)
# parser.get_format_instructions() 生成注入 prompt 的指令,内含第 6 节的 schema:
# {"confidence": {"description": "...满分 100", "maximum": 100, "minimum": 0, ...}}
逐行拆:Field(description=...) 是第 3 节「给 LLM 看的说明书」;ge=0, le=100 被翻译成 schema 里的 minimum/maximum;get_format_instructions() 把第 6 节的 model_json_schema() 输出连同正反例包成一段指令文本,注入 prompt;链尾的 parser 用 model_validate 校验模型输出,返回 res.answer、res.confidence 可直接访问的实例。
用法二:with_structured_output(摘编自 ../langchain-book-python/11-FunctionCalling.md 的嵌套信息提取):
class Person(BaseModel):
"""提取关于一个人的信息""" # docstring 也会进 schema,说明整个对象的语义
name: str = Field(description="人的名字")
age: int | None = Field(default=None, description="人的年龄") # 防幻觉
class Relation(BaseModel):
people: list[Person] = Field(description="提取所有人") # 第 4 节:列表装模型
relation: str = Field(description="人之间的关系, 尽量简洁")
extract_chain = prompt.pipe(ChatOpenAI(temperature=0).with_structured_output(Relation))
extract_chain.invoke({"input": "小明现在 18 岁了,她妈妈是小丽"})
# Relation(people=[Person(name='小明', age=18), Person(name='小丽')], relation='小丽是小明的妈妈')
小丽年龄未知 → 字段整体缺省(age: int | None = None 的第 4 节语义),而不是模型硬编一个数字——防幻觉是 schema 设计出来的。with_structured_output 直接传模型类,一行完成用法一的手动注入,1.x 的默认选择。
用法三:@tool 的参数模型(摘编自同章):
from typing import Literal
from pydantic import BaseModel, Field
class GetCurrentWeather(BaseModel):
location: str = Field(description="The city and state, e.g. San Francisco, CA")
unit: Literal["celsius", "fahrenheit"] = Field(description="The unit of temperature")
get_current_weather = tool(_get_current_weather, name="get_current_weather",
description="Get the current weather in a given location",
args_schema=GetCurrentWeather) # tool 来自 langchain.tools
args_schema 收一个 pydantic 模型:Literal 枚举进 schema 变成 enum 字段,LLM 只能二选一;参数校验失败的错误信息会回传给 LLM 让它修正重试——Agent(../langchain-book-python/12-Agent系统.md)的每个工具都是这个结构。回看三处用法,共用同一张答题卡的三个格子:字段名 = 题号,description = 题干,类型与约束 = 答题格式。会写 pydantic 模型,就会设计 LangChain 的结构化交互——更多对照见 22-读懂LangChain:语法桥。
小练习
- 定义
Book(BaseModel):title: str(1~100 字)、price: float(>0)、tags: list[str](默认空列表);传"59.9"给 price 验证自动转换。 - 定义嵌套模型
Order:items: list[Item](Item含name: str、price: float),故意让第 2 个 item 的 price 传字符串"abc",用e.errors()打印出 loc 定位路径。 - 给
Meeting(BaseModel)的start: date加校验:不能是过去的日子。传"2020-01-01"看错误,再传一个未来日期验证通过。 - 设计一个给 LLM 用的提取模型
BookReview:rating: int(1~5,description 写清「整数评分」)、comment: str | None(可选,防幻觉)、aspects: list[str];打印model_json_schema(),找到required里为什么没有comment。
练习答案
from datetime import date
from pydantic import BaseModel, Field, ValidationError, field_validator
# 练习 1
class Book(BaseModel):
title: str = Field(min_length=1, max_length=100)
price: float = Field(gt=0)
tags: list[str] = Field(default_factory=list)
b = Book(title="三体", price="59.9")
print(b.price, type(b.price)) # → 59.9 <class 'float'>
# 练习 2
class Item(BaseModel):
name: str
price: float
class Order(BaseModel):
items: list[Item]
try:
Order.model_validate({"items": [{"name": "A", "price": 9.9},
{"name": "B", "price": "abc"}]})
except ValidationError as e:
for err in e.errors():
print(err["loc"], err["type"]) # → ('items', 1, 'price') float_parsing
# 练习 3
class Meeting(BaseModel):
start: date
@field_validator("start")
@classmethod
def not_past(cls, v: date) -> date:
if v < date.today():
raise ValueError("会议不能安排在过去")
return v
# 练习 4
class BookReview(BaseModel):
rating: int = Field(ge=1, le=5, description="整数评分,1 最差 5 最好")
comment: str | None = Field(default=None, description="评论原文,没有则省略")
aspects: list[str] = Field(description="评论涉及的方面,如剧情、文笔")
# required 只有 ['rating', 'aspects']:comment 有默认值 None,不要求 LLM 必填——没有评论就不许编