大模型应用开发 / 系统课时

实现单次工具调用

实现单次工具调用

学习目标

完成本课后,你将能够:

  • 理解工具调用中模型与程序的职责边界
  • 定义函数名称、说明和参数 Schema
  • 读取模型返回的 tool_calls 并验证参数
  • 执行工具后把结果回传给模型

工具调用不是模型直接执行代码

工具调用分为两部分:

  1. 模型根据问题选择工具并生成参数。
  2. 应用验证参数、执行真实函数,再把结果返回模型。

模型不能自动获得操作系统、数据库或网络权限。权限始终由承载工具的应用控制。

调用链路

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 个业务工具。实现要求:为每个工具定义自动执行或人工确认。验收条件:依据包含权限、可逆性和影响范围。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现单次工具调用

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通