← Voltar aos guias

Tool Use 与 Function Calling：7个常见坑及避坑指南

先分清：模型调用工具，不等于模型执行代码

Tool Use 和 Function Calling 都是在模型回复中声明“应该调用哪个工具以及传入什么参数”。真正执行函数的是你的服务器、Worker 或应用进程，执行结果再作为新消息发回模型。Claude 文档更常使用 Tool Use，OpenAI 生态常称 Function Calling，但核心流程基本一致：定义工具、发送请求、读取工具调用、校验并执行、回传工具结果、获取最终答案。

第一个常见误区是把工具描述写成普通提示词。仅在 system prompt 中说“需要天气时调用天气接口”，模型可能返回自然语言而不是结构化参数。应通过 SDK 的 tools 参数提交清晰的工具名称、用途、参数类型、必填字段和枚举值。

坑一：Schema 写得模糊，参数就会失控

工具 Schema 是模型和程序之间的契约。以 get_weather 为例，city 应声明为字符串，unit 应限制为 celsius 或 fahrenheit，并明确 city 不能为空。不要使用“参数可以随便传”这类描述，也不要把所有字段都设成可选后再期待模型自行补全。

• 限定类型：金额使用 number，数量使用 integer，布尔开关使用 boolean。
• 限定范围：用 enum 限制状态、地区或单位，必要时写明长度和格式。
• 控制必填项：把执行接口真正需要的字段放入 required。
• 服务端复核：即使 Schema 校验通过，也要再次检查权限、用户归属和业务边界。

坑二：只处理最终文本，忽略 tool call

模型第一次响应可能没有可展示的文本，而是返回一个或多个工具调用。程序应先判断响应中是否存在 tool call，再读取名称和 arguments。arguments 仍然是不可信输入，必须解析 JSON，捕获解析异常，并验证字段。不要直接把模型给出的字符串拼接进 SQL、Shell 或文件路径。

推荐的实际流程是：收到调用后按名称查找白名单函数；解析并校验参数；执行有超时和权限限制的函数；记录调用日志；最后用原始的调用标识关联结果。若模型提供 tool_call_id，回传时必须使用对应标识，否则模型可能无法把结果对应到正确的调用。

坑三：消息顺序和角色不符合协议

一次完整对话通常包含用户消息、模型的 tool call 消息、工具结果消息，以及模型根据结果生成的最终回复。不要删除中间的调用消息，也不要把工具结果伪装成 user 消息。不同 SDK 的字段名称略有差异，接入 Claude、GPT 或兼容接口时，应以目标模型的协议和 SDK 类型定义为准。

如果一次响应包含多个调用，不要假设它们只有一个。可以先检查每个工具是否互不依赖，再并发执行；有依赖关系的调用则按顺序执行。并发时要设置总超时、单任务超时和失败处理策略。

坑四：把工具调用当成可信的业务授权

模型可以建议“退款”“发邮件”或“删除数据”，但不能因此获得真实权限。高风险操作应增加用户确认、权限校验、幂等键和审计日志。对于支付、账户修改等动作，最好先调用只读查询工具，再让用户确认最终参数，避免模型根据模糊上下文直接执行不可逆操作。

坑五：失败后无限重试，成本和副作用一起放大

工具可能超时、返回空数据或触发限流。为每个工具定义统一错误结构，例如错误类型、可重试标记和面向模型的简短说明。网络超时可以有限次数重试，但退款、下单等副作用操作必须使用幂等键，避免重复执行。对模型本身也设置最大工具轮数，防止调用循环。

坑六：只看模型价格，不算完整调用成本

工具定义、历史消息和工具返回内容都会占用上下文。把数据库原始结果全部回传，既浪费 Token，也可能泄露隐私。应在工具层完成筛选、分页和字段裁剪，只返回模型做决策所需的信息。生产环境还应记录输入 Token、输出 Token、工具耗时和失败率。

用 59API 低成本验证 Claude 与 GPT 工具链

如果你需要同时测试 Claude Opus、Sonnet、Haiku、Fable 以及 GPT 模型，可以使用 59API 的按量付费中转服务。它提供原生官方质量模型，不做降级，API Base URL 为 https://api.59api.com，并兼容 OpenAI SDK、Claude Code 和 Codex。开发阶段可用同一套工具 Schema 对比不同模型的调用准确率、轮数和 Token 成本；相比固定套餐，按量方式更适合小流量验证和分阶段上线。注册 59API 后即可开始测试，符合条件的用户还可通过推荐返利进一步降低费用。

上线前的检查清单

• 工具名称唯一、描述明确，参数 Schema 与真实接口一致。
• 服务端完成类型、权限、范围和敏感字段校验。
• 正确保存调用消息，并用对应 ID 回传工具结果。
• 处理零个、一个和多个并行工具调用。
• 为超时、限流、重复执行和模型循环设置边界。
• 记录 Token、耗时、错误和工具审计日志。

把模型视为负责规划的组件，把执行、授权和校验牢牢放在你的应用中，Tool Use 和 Function Calling 才能从演示功能变成可靠的生产能力。