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”时,这篇给出可照抄的范式与选型表。
目录
- 反模式:在 invoke() 里重复实例化自己
- 三个正道:直接用 self / classmethod / staticmethod
- @validate_call:纯函数也能校验,无需 BaseModel
- field_validator / model_validator:字段级二次校验
- alias 与手写 mode=“before”:字段映射的取舍
- LangChain 工具集成的四种方式
- 面试/要点速查表
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 dataalias 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 after | before=校验前看原始 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 |
相关笔记
- 源文件:打开交互图(已归档至 00_附件)
- Agent 结构化输出与工具调用(Function Calling / Tool Use / MCP / 校验) — Function Calling + Pydantic 的完整防御链(本篇是其中校验器细则的展开)
- LangChain Loop Engineering 四层架构 — LangChain 工程化架构
- 在Agent中落地ReAct模式(Reasoning + Acting) — 工具调用在 Agent 循环中的应用
- AI 大模型 MOC — 领域内容地图