Pydantic 工具类优化(校验器与 LangChain 工具集成)

一句话总结

一篇 DeepSeek 问答,解决一个常见工程问题:写基于 Pydantic 的工具类时,怎样做参数校验才不绕弯子? 核心答案:BaseModel 在 __init__ 时已自动校验过字段,别再在业务方法里重复实例化自己;要针对纯函数做校验就用 @validate_call,要针对字段做二次逻辑就用 @field_validator/@model_validator,要让 LangChain 温度有多高你多高就用 @tool(args_schema=...) 把这套校验能力接到 LLM 工具调用上。

什么时候需要读这篇

你在写 Agent 工具 / Function Calling 的 args_schema、纠结”校验器到底自动执行吗”、或问”到底用 BaseModel 还是 @validate_call”时,这篇给出可照抄的范式与选型表。


目录

  1. 反模式:在 invoke() 里重复实例化自己
  2. 三个正道:直接用 self / classmethod / staticmethod
  3. @validate_call:纯函数也能校验,无需 BaseModel
  4. field_validator / model_validator:字段级二次校验
  5. alias 与手写 mode=“before”:字段映射的取舍
  6. LangChain 工具集成的四种方式
  7. 面试/要点速查表

1. 反模式:在 invoke() 里重复实例化自己

原始代码的本意是”在调用前验证参数 a、b”,写法却踩了坑:

from pydantic import BaseModel, Field
 
class Add(BaseModel):
    """将两个数字相加"""
    a: int = Field(..., description="第一个数字")
    b: int = Field(..., description="第二个数字")
 
    def invoke(self, args):
        # ❌ 反模式:在实例方法里又 new 一个同类的新实例
        tool_instance = self.__class__(**args)  # 自动验证 a 和 b
        return tool_instance.a + tool_instance.b

三个问题:

问题说明
实例重复创建invoke 是实例方法,却用 self.__class__(**args) 建全新实例,完全无视已有的 self
校验时机冗余BaseModel 在 __init__ 时已经自动校验过字段,invoke 里再实例化一次纯属多余
无法访问实例属性既然已传参构造了 Add(a=3,b=5),直接算 self.a + self.b 就行

根因:把”校验这件事”重复做、绕路做。Pydantic 的校验入口是实例化本身,业务方法不该再承担一件事。


2. 三个正道:直接用 self / classmethod / staticmethod

方案一:直接用实例属性(推荐,最常用)

class Add(BaseModel):
    a: int = Field(..., description="第一个数字")
    b: int = Field(..., description="第二个数字")
 
    def invoke(self):          # 不再接收 args
        return self.a + self.b  # 直接使用 self 已校验的属性
 
add = Add(a=3, b=5)
result = add.invoke()          # 8

方案二:类方法模式(需要从 dict 创建实例时)

class Add(BaseModel):
    a: int = Field(..., description="第一个数字")
    b: int = Field(..., description="第二个数字")
 
    @classmethod
    def invoke_from_dict(cls, args: dict):
        instance = cls(**args)          # 在此实例化并自动校验
        return instance.a + instance.b
 
Add.invoke_from_dict({"a": 3, "b": 5})  # 8

方案三:静态方法模式(适合无状态工具)

class Add(BaseModel):
    a: int = Field(..., description="第一个数字")
    b: int = Field(..., description="第二个数字")
 
    @staticmethod
    def invoke(args: dict):
        validated = Add(**args)         # 手动校验一次
        return validated.a + validated.b

核心原则

用「创建/入口」换掉「方法内手动实例化」。 需要校验就靠 Pydantic 的构造/model_validate 入口一次完成,业务方法里不要重复 __class__(**args)。


3. @validate_call:纯函数也能校验,无需 BaseModel

如果只是给一个普通函数加参数校验和类型转换,根本不用继承 BaseModel —— 用装饰器 @validate_call:

from pydantic import validate_call
 
@validate_call
def add(a: int, b: int) -> int:
    """将两个数字相加"""
    return a + b
 
result = add(3, 5)          # 8
result2 = add("4", "6")     # 字符串 '4','6' 被自动转为 4,6
# add("wrong", 5)           # 抛 ValidationError
对比项BaseModel@validate_call
适用对象数据模型类纯函数/工具函数
校验时机__init__ / model_validate函数被调用时
额外复杂度要定义类结构一个装饰器即可
典型场景LangChain args_schema、字段关系校验简单函数参数校验

