定义 tool 参数后, 不引入其他库, 仅用 Pydantic 自动生成符合 OpenAI 规范的 Tool Schema. 想法很简单, 把 Pydantic 的 model_json_schema 生成的 JSON Schema 处理成 OpenAI 规范即可.
好处是 (1) 不用引入或依赖其他乱七八糟的库; (2) 不用手动额外维护一套工具描述; (3) 能利用 Pydantic 的一些功能, 从 JSON string load 之后自动校验参数, 自动转换类型等.
基础示例
比如
class GetWeatherArgs(BaseModel):
"""Retrieves current weather for the given location."""
location: str = Field(description="City and country e.g. Bogotá, Colombia")
units: Literal["celsius", "fahrenheit"] = Field(description="Units the temperature will be returned in.")
def get_weather(args: GetWeatherArgs):
"""实际的工具处理逻辑"""
pass
get_weather_tool = create_tool_from_pydantic(GetWeatherArgs)
print(json.dumps(get_weather_tool, ensure_ascii=False, indent=2))
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Retrieves current weather for the given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia"
},
"units": {
"type": "string",
"description": "Units the temperature will be returned in.",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"units"
]
}
}
}
完整代码
import datetime
import json
import re
import textwrap
from enum import StrEnum
from typing import Type, Literal, Optional, List, Any
import pydantic
from pydantic import BaseModel, Field
def _clean_text(text: str) -> str:
"""清理多行字符串的缩进和行尾空格。"""
return textwrap.dedent(text).strip()
def _process_property(prop_schema: dict, defs: dict) -> dict:
"""递归地处理单个属性的 Schema，将其转换为 Tool 参数格式。"""
# 1. 处理 Optional[T]，在 Pydantic v2 中表现为 anyOf 包含 'null'
if 'anyOf' in prop_schema:
# 找到非 null 的那个 schema 定义
non_null_schema = next((s for s in prop_schema['anyOf'] if s.get('type') != 'null'), None)
if non_null_schema:
# 递归处理，但保留外层的 description
processed_schema = _process_property(non_null_schema, defs)
if 'description' in prop_schema:
processed_schema['description'] = _clean_text(prop_schema['description'])
return processed_schema
else: # 理论上不应该只有 null
return {}
# 2. 处理嵌套对象 ($ref)
if '$ref' in prop_schema:
ref_name = prop_schema['$ref'].split('/')[-1]
nested_schema = defs.get(ref_name)
if nested_schema:
# 对于嵌套对象，我们再次调用主转换函数
return pydantic_to_tool_schema(nested_schema, defs)
# 3. 处理基本类型和数组
result = {}
prop_type = prop_schema.get('type')
if prop_type:
result['type'] = prop_type
if 'description' in prop_schema:
result['description'] = _clean_text(prop_schema['description'])
if 'enum' in prop_schema:
result['enum'] = prop_schema['enum']
# 3a. 处理数组 (List[T])
if prop_type == 'array' and 'items' in prop_schema:
# 递归处理数组元素的类型
result['items'] = _process_property(prop_schema['items'], defs)
return result
def pydantic_to_tool_schema(schema: dict, defs: dict = None) -> dict:
"""将 Pydantic 的 JSON Schema 转换为 Tool 的 parameters 部分。"""
if defs is None:
defs = schema.get('$defs', {})
tool_params = {
"type": "object",
"properties": {},
"required": schema.get("required", []),
}
# 顶层描述 (来自类的 docstring)
if 'description' in schema:
tool_params['description'] = _clean_text(schema['description'])
properties = schema.get("properties", {})
for name, prop_schema in properties.items():
tool_params["properties"][name] = _process_property(prop_schema, defs)
return tool_params
def create_tool_from_pydantic(pydantic_model: Type[BaseModel]) -> dict:
"""
根据 Pydantic 模型自动创建一个符合 OpenAI 规范的 Tool 定义。
- 自动从模型类名推断函数名 (例如 GetWeatherArgs -> get_weather)。
- 自动使用模型的 docstring 作为工具的描述。
"""
# 1. 从模型类名推断函数名
model_name = pydantic_model.__name__
class_name = model_name.removesuffix('Args')
# 将驼峰命名 (CamelCase) 转换为下划线命名 (snake_case)
function_name = re.sub(r'(?<!^)(?=[A-Z])', '_', class_name).lower()
# 2. 生成 Pydantic Schema 并转换为 Tool Schema
pydantic_schema = pydantic_model.model_json_schema()
tool_schema = pydantic_to_tool_schema(pydantic_schema)
description = tool_schema.pop("description", "") # 描述移动到外层
# 3. 构建并返回完整的 Tool 定义
return {
"type": "function",
"function": {
"name": function_name,
"description": description,
"parameters": tool_schema,
},
}
class GetWeatherArgs(BaseModel):
"""Retrieves current weather for the given location."""
location: str = Field(description="City and country e.g. Bogotá, Colombia")
units: Literal["celsius", "fahrenheit"] = Field(description="Units the temperature will be returned in.")
def get_weather(args: GetWeatherArgs):
"""实际的工具处理逻辑"""
pass
get_weather_tool = create_tool_from_pydantic(GetWeatherArgs)
print(json.dumps(get_weather_tool, ensure_ascii=False, indent=2))
复杂点的例子
可以定义嵌套模型, 枚举类型, 添加自定义校验逻辑等. 下面的 SearchFilesArgs 模型演示了如何处理文件搜索场景, 它包含了对文件类型 (FileType 枚举) 和创建时间 (嵌套的 TimeRange 模型) 的筛选.
我们还定义了一个 LLMProofBaseModel 基类, 能自动处理来自 LLM 的 'null' 字符串输入. 嵌套的 TimeRange 模型中的校验器 check_dates 也展示了如何在数据模型层面封装业务规则.
# --- 接上一段代码 ---
class LLMProofBaseModel(BaseModel):
"""自动将所有字段中值为字符串 'null' 的输入转换为 None"""
@pydantic.field_validator('*', mode='before')
@classmethod
def _clean_null_str(cls, v: Any) -> Any:
if isinstance(v, str) and v.lower() == 'null':
return None
return v
class TimeRange(LLMProofBaseModel):
"""这个 docstring 不会用到"""
start_date: Optional[datetime.date] = Field(None, description="开始日期 (YYYY-MM-DD)")
end_date: Optional[datetime.date] = Field(None, description="结束日期 (YYYY-MM-DD)")
random_field: Optional[str] = Field(None, description='演示用')
@pydantic.model_validator(mode='after')
def check_dates(self) -> 'TimeRange':
if self.start_date and self.end_date and self.start_date > self.end_date:
# 抛出错误或者其他处理方式
self.end_date = self.start_date
return self
class FileType(StrEnum):
PDF = "pdf"
PPT = "ppt"
class SearchFilesArgs(LLMProofBaseModel):
"""
搜索文件
多行示例
- xx
- yy
"""
query: str = Field(description="根据用户问题提炼出的核心搜索查询语句")
file_types: Optional[List[Literal[*FileType]]] = Field(None, description="文件类型")
time_range: Optional[TimeRange] = Field(None, description="文件创建时间范围")
search_file_tool = create_tool_from_pydantic(SearchFilesArgs)
tools = [
get_weather_tool,
search_file_tool,
]
print(json.dumps(tools, ensure_ascii=False, indent=2))
args1 = GetWeatherArgs.model_validate({"location": "Bogotá, Colombia", "units": "celsius"})
args2 = SearchFilesArgs.model_validate(
{
"query": "年报", "file_types": ["pdf"],
"time_range": {"start_date": "2025-01-01", "end_date": "2024-01-01", "random_field": "null"},
}
)
[
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Retrieves current weather for the given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia"
},
"units": {
"type": "string",
"description": "Units the temperature will be returned in.",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"location",
"units"
]
}
}
},
{
"type": "function",
"function": {
"name": "search_files",
"description": "搜索文件\n\n多行示例\n- xx\n- yy",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "根据用户问题提炼出的核心搜索查询语句"
},
"file_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"pdf",
"ppt"
]
},
"description": "文件类型"
},
"time_range": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "开始日期 (YYYY-MM-DD)"
},
"end_date": {
"type": "string",
"description": "结束日期 (YYYY-MM-DD)"
},
"random_field": {
"type": "string",
"description": "演示用"
}
},
"required": [],
"description": "文件创建时间范围"
}
},
"required": [
"query"
]
}
}
}
]