函数调用与工具使用常见问题

编辑部发布 2026-06-26 更新 2026-06-27 12 分钟阅读 2,376 字

当你满怀信心地让大模型去调用外部 API、查询数据库或执行一段代码，结果却只收到格式错乱的 JSON、模型固执地拒绝使用某个工具、或者陷入无休止的重复调用时——请放心，你并不孤单。这些问题，几乎是每个认真使用大模型功能的人都会遇到的“成人礼”。

本文将深入剖析函数调用与工具使用中的常见死穴，提供一套标准化的排查流程、典型错误对照表以及从实践中提炼出的避坑建议，帮你从焦虑到从容，快速定位并根除问题。

核心要诀

函数调用与工具使用的所有痛点，都可以归结为三个环节的脱节：

定义阶段：你写的函数“说明书”（Schema）没能让模型看懂。
解析阶段：模型写的“手术申请书”（function_call 参数）格式不对，让你没法执行。
执行阶段：你把手术结果（工具返回）递回给模型，模型却无法理解，甚至因此“宕机”。

破解这些问题的关键，不在于堆砌更长的提示词，而在于：严格遵守模型的原生规范、在工具侧做好错误边界处理，并在系统提示中清晰说明工具的使用规则和限制。

开始前的自我检查

在开始漫长的排查之前，请先确认以下三个前提条件已经满足。这将避免你误入歧途，浪费大量时间在无关问题上。

确认模型原生支持：确保你使用的模型（如 Claude 3、GPT-4、Gemini 等）原生支持 Function Calling，而不是通过文本模拟。如果模型版本较旧（例如 gpt-3.5-turbo-0301），你可能需要手动添加特定参数来启用此功能，并确认 API 版本已更新。
确认参数已正确传递：检查你的 API 调用是否显式传入了 tools 或 functions 参数。尤其注意 tool_choice 字段是否被错误地设置为 "none"（这会强制模型忽略所有工具）。默认情况下，模型会自行判断是否需要调用工具；如果你希望每次都强制调用，可以设置为 "required"。
确认函数定义规范：你的 JSON Schema 定义是否严格遵守了模型供应商（如 OpenAI / Anthropic）的规范？一个常见的陷阱是：properties 中包含了 "additionalProperties": false，这会导致部分模型直接拒绝解析。同时，description 应清晰说明参数的接收范围和默认行为，而不仅仅是描述字段名称。

标准化排查流程

按图索骥，效率最高。请按照以下步骤，从最高概率的问题开始，逐一排查。

1. 检查函数定义的“完整性”

最常见的问题往往源于函数定义本身那些细微的、被忽视的错误。这导致模型即便有心调用，也无力生成合法参数。

类型字段必须具体而准确：type: "string" 固然没问题，但如果参数期望是固定枚举值，务必添加 enum: ["value1", "value2"]。如果参数可以为空（例如可选参数），显式标注 nullable: true，永远不要指望模型自行推断。
必填字段必须宣告：一个参数必须出现在 required 数组中，模型才会将其视为“必填”。否则，模型会自动忽略它，而不是“推荐填写”。
描述要包含“使用说明书”：想象一下，你要教一个聪明的、但毫无常识的实习生使用一个工具。例如，对于“金额”这个字段，描述写成 “单位为分，最低 50，不可为负数” 远比 “交易金额” 有效得多。它能极大地减少模型生成非法或不合理参数的概率。

2. 验证模型返回的“手术申请书”

当模型决定调用工具时，它会返回一个结构化的请求。你需要检查这份“申请书”是否格式正确，可以执行。

检查关键字段：在 API 返回的原始 JSON 中，重点核对以下内容：

{
  "finish_reason": "function_call",
  "message": {
    "function_call": {
      "name": "get_weather",
      "arguments": "{\"location\": \"Beijing\"}"
    }
  }
}