注意:validate_call 与 @field_validator/@model_validator 不是一回事——后者专用于 BaseModel 内部某个字段/整个模型的自定义校验;@validate_call 直接装饰任意函数。


4. field_validator / model_validator:字段级二次校验

Pydantic 提供的三段式校验:Field 约束 → @field_validator 单字段 → @model_validator 跨字段。

from pydantic import BaseModel, Field, field_validator, model_validator
 
class RegisterVo(BaseModel):
    username: str = Field(..., min_length=2, max_length=20, description="用户名")
    password: str = Field(..., min_length=6, max_length=20, description="密码")
    confirm_password: str = Field(..., description="确认密码")
 
    # 1. @field_validator:单字段二次逻辑(去空格、业务规则)
    @field_validator("username")
    @classmethod
    def username_must_valid(cls, v: str) -> str:
        cleaned = v.strip()
        if cleaned.isascii():
            if len(cleaned) < 3:
                raise ValueError("英文用户名至少需要 3 个字符")
        else:
            if len(cleaned) < 2:
                raise ValueError("中文用户名至少需要 2 个字符")
        return cleaned             # 返回值替换原值(实现去空格)
 
    # 2. @model_validator(mode="after"):跨字段一致性
    @model_validator(mode="after")
    def check_passwords_match(self):
        if self.password != self.confirm_password:
            raise ValueError("两次输入密码不一致")
        return self
 
RegisterVo(username="  alice ", password="abc123", confirm_password="abc123")

关键语法点

语法含义
@field_validator("username")指明校验哪个字段
必须叠加 @classmethod类方法,参数 v 是被校验字段的值
return cleaned返回值会替换原值(从而去掉首尾空格)
@model_validator(mode="after")整个模型构造完成后执行,可安全通过 self 访问所有已校验字段

mode=“before” / “after” 的时机差异

模式执行时机能访问的数据常见用途
before字段校验之前只有原始输入 dict(未校验)数据预处理、类型转换、字段重命名映射
after所有字段校验之后完整模型实例 self跨字段校验(如密码确认)、计算派生字段

装饰器顺序有讲究

# ✅ 正确:@field_validator 在上,@classmethod 在下
@field_validator("username")
@classmethod
def username_must_valid(cls, v): ...
 
# ❌ 报错:顺序反了
@classmethod
@field_validator("username")
def username_must_valid(cls, v): ...

原因:装饰器从下往上执行。@classmethod 在下 → 它先执行,把函数变成类方法;随后 @field_validator 收到的是类方法对象而非普通函数,Pydantic 无法正确注册校验器。

校验器是自动执行的吗?

完全自动,无需手动调用。 只要创建实例(User(...))或 model_validate({...}),所有 @field_validator/@model_validator 都会在对应时机自动触发,失败自动抛 ValidationError。

user = User(name="Alice", age=25)             # ✅ 自动触发全部校验器
user = User.model_validate({"name": "Bob", "age": 30})

5. alias 与手写 mode=“before”:字段映射的取舍

直觉正确的设计:alias 本质就是 Pydantic 在 mode="before" 阶段做的字段映射,只是官方封装成了声明式语法糖:

from pydantic import BaseModel, Field
 
class User(BaseModel):
    name: str = Field(..., alias="full_name")   # 声明别名
    age: int
 
user = User(full_name="Alice", age=25)
print(user.name)                    # Alice
print(user.model_dump())            # {'name': 'Alice', 'age': 25}

Pydantic 内部等价于手写的 mode="before" 预处理(简化伪代码):

@model_validator(mode="before")
@classmethod
def _apply_aliases(cls, data):
    for field_name, field_info in cls.model_fields.items():
        if field_info.alias and field_info.alias in data:
            data[field_name] = data.pop(field_info.alias)
    return data

alias vs 手写 pre_process 对比

对比项用 alias手写 pre_process
代码量一行声明写完整校验器逻辑
可读性高、语义清晰中,需阅读函数实现
维护性低维护,Pydantic 自动处理需自己维护映射逻辑
IDE 支持好,类型提示/自动补全一般,data 是 Any
灵活性仅字段映射任意预处理(类型转换、默认值、条件处理)

什么时候用哪种

