跳转到主要内容

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 模型长得像,分工完全不同:

@dataclasspydantic 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:语法桥。

小练习

  1. 定义 Book(BaseModel):title: str(1~100 字)、price: float(>0)、tags: list[str](默认空列表);传 "59.9" 给 price 验证自动转换。
  2. 定义嵌套模型 Order:items: list[Item](Item 含 name: str、price: float),故意让第 2 个 item 的 price 传字符串 "abc",用 e.errors() 打印出 loc 定位路径。
  3. 给 Meeting(BaseModel) 的 start: date 加校验:不能是过去的日子。传 "2020-01-01" 看错误,再传一个未来日期验证通过。
  4. 设计一个给 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 必填——没有评论就不许编