大模型应用开发 / 系统课时
实现单次工具调用
实现单次工具调用
学习目标
完成本课后,你将能够:
- 理解工具调用中模型与程序的职责边界
- 定义函数名称、说明和参数 Schema
- 读取模型返回的
tool_calls并验证参数- 执行工具后把结果回传给模型
工具调用不是模型直接执行代码
工具调用分为两部分:
- 模型根据问题选择工具并生成参数。
- 应用验证参数、执行真实函数,再把结果返回模型。
模型不能自动获得操作系统、数据库或网络权限。权限始终由承载工具的应用控制。
调用链路
text
用户问题
→ 模型返回 tool_calls
→ 应用验证函数名和参数
→ 应用执行函数
→ 追加 tool 结果消息
→ 模型生成最终回答即使只调用一次工具,也需要完整回传工具结果,不能把模型生成的参数当作最终答案。
Python 完整示例
保存为 single_tool_call.py:
python
from typing import Any
from ollama import chat
MODEL = "<TOOL_CAPABLE_MODEL>"
def get_temperature(city: str) -> dict[str, Any]:
allowed = {
"吉隆坡": 31,
"上海": 28,
}
if city not in allowed:
return {"ok": False, "error": "unsupported_city"}
return {"ok": True, "city": city, "temperature_c": allowed[city]}
tools = [
{
"type": "function",
"function": {
"name": "get_temperature",
"description": "查询示例城市的当前演示温度。",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"enum": ["吉隆坡", "上海"],
}
},
"required": ["city"],
"additionalProperties": False,
},
},
}
]
messages = [
{
"role": "user",
"content": "吉隆坡的演示温度是多少?",
}
]
first = chat(
model=MODEL,
messages=messages,
tools=tools,
options={"temperature": 0},
)
messages.append(first["message"])
tool_calls = first["message"].get("tool_calls", [])
if len(tool_calls) != 1:
raise SystemExit(f"期望 1 个工具调用,实际为 {len(tool_calls)}")
call = tool_calls[0]
function = call["function"]
if function["name"] != "get_temperature":
raise SystemExit(f"不允许的工具: {function['name']}")
arguments = function.get("arguments", {})
city = arguments.get("city")
if city not in {"吉隆坡", "上海"}:
raise SystemExit(f"不允许的城市: {city!r}")
result = get_temperature(city)
messages.append(
{
"role": "tool",
"tool_name": "get_temperature",
"content": str(result),
}
)
final = chat(
model=MODEL,
messages=messages,
tools=tools,
options={"temperature": 0},
)
print(final["message"]["content"].strip())运行前将 <TOOL_CAPABLE_MODEL> 替换为本地已下载且支持工具调用的模型。运行:
bash
python single_tool_call.py预期输出结构:
text
<RESPONSE_CONTAINING_31_CELSIUS>示例温度来自本地固定字典,不代表真实天气。
工具定义的设计
工具说明要清晰但不能过度宽泛:
- 名称使用稳定动词短语。
- 描述说明何时调用。
- 参数使用 JSON Schema。
- 能用枚举时使用枚举。
- 禁止额外字段。
- 区分必填与可选。
- 不把密钥或内部权限放入描述。
工具过多时,模型更容易选错,应按当前任务动态提供需要的工具集合。
参数验证
模型参数必须当作不可信输入。至少验证:
- 函数名是否白名单
- 必填字段
- 字段类型
- 数值范围
- 字符串长度
- 枚举值
- 文件路径
- URL 和网络目标
- 用户权限
- 重复调用与幂等性
不能直接使用 eval、动态导入或任意 shell 执行模型参数。
工具结果格式
工具结果应尽量返回结构化、精简、可验证的数据。例如:
json
{
"ok": true,
"city": "吉隆坡",
"temperature_c": 31
}错误也应结构化:
json
{
"ok": false,
"error": "unsupported_city"
}不要把完整数据库异常堆栈或密钥返回给模型。
是否允许自动执行
低风险只读工具可以在校验后自动执行。涉及以下操作时应增加用户确认或审批:
- 删除文件
- 转账与支付
- 发送邮件
- 修改生产数据
- 发布内容
- 执行系统命令
- 访问敏感客户信息
模型负责建议动作,业务系统负责授权和审计。
本课练习
练习 1:定义只读工具
任务目标:练习参数 Schema。输入或初始条件:选择汇率、库存或内部字典查询。实现要求:定义工具并验证参数。验收条件:模型不能传入 Schema 之外字段。
练习 2:模拟非法参数
任务目标:测试安全校验。输入或初始条件:手工构造越界参数。实现要求:让应用在执行前拒绝。验收条件:真实函数没有被调用。
练习 3:设计审批规则
任务目标:区分低风险与高风险工具。输入或初始条件:列出 6 个业务工具。实现要求:为每个工具定义自动执行或人工确认。验收条件:依据包含权限、可逆性和影响范围。
按自己的节奏,确认真正理解。