AI-Wiki

核心定义

Pydantic是Python生态下的第三方开源数据处理库，依托Python类型注解特性实现自动化数据校验与建模，可替代大量手写的校验逻辑，是Web开发、大模型应用开发场景的核心工具库。

核心功能

数据格式校验：自动匹配模型定义的类型注解规则，校验输入数据是否符合要求，不符合时自动抛出结构化错误信息，无需手动编写大量if判断逻辑
数据类型自动转换：自动对可兼容的类型做安全转换，例如将字符串格式的数字"123"自动转为int类型123、将符合格式的字符串日期自动转为datetime对象，减少手动类型转换代码
类字段元数据配置：支持为每个类字段自定义元信息，统一管理字段的校验规则、描述、别名、默认值等属性

核心组件

Field方法

Field是Pydantic的核心字段配置工具，专门用于为类字段配置元数据，常用配置项包括：

default：字段的默认值，未传入该参数时自动填充
alias：字段的别名，支持输入参数使用别名映射到类内部的字段名，例如接口传入model_path可自动映射到类字段model_folder_path
验证规则：内置支持min_length（最小长度）、max_length（最大长度）、gt（大于）、lt（小于）等通用校验规则
description：字段的描述信息，可被自动提取用于生成接口文档

示例代码：

from pydantic import BaseModel, Field
from typing import Optional

class ModelConfig(BaseModel):
    model_folder_path: Optional[str] = Field(
        default=None, 
        alias="model_path", 
        description="模型存储的文件夹路径", 
        min_length=5
    )

@field_validator装饰器

@field_validator是Python装饰器的一种，用于绑定指定类字段实现自定义校验逻辑，Pydantic会自动将绑定字段的实际值传入修饰方法的value参数，无需手动传参。

示例代码：

from pydantic import BaseModel, field_validator

class PromptConfig(BaseModel):
    input_variables: list[str]

    @field_validator("input_variables")
    def check_input_not_empty(cls, value):
        if len(value) == 0:
            raise ValueError("输入变量列表不能为空")
        return value

适用场景

接口参数校验：常配合FastAPI使用，自动校验HTTP请求的参数合法性，不符合要求时自动返回标准化错误响应
配置类定义：用于项目的全局配置类，自动校验配置项是否符合规则，避免配置错误导致的运行异常
大模型输出结构化校验：是LangChain结构化输出解析器的核心依赖，可强制大模型的返回内容符合指定的字段格式，避免非结构化输出导致的解析错误
数据模型定义：用于定义接口响应模型、ORM映射模型等，统一项目内的数据结构标准

注意事项

Pydantic分为v1和v2两个主流版本，v2版本核心校验逻辑用Rust重写，性能相比v1提升5~10倍，两者部分语法存在差异，迁移时需要注意适配
所有校验逻辑依托Python类型注解实现，定义模型时必须为字段指定明确的类型注解才能生效
配合Optional类型（来自Python内置typing模块）可定义允许为None的字段，Optional[str]等价于Union[str, None]，表示字段可传入字符串或者Null值

Pydantic