用 alias(推荐,简单场景):

  • 简单字段名映射(full_name → name)
  • API 响应字段命名不一致(JSON 返回 user_id,模型用 userId)
  • 需要序列化控制(serialization_alias 控制输出名)
class User(BaseModel):
    user_id: int = Field(alias="id")   # 输入接受 id,输出为 user_id
    email: str
 
User(id=123, email="t@t.com").model_dump(by_alias=True)  # {'id': 123, 'email': '...'}

手写 mode="before"(复杂处理):

  • 复杂数据转换(时间字符串 → datetime)
  • 条件性字段映射(取决于某字段的值)
  • 数据清洗标准化(统一大小写、去空格)
  • 兼容多版本 API 字段(同时支持 full_name 和 fullName)

6. LangChain 工具集成的四种方式

Pydantic 类在这些场景统一以 args_schema(参数模式) 角色出现:告诉 LangChain / LLM 工具需要哪些参数、参数类型和描述;校验逻辑由 Pydantic 自动处理。

方式一:@tool(args_schema=PydanticClass)(最常用、标准组合)

from pydantic import BaseModel, Field
from langchain_core.tools import tool
 
class WeatherInput(BaseModel):
    location: str = Field(description="城市名,如 San Francisco, CA")
 
@tool(args_schema=WeatherInput)
def get_weather(location: str) -> str:
    """获取指定地点的当前天气"""
    return f"The weather in {location} is sunny."
 
get_weather.invoke({"location": "Beijing"})

方式二:直接实例化 StructuredTool.from_function()

from langchain_core.tools import StructuredTool
from pydantic import BaseModel, Field
 
class AddInput(BaseModel):
    a: int = Field(description="第一个数字")
    b: int = Field(description="第二个数字")
 
def add_func(a: int, b: int) -> int:
    return a + b
 
tool = StructuredTool.from_function(
    func=add_func, name="add", description="将两个数字相加",
    args_schema=AddInput,
)
tool.invoke({"a": 3, "b": 5})   # 8

方式三:继承 BaseTool(最灵活,支持状态与异步)

from langchain_core.tools import BaseTool
from typing import Type
 
class MultiplyInput(BaseModel):
    a: int
    b: int
 
class MultiplyTool(BaseTool):
    name: str = "multiply"
    description: str = "两个数字相乘"
    args_schema: Type[BaseModel] = MultiplyInput
 
    def _run(self, a: int, b: int) -> int:      # 同步
        return a * b
    async def _arun(self, a: int, b: int) -> int:  # 异步
        return a * b
 
MultiplyTool().invoke({"a": 4, "b": 3})          # 12

方式四:直接传给 ChatModel(bind_tools)

from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from pydantic import BaseModel, Field
 
class SearchInput(BaseModel):
    query: str = Field(description="搜索关键词")
 
model = ChatOpenAI()
model_with_tools = model.bind_tools([SearchInput])        # Pydantic 类可直接传,无需装饰器
response = model.invoke("搜索 LangChain", tools=[SearchInput])  # 底层 API

选型速查

使用场景推荐方式
简单工具、快速开发@tool(args_schema=PydanticClass)
需要自定义执行逻辑StructuredTool.from_function()
复杂工具、需要状态管理/异步继承 BaseTool(_run/_arun)
与 ChatModel 集成model.bind_tools([PydanticClass])

@tool 是”把普通函数变工具”的快捷方式,适合简单场景;继承 BaseTool 适合复杂工具(初始化配置如 API Key、管理状态、异步方法)。


7. 面试/要点速查表

问题答案
BaseModel 何时校验字段实例化时(__init__ 已内建),别再在业务方法里重复实例化
invoke 反模式self.__class__(**args) 新建实例,忽略 self、重复校验
纯函数要校验@validate_call,无需 BaseModel
field_validator 顺序@field_validator 在上、@classmethod 在下(装饰器自下而上执行)
before vs afterbefore=校验前看原始 dict;after=校验后访问 self
validator 自动执行吗是,构造/model_validate 自动触发,失败抛 ValidationError
alias 本质mode="before" 阶段做字段映射的声明式语法糖
alias vs 手写简单映射用 alias;复杂转换/条件/清洗用手写 before
LangChain 标准组合Pydantic类 + @tool(args_schema=...)
bind_tools 用 Pydantic?直接传 Pydantic 类即可,无需装饰器,作为 args_schema

相关笔记