函数工具与参数 Schema
用 JSON Schema 描述函数输入，使模型能生成可验证的结构化参数。
学习目标
- 能说明函数工具与参数 Schema解决什么问题，以及何时适用。
- 能解释为什么“description 模糊”是误区。
学习前需要掌握
背景与问题
工具参数如果只是自由文字，程序很难稳定区分路径、数量与可选条件。函数工具用结构化接口告诉模型可提交哪些字段，再由应用将合法请求交给实际函数实现。
Schema 能提前发现一部分结构错误，但它不认识业务世界：类型正确的路径可能越界，合法整数也可能超过额度。因此结构约束与执行前验证必须分层。
概念定义
函数工具是由名称、描述、输入参数 Schema 和执行实现构成的工具接口。
直观理解
它像一份机器可读表单：字段、类型、枚举和必填项都明确。
核心原理
名称与描述应说明函数用途、何时适用和返回什么。参数 Schema 则定义对象、字段类型、必填项与额外属性；嵌套对象也要按实际接口约束，避免模型插入执行器没有处理的字段。
下方示例使用 OpenAI 的 strict 函数模式：对象声明不接收额外属性，定义的字段列入 required；允许缺省语义的值用可包含 null 的类型表达。这里“字段必须出现”与“值不能为 null”是两件事。
执行器先做结构验证，再做语义验证。例如 max_chars 为整数并不代表负数有意义，path 为字符串并不代表它在授权根目录内；默认值、范围和资源权限仍需由实现明确处理。
返回值也应有稳定契约，区分内容、截断标记和失败原因。工具描述和 Schema 的修改相当于接口变化，调用者与实现要一起更新，并检查旧调用是否仍能正确处理。
案例：一份笔记读取请求的三层检查
按下方 Schema，参数可以是路径为 notes/agent.md、max_chars 为 null 的对象；实现可以约定 null 使用默认长度。但遗漏 max_chars 或多出未声明字段，在严格结构约束下应被拒绝。
即使路径与类型都合法，notes/../private.md 仍需要解析后检查是否越过允许目录。max_chars 为负数也需要业务范围校验。最后，读取成功返回的内容是否支持用户问题，还属于任务验收层；这三层不能互相代替。
理解与实践步骤
- 定义名称和使用描述
- 编写 JSON Schema
- 开启严格模式
- 解析模型参数
- 执行语义与权限校验
- 调用函数并返回结构化结果
代码实现
示例 1
严格函数工具的参数 Schema
example_01.py用途：展示 OpenAI 当前文档推荐的 strict JSON Schema 约束；仅作静态示例。
{
"type": "function",
"name": "read_note",
"description": "读取允许目录中的一份 Markdown 笔记",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string"},
"max_chars": {"type": ["integer", "null"]}
},
"required": ["path", "max_chars"],
"additionalProperties": false
}
}代码解析
解析始终位于完整代码下方，并按实际代码段逐项对应。
输入数据与任务
展示 OpenAI 当前文档推荐的 strict JSON Schema 约束；仅作静态示例。
Step 1 · 1–15 行
type 和 name 标识函数工具。
{
"type": "function",
"name": "read_note",
"description": "读取允许目录中的一份 Markdown 笔记",
"strict": true,
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string"},
"max_chars": {"type": ["integer", "null"]}
},
"required": ["path", "max_chars"],
"additionalProperties": false
}
}预期输出或运行结果
模型工具调用参数只能包含 path 与 max_chars；结构不合法时应拒绝执行。
常见错误 · 3 条
- 描述过于模糊，多个函数用途重叠，模型无法判断什么时候选哪一个。
- 在本页严格模式示例中只删除 required 字段来表达可选性，或忘记关闭额外属性。
- 把结构验证当作资源授权、数值范围检查或最终结果正确性的证明。
实际应用
- API 适配
- 结构化查询
- 本地函数调用
常见错误
- 描述过于模糊，多个函数用途重叠，模型无法判断什么时候选哪一个。
- 在本页严格模式示例中只删除 required 字段来表达可选性，或忘记关闭额外属性。
- 把结构验证当作资源授权、数值范围检查或最终结果正确性的证明。
输入、输出与执行边界
输入
- JSON Schema
- 模型生成参数
输出
- 验证后的参数或结构化错误
能力
- API 适配
- 结构化查询
- 本地函数调用
安全风险与信任边界
符合 JSON Schema 只证明参数结构满足约束，不证明收款人、路径或金额在业务上正确。函数返回的文本也可能包含外部指令，应作为数据解析；会改变外部状态的函数还需区分提交成功、结果未知与明确失败。
性能与失败模式
调用耗时通常包括模型选函数、参数校验、执行和结果回传，失败重试会扩大尾部延迟。测试应分别检查选函数是否正确、参数语义是否正确与最终结果是否达成；存在依赖的函数不能只为降延迟而并行。
推荐学习资料
OpenAI Tools Guide
说明模型如何调用函数、搜索、计算机操作及其他工具，并展示结构化参数。
OpenAI · OpenAI Platform