常见错误分析：
- 如果 arguments 字段缺失，通常是函数定义中某个参数的类型定义错误，比如把 integer 错误地写成了 int（JSON Schema 中无 int 类型）。
- 如果 arguments 是无效的 JSON（例如缺少逗号、多了一个逗号），这可能意味着函数 Schema 中存在歧义或描述不清的字段，导致模型生成了非标准输出。一个实用的策略是：在解析 arguments 时，用 JSON.parse() 包裹在 try/catch 块中。一旦解析失败，不抛出错误，而是主动将该次调用标记为“失败”，并让模型根据失败信息重试。

3. 检查工具执行与结果回传的“闭环”

工具执行完毕并反馈结果给模型，是隐藏问题最多的环节。这个“闭环”一旦中断，模型的行为就会变得不可预测。

结果返回格式必须一致且结构清晰：如果工具返回的是纯文本而非 JSON，或者 JSON 中的字段名与函数定义中的参数名不匹配，模型可能无法正确解读结果。理想情况下，工具应该返回一个结构化的、清晰的 JSON 对象。
异常处理至关重要：当 API 超时、数据库连接失败时，不要直接抛出异常或返回空字符串。务必给模型返回一个包含错误信息的结构化反馈，例如：
```
{"error": true, "message": "查询超时，请稍后重试"}
```
这给了模型“下台阶”的机会，它可以根据错误信息调整策略或直接告知用户。
警惕“死亡循环”：当工具 A 的返回结果恰好满足了工具 B 的执行条件，而 B 的执行结果又再次触发 A 时，模型就可能陷入无限循环。解决方法是在系统提示中明确声明循环上限，例如：“如果你已经连续调用了同一个工具（或同一组工具）3次仍未解决问题，请告知用户‘我遇到了技术困难，无法完成’，并提供当前所能获得的所有信息。”

避坑检查清单

以下四个细节是最容易让人“抓狂”的陷阱，建议在排查问题时逐一核对。

函数名合规吗？ 函数名是否包含了大写字母或下划线 (_) 以外的符号？多数模型要求函数名只能由字母、数字、下划线和点号 (.) 组成，且长度不超过 64 个字符。
参数名冲突了吗？ 参数名是否与 JSON Schema 的保留关键字（如 name, type, required）冲突？虽然这些是顶级关键词，但作为参数名时需要确保它们被正确地嵌套在 properties 对象中，避免产生歧义。
工具结果记入“历史”了吗？ 工具执行的结果是否被正确地追加到了 messages 数组中？模型无法“凭空”知道工具调用了、执行了、得到了什么结果。如果不更新对话上下文，模型每次都是“重头开始”，自然可能重复调用。
max_tokens 够用吗？ 当函数定义很长，且返回结果也很长时，如果 max_tokens 设置得过小，模型可能在生成最终的文本回复或下一个 function_call 之前就被截断。一个被截断的 function_call 通常是无效的。

常见问题速查

模型拒绝调用任何工具

现象：即使提示词明确要求，模型也坚持用纯文本回复。
排查路径：
1. 立即检查 tool_choice 参数是否被误设为 "none"。
2. 审视函数 description 是否过于模糊？尝试在描述中加入明确的触发条件，例如：“当用户询问某地的当前天气时，无论其他上下文如何，必须调用此函数。”
3. 在历史消息中，检查上一个 role: "assistant" 的回复。在某些模型（如早期 GPT-4）中，如果你传回了一个不带工具调用结果的 role: "assistant" 消息，模型可能会认为上一轮对话已经结束，从而忽略工具策略。

模型不断调用同一个工具并返回相同参数

现象：模型反复查询“北京天气”，每次结果一样，依然继续查询。
排查路径：
1. 首要怀疑对象：工具返回的结果是否被正确追加到 messages 数组中？这是最常见的原因。模型不知道自己已经查询过，所以每次都是“第一次”。
2. 检查返回结果是否被模型“看懂”了。例如，工具返回了 {"temperature": 22}，但模型被“期待”从结果中提取一个 <weather> 标签内的信息。如果实际返回没有这个标签，模型会认为“信息不足”，从而再次调用工具。
3. 如果上述两点都正常，在系统提示中添加限制语句：“如果某次工具调用返回的结果与历史记录中相同，请停止调用并告知用户。”