Python函数调用规范与使用技巧

本文深入剖析了OpenAI API中Python函数调用（Function Calling）的最新规范与实战避坑指南，重点强调tools参数必须为严格格式的list而非dict、每个tool须符合{"type": "function", "function": {...}}结构、function.parameters必须是精准的JSON Schema对象（含type、properties、required），并揭示了模型在启用tools后将强制进入工具决策模式、不再自动fallback至自然语言回复的关键行为；同时指出开发者常踩的三大高发雷区——schema定义偏差、tool_call.id匹配遗漏、role="tool"消息构造不规范——它们合计导致八成线上故障，辅以清晰的调试策略和消息流闭环要求，助你稳稳驾驭GPT-4 Turbo等模型的工具调用能力。

tools 参数必须是 list，不是 dict

OpenAI API（gpt-4-turbo、gpt-3.5-turbo 等）已完全弃用 functions 字段，只认 tools，且它必须是列表类型。传入 dict 或 None 会直接报错 TypeError: object of type 'dict' is not iterable 或 BadRequestError: tools must be an array。

• tools 是顶层请求参数，和 messages 同级，不是嵌套在 system message 里
• 每个 tool 必须是 {"type": "function", "function": {...}} 结构，不能漏掉 "type": "function"
• 哪怕只定义一个工具，也得写成 [{...}]，不是 {...}

function 字段里 parameters 必须是 JSON Schema 对象

不是 Python dict 描述，也不是自然语言说明——模型靠它做参数提取，格式错一点就无法生成合法 tool_calls。常见错误是把 "properties" 写成字符串，或漏掉 "required" 导致字段为空时仍被调用。

• parameters 必须是 {"type": "object", "properties": {...}, "required": [...]}
• 所有参数类型必须明确：城市名用 "type": "string"，温度阈值用 "type": "number"，开关状态用 "type": "boolean"
• "required" 列表里的字段，模型若没提取到就会拒绝调用，而不是填空默认值

model 不会自动 fallback 到自然语言回复

很多开发者以为“模型觉得不合适就自己说人话”，其实不是。一旦你传了 tools，模型就进入「强制工具决策模式」：要么返回 tool_calls，要么返回空 content（即 content=null）。如果用户问“今天心情怎么样”，而你只注册了 get_weather，模型大概率返回空内容，而不是闲聊。

• 想保留自然语言能力，必须在 tools 之外，允许模型返回 content —— 这靠的是不加 tool_choice="required"
• 避免加 tool_choice="required"，除非你 100% 确认每条输入都该触发工具
• 调试时先去掉 tool_choice，观察模型是否真能识别意图，再逐步收紧

执行 tool_calls 后必须手动拼回 conversation history

API 返回的 tool_calls 只是结构化指令，模型不会自动执行。你得自己解析 response.choices[0].message.tool_calls，调用对应函数，拿到结果后，再以 role="tool" 的 message 补回去，才能让模型继续推理。

• 每个 tool_call 有 id、function.name、function.arguments，三者缺一不可
• 调用失败或超时，必须返回带 error 字段的 tool 消息，否则模型卡死
• 不要省略 id：后续 role="tool" 消息必须严格匹配原始 tool_call.id

工具定义看着简单，但 parameters 的 schema 偏差、tool_calls 的 id 匹配遗漏、role="tool" 消息构造不规范——这三处出错，基本占了线上 Function Calling 故障的 80%。

终于介绍完啦！小伙伴们，这篇关于《Python函数调用规范与使用技巧》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！