大模型应用开发 / 系统课时
定义工具接口
定义工具接口
模型只有在准确理解工具用途、参数含义和调用边界后,才能稳定连接外部系统。本课将把一个普通函数整理成清晰的工具定义,并用参数模式阻止缺字段、错类型和无效取值。
学习目标
- 为工具选择明确且不歧义的名称与说明
- 使用 JSON Schema 描述必填参数、类型和约束
- 在执行前验证模型生成的工具参数
工具接口包含什么
一个工具接口通常由三部分组成:名称、说明和参数模式。名称用于唯一识别能力,说明告诉模型“何时调用”,参数模式则规定“如何调用”。这三部分必须共同表达业务边界,不能只写一个函数名让模型猜测用途。
工具应保持单一职责。例如查询天气和发送通知应拆成两个工具;get_data 这类名称过于宽泛,而 get_order_status 能直接说明动作和对象。说明中还应写清不适用场景,例如“仅查询订单,不执行退款”。
用参数模式消除歧义
参数模式推荐采用 JSON Schema。字段说明应解释业务含义,而不只是重复字段名;可枚举的值用 enum 限制;必要字段放入 required;默认不接受额外字段,避免模型附带未定义参数。
{
"type": "object",
"properties": {
"orderNo": {
"type": "string",
"description": "需要查询的商户订单号,不能为空"
},
"detailLevel": {
"type": "string",
"enum": ["basic", "full"],
"description": "basic 返回状态,full 额外返回支付与退款明细"
}
},
"required": ["orderNo"],
"additionalProperties": false
}该模式的生效行为是:缺少 orderNo、传入枚举外的值或增加未知字段时,参数验证应失败。Schema 只负责描述输入,鉴权、限流、幂等和敏感字段脱敏仍由工具执行层负责。
定义并验证一个完整工具
下面使用 Python 字典定义工具,并实现最小参数校验。示例不依赖第三方库,可以直接运行;真实项目可替换为标准 JSON Schema 校验器。
from typing import Any
ORDER_STATUS_TOOL = {
"name": "get_order_status",
"description": "查询指定商户订单的当前状态;只读,不执行退款或状态修改。",
"parameters": {
"type": "object",
"properties": {
"orderNo": {
"type": "string",
"description": "商户订单号"
},
"detailLevel": {
"type": "string",
"enum": ["basic", "full"],
"description": "返回信息详细程度"
}
},
"required": ["orderNo"],
"additionalProperties": False
}
}
def validate_arguments(arguments: dict[str, Any]) -> None:
allowed = {"orderNo", "detailLevel"}
unknown = set(arguments) - allowed
if unknown:
raise ValueError(f"存在未知参数:{sorted(unknown)}")
order_no = arguments.get("orderNo")
if not isinstance(order_no, str) or not order_no.strip():
raise ValueError("orderNo 必须是非空字符串")
detail_level = arguments.get("detailLevel", "basic")
if detail_level not in {"basic", "full"}:
raise ValueError("detailLevel 只能是 basic 或 full")
def execute_tool(arguments: dict[str, Any]) -> dict[str, str]:
validate_arguments(arguments)
return {
"orderNo": arguments["orderNo"],
"status": "PAID",
"detailLevel": arguments.get("detailLevel", "basic")
}
result = execute_tool({
"orderNo": "MER202608020001",
"detailLevel": "full"
})
print(result)预期输出
{'orderNo': 'MER202608020001', 'status': 'PAID', 'detailLevel': 'full'}示例中的订单号和状态仅用于演示接口形状。接入真实系统后,execute_tool 应调用受鉴权保护的服务,并把超时、权限不足和业务不存在转换为稳定的错误结构。
写好说明与边界
工具说明要回答三个问题:何时调用、调用后得到什么、哪些事情不能做。不要把内部实现细节全部塞入说明,也不要写“用于处理订单”这种无法帮助模型选择工具的描述。
参数字段应尽量使用业务上稳定的值。日期要规定格式和时区,金额要规定单位,标识符要说明来源。对于删除、付款、退款等有副作用的工具,还应增加确认参数或在执行层要求人工确认,不能因为模型给出了合法 JSON 就直接执行。
本课总结
- 工具名称和说明负责帮助模型选对能力,参数模式负责约束调用方式
- 必填、枚举和
additionalProperties能显著减少无效参数 - Schema 校验通过不等于业务安全,执行层仍需鉴权、确认和错误处理
下一课预告
下一课将介绍模型如何选择工具、生成调用参数,并把工具执行结果继续交给模型组织最终回答。