5分钟上手Function Calling：让大模型从聊天到执行的关键技术-三亩地-编程学习日记

1. 项目概述：为什么Function Calling是AI应用开发的分水岭？

如果你最近在折腾大模型应用开发，无论是想做个智能客服、数据分析助手，还是想给自家产品加个“大脑”，那你一定绕不开一个词：Function Calling。这玩意儿听起来有点技术范儿，但说白了，它就是让大语言模型（比如GPT、Claude这些）不仅能跟你聊天，还能“动手”帮你干实事的关键桥梁。想象一下，你问AI“帮我查一下北京明天下午三点的天气”，传统的AI可能只会给你一段描述天气的文字。但有了Function Calling，AI能理解你的意图，然后自动调用一个“查询天气”的接口，把真实的、结构化的数据（比如温度、湿度、风速）精准地返回给你，甚至直接帮你把日历事件创建好。

这就是Function Calling的核心价值：将自然语言的模糊指令，转化为对特定工具或API的精确调用。它彻底改变了我们与AI的交互模式，从“问答机”升级为“执行者”。网络上热议的“AI智能体”、“AI Agent”的雏形，其核心动作机制就是Function Calling。它不再满足于生成文本，而是追求在真实世界中产生动作和结果。对于开发者而言，掌握了Function Calling，就相当于拿到了将大模型能力无缝集成到现有业务和工作流中的万能钥匙。今天，我们就抛开复杂的理论，用最直白的方式，在5分钟内带你跑通第一个Function Calling实例，让你真切感受到这种“AI执行力”的魅力。

2. 核心思路拆解：Function Calling是如何工作的？

在撸起袖子写代码之前，我们得先搞明白Function Calling的“工作流程图”。这能帮你理解每一步在做什么，而不是机械地复制粘贴。整个流程可以概括为“两次对话，一次执行”。

2.1 第一步：定义“工具清单”

首先，你需要告诉大模型：“嗨，我这里有这些工具（函数）你可以用。” 这份“工具清单”就是一组函数描述。每个描述通常包括：

函数名：一个清晰的标识，比如get_current_weather。
描述：用自然语言告诉模型这个函数是干什么的。这部分至关重要，模型主要靠它来理解何时该调用此函数。例如：“获取指定城市的当前天气情况。”
参数：定义函数需要哪些输入，以及每个输入的类型和描述。例如，一个city参数，类型是字符串，描述是“城市名称，例如‘北京’、‘San Francisco’”。

这个清单会随着你的请求一起发送给大模型。注意，你只是发送了函数的“说明书”（元数据），并没有发送函数的具体实现代码。模型根本看不到你的代码逻辑。

2.2 第二步：模型的理解与决策

用户发出一个请求，比如“旧金山天气怎么样？”。大模型结合你的问题，以及你刚才提供的“工具清单”，进行推理：

意图识别：用户想知道天气。
工具匹配：在清单里，有一个叫get_current_weather的函数，描述是获取天气的。
参数提取：从用户问题中提取出关键参数“旧金山”，对应函数参数city。
生成调用请求：模型不会直接执行代码，而是会生成一个结构化的响应，内容大概是：“我决定调用get_current_weather函数，并且参数city应该设为 ‘San Francisco’。”

这个响应是一个标准的、机器可读的格式（通常是JSON），里面包含了它“想”调用的函数名和具体的参数值。

2.3 第三步：本地执行与结果返回

你的应用程序收到模型返回的“调用请求”后，真正的魔法才发生：

本地调用：你的代码根据模型返回的函数名，在你的本地或服务端找到对应的真实函数（比如一个调用天气API的函数），并用模型提供的参数去执行它。
获取真实结果：函数执行后，会返回真实的数据，比如{“temperature”: 22, “unit”: “celsius”, “description”: “晴朗”}。
二次对话：你将这个真实的函数执行结果，再次发送给大模型，并请它基于这个结果来组织最终回复给用户的自然语言。
生成用户回复：模型收到真实数据后，会生成一段友好、易懂的回复，比如：“旧金山目前天气晴朗，气温22摄氏度。”

至此，一个完整的Function Calling闭环就完成了。用户用自然语言提问，获得了基于真实数据生成的精准回答。整个过程，模型扮演了“理解者”和“调度者”的角色，而具体的“体力活”（调用API、处理数据）则由你定义的函数来完成。

关键理解：Function Calling的本质是“意图解析”和“任务分发”。大模型负责最擅长的语义理解，将非结构化的语言转化为结构化的调用指令；开发者负责提供可靠、安全的执行能力。两者结合，威力无穷。

3. 环境准备与工具选型

理论懂了，我们开始实战。为了在5分钟内快速上手，我们需要选择最简洁、高效的路径。这里我强烈推荐使用OpenAI的API和Python语言，因为它们的生态最成熟，文档最全，社区资源最多，能让你避开很多初期的坑。

3.1 核心工具：OpenAI API

为什么是OpenAI？虽然其他模型也陆续支持了类似功能，但OpenAI的Function Calling实现最早、最稳定，并且其gpt-3.5-turbo和gpt-4系列模型对此功能支持得非常好。对于学习和快速验证来说，它是首选。

你需要准备：

一个OpenAI账号：去平台官网注册即可。
API密钥：在账号后台生成一个sk-开头的密钥，这是调用API的通行证。
一定的API额度：新账号通常有免费试用额度，足够我们完成大量实验。

3.2 开发环境搭建

我们追求极简，只需要一个能运行Python的环境。

方案一（推荐）：使用Google Colab。这是一个在线的Jupyter笔记本环境，无需在本地安装任何东西，打开浏览器就能写代码、运行代码，并且预装了大部分常用库。对于快速体验来说，这是零门槛的最佳选择。
方案二：如果你习惯本地开发，确保你的电脑安装了Python（建议3.8以上版本）。然后通过pip安装必要的库。

3.3 安装必要的Python库

打开你的终端（本地）或Colab的代码单元格（在线），执行以下安装命令。在Colab中，很多库可能已预装，但执行一下也无妨。

pip install openai

是的，主要就是这个openai库。它封装了与OpenAI API通信的所有细节，让我们能用几行代码就完成复杂交互。

实操心得：API密钥的安全管理永远不要将你的API密钥直接硬编码在代码里，尤其是打算分享或上传到GitHub时。密钥泄露会导致他人盗用你的额度。正确的做法是使用环境变量。在本地，你可以在终端中设置：export OPENAI_API_KEY='你的sk-密钥'。在Colab中，可以使用以下代码片段，它会在运行时弹出一个输入框让你安全地填入密钥：
from google.colab import userdata # 首先，在Colab的「密钥」设置部分（左侧钥匙图标）添加你的OPENAI_API_KEY import os os.environ[“OPENAI_API_KEY”] = userdata.get(‘OPENAI_API_KEY’)
或者在Colab单元格中直接使用getpass进行临时输入：
from getpass import getpass api_key = getpass(“请输入你的OpenAI API密钥: “) os.environ[“OPENAI_API_KEY”] = api_key

4. 5分钟核心实战：构建你的第一个天气查询助手

现在，我们进入最激动人心的环节：写代码。我们将实现一个经典的天气查询Function Calling例子。请跟着我一步步操作。

4.1 第一步：导入库并设置客户端

import openai import json # 用于处理模型返回的JSON数据 import os # 设置你的API密钥。请务必用你自己的密钥替换下面的字符串。 # 安全提示：在实际项目中，请使用上文提到的环境变量方法！ openai.api_key = “你的-api-key-here” # TODO: 请替换 # 或者，如果你已经设置了环境变量 OPENAI_API_KEY，可以这样： # openai.api_key = os.environ.get(“OPENAI_API_KEY”) # 创建一个简单的客户端（旧版openai库写法，清晰易懂） client = openai.OpenAI()

4.2 第二步：定义你的“工具”（函数）

这里我们定义两个东西：1. 给模型看的“函数描述”；2. 我们本地真正执行的函数。

# 1. 定义给模型看的“工具”（函数描述） tools = [ { “type”: “function”, “function”: { “name”: “get_current_weather”, # 函数名，模型将返回这个名字 “description”: “获取指定城市的当前天气”, # 关键！模型靠这个理解功能 “parameters”: { # 定义参数结构 “type”: “object”, “properties”: { “location”: { # 参数名 “type”: “string”, “description”: “城市或地区名称，例如：北京， San Francisco”， }, “unit”: { “type”: “string”, “enum”: [“celsius”, “fahrenheit”], # 枚举，限定可选值 “description”: “温度单位，摄氏度或华氏度”， } }, “required”: [“location”], # 必填参数 }, }, } ] # 2. 定义本地实际执行的函数 # 注意：这是一个模拟函数。真实场景中，这里应该调用如OpenWeatherMap等真实天气API。 def get_current_weather(location, unit=“celsius”): “”“模拟获取天气数据。在实际应用中，这里应替换为真实的API调用。”“” # 模拟一些假数据 weather_data = { “北京”: {“temperature”: 25, “unit”: unit, “condition”: “晴朗”， “humidity”: 40}, “San Francisco”: {“temperature”: 18, “unit”: unit, “condition”: “多云”， “humidity”: 65}, “London”: {“temperature”: 12, “unit”: unit, “condition”: “小雨”， “humidity”: 80}, } # 返回模拟数据，如果城市不在字典里，返回一个默认值 return weather_data.get(location, {“temperature”: 20, “unit”: unit, “condition”: “未知”， “humidity”: 50})

代码解读：

tools列表就是我们递给模型的“工具箱说明书”。description字段要写得清晰准确，这是模型能否正确触发函数的关键。
本地函数get_current_weather是实际干活的。这里我们用字典模拟了数据。在真实项目中，你会在这里编写调用真实天气API（如和风天气、OpenWeatherMap）的代码，并解析返回的JSON数据。

4.3 第三步：发起对话，让模型决定是否调用函数

现在，我们模拟用户提问，并将tools信息传给模型。

# 用户的提问 user_query = “请问北京现在的天气如何？用摄氏度告诉我。” # 第一次请求：将用户问题和工具描述发给模型 response = client.chat.completions.create( model=“gpt-3.5-turbo”， # 也可以使用 gpt-4, gpt-4-turbo messages=[{“role”: “user”, “content”: user_query}], tools=tools, # 关键！这里传递了我们定义的工具列表 tool_choice=“auto”， # 让模型自动决定是否以及调用哪个工具 ) # 查看模型的回复 message = response.choices[0].message print(“模型的第一轮回复:”) print(message) print(“\n” + “-”*50 + “\n”)

运行这段代码，你会看到模型的回复message对象里，不仅包含常见的content字段（可能为空），更重要的是包含了一个tool_calls列表。这正是模型发出的“调用指令”。

4.4 第四步：解析调用指令并执行本地函数

我们需要检查模型是否决定调用函数，如果是，就提取参数并执行我们本地的函数。

# 检查模型是否要求调用函数 if message.tool_calls: # 通常一次只调用一个函数，我们取第一个 tool_call = message.tool_calls[0] function_name = tool_call.function.name function_args = json.loads(tool_call.function.arguments) # 解析参数 print(f“模型决定调用函数: {function_name}”) print(f“调用参数: {function_args}”) # 根据函数名，调用对应的本地函数 available_functions = { “get_current_weather”: get_current_weather, } function_to_call = available_functions[function_name] # 执行函数，传入模型解析出的参数 function_response = function_to_call(**function_args) print(f“本地函数执行结果: {function_response}”) else: print(“模型未触发函数调用，直接回复:”, message.content)

执行逻辑：

if message.tool_calls:判断模型是否返回了工具调用。
tool_call.function.name拿到函数名“get_current_weather”。
json.loads(tool_call.function.arguments)拿到参数字典，例如{“location”: “北京”， “unit”: “celsius”}。
我们预定义了一个available_functions映射字典，将函数名与本地函数对象关联起来。
function_to_call(**function_args)使用参数解包的方式调用本地函数，得到真实的天气数据。

4.5 第五步：将执行结果送回模型，生成最终回复

模型还不知道我们执行函数的结果呢。我们需要把结果作为新的消息追加到对话历史中，再次请求模型生成面向用户的最终回答。

# 将函数执行结果作为新的消息追加到对话历史中 # 首先，把模型刚才的回复（包含tool_calls）加入历史 messages = [ {“role”: “user”, “content”: user_query}, message, # 模型的第一次回复，包含tool_calls { “role”: “tool”， # 注意角色是“tool”，用于返回函数结果 “tool_call_id”: tool_call.id, # 必须对应之前的tool_call id “content”: json.dumps(function_response), # 函数结果必须转为JSON字符串 }, ] # 第二次请求：将包含函数结果的完整历史发给模型，让它生成最终回答 second_response = client.chat.completions.create( model=“gpt-3.5-turbo”， messages=messages, ) # 获取最终的自然语言回复 final_answer = second_response.choices[0].message.content print(“\n” + “=”*50) print(“AI的最终回复：”) print(final_answer) print(“=”*50)

关键点：

“role”: “tool”是一个特殊的消息角色，专门用于向模型传递函数执行结果。
tool_call_id必须与之前模型请求中的tool_call.id一致，这样模型才知道这个结果是针对哪个调用请求的。
content字段需要是函数返回值的JSON字符串形式。

运行全部代码，你将在控制台看到类似以下的输出：

模型的第一轮回复: ChatCompletionMessage(content=‘’， role=‘assistant’， function_call=None， tool_calls=[ChatCompletionMessageToolCall(id=‘call_abc…’， function=Function(arguments=‘{“location”: “北京”， “unit”: “celsius”}’， name=‘get_current_weather’)， type=‘function’)]) 模型决定调用函数: get_current_weather 调用参数: {‘location’: ‘北京’， ‘unit’: ‘celsius’} 本地函数执行结果: {‘temperature’: 25, ‘unit’: ‘celsius’， ‘condition’: ‘晴朗’， ‘humidity’: 40} ================================================== AI的最终回复： 北京目前天气晴朗，气温25摄氏度，湿度40%。 ==================================================

恭喜！你已经成功实现了第一个Function Calling流程。从用户提问到获得基于“真实数据”的回复，整个过程完全自动化。

5. 参数详解与高级配置

跑通流程只是第一步。要让Function Calling在实际项目中稳定可靠，必须深入理解每个参数的含义。下面我们拆解client.chat.completions.create中与Function Calling相关的关键参数。

5.1`tools`：函数定义的艺术

tools参数是一个列表，每个元素定义一个工具。除了我们上面用的“type”: “function”，未来可能还有其他类型。在function对象内：

name：尽量使用简洁、清晰的蛇形命名（snake_case），如calculate_bmi,search_database。
description：这是最重要的字段。描述要具体，说明函数的用途、适用场景。例如，“根据用户的身高和体重计算身体质量指数(BMI)，并返回BMI值和健康类别（偏瘦、正常、超重、肥胖）”，就比“计算BMI”好得多。好的描述能极大提升模型调用的准确率。
parameters：遵循JSON Schema格式。
- properties定义每个参数。每个参数最好都有type和description。
- required数组列出必填参数名。对于有默认值的可选参数，可不放入required。

示例：一个更复杂的函数定义

tools = [ { “type”: “function”, “function”: { “name”: “book_flight”， “description”: “根据出发地、目的地、日期和乘客信息，查询并预订航班。”， “parameters”: { “type”: “object”, “properties”: { “departure_city”: {“type”: “string”， “description”: “出发城市机场代码，如PEK（北京首都）”}， “arrival_city”: {“type”: “string”， “description”: “到达城市机场代码，如SHA（上海虹桥）”}， “departure_date”: {“type”: “string”， “description”: “出发日期，格式为YYYY-MM-DD”}， “return_date”: {“type”: “string”， “description”: “返程日期（可选），格式为YYYY-MM-DD”}， “passengers”: { “type”: “object”， “properties”: { “adults”: {“type”: “integer”， “description”: “成人数量”}， “children”: {“type”: “integer”， “description”: “儿童数量”}， “infants”: {“type”: “integer”， “description”: “婴儿数量”} } } }, “required”: [“departure_city”， “arrival_city”， “departure_date”， “passengers”]， } } } ]

5.2`tool_choice`：控制模型的调用行为

这个参数决定了模型在调用工具上的自由度。

“auto”(默认)：模型自主决定是否调用以及调用哪个工具。这是最常用的模式。
“none”：强制模型不调用任何工具，只生成文本回复。当你想禁用本次对话中的Function Calling时使用。
{“type”: “function”， “function”: {“name”: “get_current_weather”}}：强制模型调用指定的某个工具。即使对话上下文不适合，模型也会尝试生成调用该工具的参数。这在构建确定性工作流时非常有用。

5.3`temperature`与`top_p`：影响决策的稳定性

这两个参数控制模型输出的随机性（“创造力”），同样会影响函数调用的决策。

temperature：值越高（如0.8），输出越随机、多样；值越低（如0.2），输出越确定、保守。
在Function Calling场景下的建议：对于需要稳定、准确调用函数的场景（如客服机器人执行操作），建议将temperature设置为0或一个非常低的值（如0.1）。这可以最大程度减少模型“突发奇想”去调用错误函数或生成错误参数的概率。在我们之前的天气例子中，可以这样设置：

response = client.chat.completions.create( model=“gpt-3.5-turbo”， messages=messages, tools=tools, tool_choice=“auto”， temperature=0, # 设置为0，让函数调用决策更稳定 )

5.4 并行工具调用与流式响应

并行工具调用：从gpt-3.5-turbo-1106和gpt-4-1106-preview版本开始，模型支持在单个回复中同时调用多个工具（message.tool_calls列表包含多个元素）。这意味着你可以一次性定义“查天气”、“查日历”、“发邮件”等多个工具，用户说“帮我看看明天北京的天气，如果晴天就晚上7点安排一场篮球赛”，模型可能同时触发天气查询和日历创建两个函数调用。你需要遍历tool_calls列表来执行所有函数。
流式响应：对于需要长时间运行的函数，或者你想在网页应用中实现打字机效果，可以使用流式响应（stream=True）。在流式响应中，函数调用信息会作为一个独立的delta块提前返回，这样你可以在函数执行的同时就开始准备，提升用户体验。

6. 实战进阶：构建一个多功能的个人助理

单一功能不过瘾，我们来构建一个更实用的、具备多功能的简易个人助理。这个助理将能处理三项任务：查询天气、计算数学、记录待办事项。我们将看到模型如何在不同工具间做选择。

6.1 定义多功能工具箱

import math import datetime # 1. 定义给模型的多功能工具列表 multi_tools = [ { # 工具1: 天气查询（模拟） “type”: “function”, “function”: { “name”: “get_weather”， “description”: “获取指定城市未来几天的天气预报。”， “parameters”: { “type”: “object”, “properties”: { “city”: {“type”: “string”， “description”: “城市名称”}， “days”: {“type”: “integer”， “description”: “预报天数，默认为1，最多3天”， “default”: 1} }, “required”: [“city”]， } } }, { # 工具2: 数学计算 “type”: “function”, “function”: { “name”: “calculate”， “description”: “执行基础数学运算，支持加(+)、减(-)、乘(*)、除(/)、乘方(**)及常用函数如sqrt（平方根）、sin（正弦）等。表达式需为字符串。”， “parameters”: { “type”: “object”, “properties”: { “expression”: {“type”: “string”， “description”: “数学表达式，例如：‘3 + 5 * 2’， ‘sqrt(16)’， ‘sin(pi/2)’”} }, “required”: [“expression”]， } } }, { # 工具3: 待办事项管理（模拟，用内存列表存储） “type”: “function”, “function”: { “name”: “manage_todo”， “description”: “管理待办事项列表。可以添加新事项、标记事项为完成、或列出所有事项。”， “parameters”: { “type”: “object”, “properties”: { “action”: { “type”: “string”， “enum”: [“add”， “complete”， “list”]， “description”: “要执行的操作：‘add’添加，‘complete’标记完成，‘list’列出所有” }, “task”: { “type”: “string”， “description”: “待办事项的描述（‘add’操作时必需）” }, “task_id”: { “type”: “integer”， “description”: “待办事项的ID编号（‘complete’操作时必需）” } }, “required”: [“action”]， } } } ] # 2. 实现本地函数 # 模拟天气数据 def get_weather(city, days=1): forecast = [f”{city}第{i+1}天：模拟数据，晴朗，{20+i}摄氏度” for i in range(min(days, 3))] return {“city”: city, “forecast”: forecast} # 安全计算函数（使用eval需极其谨慎！此处仅为演示，生产环境应用更安全的方法如ast.literal_eval或专用库） def calculate(expression): try: # 警告：在生产环境中直接使用eval非常危险，容易导致代码注入！ # 这里仅作演示，假设表达式是安全的。 result = eval(expression, {“__builtins__”: {}}, {“sqrt”: math.sqrt, “sin”: math.sin, “pi”: math.pi, “e”: math.e}) return {“expression”: expression, “result”: result} except Exception as e: return {“expression”: expression, “error”: str(e)} # 简单的内存待办事项列表 todo_list = [] next_id = 1 def manage_todo(action, task=None, task_id=None): global next_id, todo_list if action == “add”: if not task: return {“error”: “添加任务时需要提供‘task’参数”} new_task = {“id”: next_id, “task”: task, “done”: False, “created_at”: datetime.datetime.now().isoformat()} todo_list.append(new_task) next_id += 1 return {“action”: “add”， “task_added”: new_task} elif action == “complete”: if task_id is None: return {“error”: “标记完成时需要提供‘task_id’参数”} for t in todo_list: if t[“id”] == task_id: t[“done”] = True t[“completed_at”] = datetime.datetime.now().isoformat() return {“action”: “complete”， “task_completed”: t} return {“action”: “complete”， “error”: f”未找到ID为{task_id}的任务”} elif action == “list”: return {“action”: “list”， “todo_list”: todo_list} else: return {“error”: f”未知操作：{action}”} # 3. 函数映射字典 available_functions = { “get_weather”: get_weather, “calculate”: calculate, “manage_todo”: manage_todo, }

6.2 构建智能对话循环

现在，我们创建一个简单的循环，让用户可以和这个多功能助理持续交互。

def run_assistant_conversation(): “”“运行一个简单的对话循环。”“” messages = [] # 保存对话历史 print(“多功能个人助理已启动。输入‘退出’或‘quit’结束对话。”) print(“你可以问我：天气、计算、管理待办事项。\n”) while True: # 获取用户输入 user_input = input(“你: “) if user_input.lower() in [“退出”， “quit”， “exit”]: print(“助理: 再见！”) break # 将用户输入加入历史 messages.append({“role”: “user”， “content”: user_input}) # 第一步：发送请求，让模型决定做什么 try: response = client.chat.completions.create( model=“gpt-3.5-turbo”， messages=messages, tools=multi_tools, tool_choice=“auto”， temperature=0, # 低温度值保证决策稳定 ) except Exception as e: print(f“调用API时出错: {e}”) continue assistant_message = response.choices[0].message messages.append(assistant_message) # 将模型的回复（可能包含tool_calls）加入历史 # 第二步：检查并执行函数调用 if assistant_message.tool_calls: print(“助理: （正在处理你的请求…）”) for tool_call in assistant_message.tool_calls: function_name = tool_call.function.name function_args = json.loads(tool_call.function.arguments) # 找到并执行对应的本地函数 if function_name in available_functions: function_to_call = available_functions[function_name] try: function_response = function_to_call(**function_args) except Exception as e: function_response = {“error”: f”执行函数{function_name}时出错: {str(e)}”} else: function_response = {“error”: f”未知函数: {function_name}”} # 将每个函数执行结果作为tool消息追加 messages.append({ “role”: “tool”， “tool_call_id”: tool_call.id, “content”: json.dumps(function_response, ensure_ascii=False), # 处理中文 }) # 第三步：将所有函数结果送回模型，生成最终回复 second_response = client.chat.completions.create( model=“gpt-3.5-turbo”， messages=messages, temperature=0.7, # 最终回复可以有些许创造性 ) final_message = second_response.choices[0].message messages.append(final_message) # 将最终回复加入历史 print(f”助理: {final_message.content}”) else: # 模型没有调用函数，直接回复 print(f”助理: {assistant_message.content}”) print() # 空行分隔对话轮次 # 运行对话 # 注意：在长时间循环中，请确保你的API密钥有效且有足够额度。 # run_assistant_conversation() # 取消注释这行来运行

运行示例：

你: 帮我计算一下125除以5再加上18的结果。 助理: （正在处理你的请求…） 助理: 计算结果是 43.0。因为 125 ÷ 5 = 25，然后 25 + 18 = 43。 你: 北京明天和后天的天气怎么样？ 助理: （正在处理你的请求…） 助理: 根据预报，北京明天（第1天）：模拟数据，晴朗，20摄氏度；后天（第2天）：模拟数据，晴朗，21摄氏度。 你: 添加一个待办事项：写Function Calling技术博客。 助理: （正在处理你的请求…） 助理: 已为您添加待办事项：写Function Calling技术博客（ID: 1）。 你: 列出我所有的待办事项。 助理: （正在处理你的请求…） 助理: 您当前的待办事项列表如下： 1. [ ] ID: 1 - 写Function Calling技术博客 (创建于: 2023-10-27T10:30:00)

通过这个例子，你可以清晰地看到，模型就像一个智能调度中心，根据你的自然语言指令，准确地选择并调用了不同的“工具”来完成任务。这就是构建复杂AI应用的基础。

7. 避坑指南与最佳实践

在实际开发中，你会遇到各种问题。下面是我从大量实践中总结出的经验，能帮你节省大量调试时间。

7.1 函数描述（Description）是成败关键

模型完全依靠你提供的函数描述来决定是否以及如何调用。模糊的描述会导致错误的调用或根本不调用。

差描述：“获取数据”。太模糊，什么数据？从哪里获取？
好描述：“根据股票代码，从模拟数据源获取该股票最新的价格和涨跌幅信息。”清晰说明了功能、输入（股票代码）、输出范围。

技巧：在描述中，可以加入一些触发条件的暗示。例如，对于天气函数，可以写“当用户询问某地当前或未来的天气状况时调用此函数。”

7.2 处理模型“幻觉”与错误调用

即使描述很清晰，模型有时也会“幻觉”出不存在的参数，或者错误地调用函数。

防御性编程：在你的本地函数中，对传入的参数进行严格的类型检查和有效性验证。即使模型返回了unit: “kelvin”（而你只定义了celsius和fahrenheit），你的代码也要能优雅处理，返回一个友好的错误信息。
提供反馈循环：如果函数执行失败（如参数无效、API调用错误），将明确的错误信息通过tool角色返回给模型。模型有时能根据错误信息，在下一轮对话中纠正自己或向用户澄清问题。

7.3 管理对话历史与上下文

Function Calling的对话往往是多轮的。妥善管理messages列表至关重要。

必须包含完整上下文：每次API调用，messages参数应该包含从对话开始到当前的所有消息（用户消息、助理消息、工具消息）。如果丢失了历史，模型就无法理解当前的上下文。
控制上下文长度：长对话会导致token数快速增长，增加成本和可能触及模型上下文窗口限制（如GPT-3.5-Turbo的16K）。对于超长对话，需要考虑摘要历史、只保留最近N条消息等策略。
角色不要弄错：用户消息role: “user”，助理消息role: “assistant”，工具返回消息role: “tool”。混淆角色会导致模型无法正确理解对话结构。

7.4 安全性考量

永远不要相信模型的输入：模型返回的函数参数是文本解析而来的。必须将其视为不可信的、需要净化的用户输入。防止注入攻击（如SQL注入、命令注入）。
谨慎使用eval：我们的计算函数示例中使用了eval，这在生产环境是极度危险的。用户可能输入__import__(‘os’).system(‘rm -rf /’)这样的恶意字符串。在实际项目中，应使用安全的数学表达式解析库（如ast.literal_eval配合白名单，或numexpr）。
API密钥与权限：你的本地函数可能会调用内部或第三方API。确保这些API调用是在安全的服务器端进行，并且使用的令牌、密钥有最小必要权限。不要在客户端（如浏览器）暴露核心API密钥。

7.5 性能与成本优化

批量处理：如果用户请求可能触发多个独立函数调用，考虑是否可以将它们合并或批量处理，减少API调用次数。
缓存结果：对于耗时的函数调用（如复杂的数据库查询、外部API调用），如果结果在短时间内不会变化，可以考虑缓存结果，避免重复计算和调用。
选择合适的模型：gpt-3.5-turbo在Function Calling上通常已经足够好，且成本远低于gpt-4。仅在需要极复杂推理或更高准确性的场景下才考虑使用GPT-4。

8. 常见问题排查（FAQ）

在实际操作中，你可能会遇到以下问题。这里提供快速的排查思路。

Q1: 模型总是返回普通文本，不触发函数调用，怎么办？

检查函数描述：描述是否足够清晰、具体？是否准确描述了函数的用途和触发场景？尝试用更详细、场景化的语言重写description。
检查用户输入：你的用户输入是否明确包含了需要调用函数的意图？例如，“今天热吗？”可能不够直接，而“上海今天气温多少度？”就更好。
调整temperature：尝试将temperature设为0，减少随机性。
提供示例：在系统消息（role: “system”）或对话历史中，给模型一两个函数调用的示例，进行少样本学习（Few-shot Learning）。

Q2: 模型调用了错误的函数，或者提取的参数不对，怎么办？

优化参数描述：检查函数参数的description，确保它们无歧义。例如，location参数描述为“城市和国家的名称，例如‘中国北京’”，比单纯的“地点”更好。
使用enum限制选项：如果参数只有几个固定值（如单位unit），务必使用enum列出，这能极大提高准确性。
审查对话历史：是否之前的对话导致了错误的上下文？尝试简化或重置历史。

Q3: 本地函数执行成功，但模型的最终回复很奇怪或没有使用结果数据，为什么？

检查tool消息格式：确保tool_call_id与请求中的id完全一致，并且content是函数返回值的JSON字符串。如果返回的是Python字典，务必用json.dumps()转换。
检查返回数据的结构：模型可能不擅长处理过于嵌套或非标准的数据结构。尽量返回扁平化的、字段名清晰的字典。

Q4: 遇到了速率限制（Rate Limit）错误，如何解决？

OpenAI API对每分钟和每天的请求次数、Token数量都有限制。错误信息通常会很明确（如429状态码）。
解决方案：1) 实现指数退避重试机制，在代码中加入遇到速率限制时等待一段时间再重试。2) 申请提高速率限制。3) 优化你的应用，减少不必要的API调用。

Q5: 如何调试复杂的Function Calling流程？

打印关键信息：在开发阶段，详细打印出messages列表、模型返回的assistant_message对象、解析出的参数以及本地函数的返回结果。
使用Playground：OpenAI官方Playground提供了可视化界面来测试Function Calling，你可以直观地看到消息流和工具调用，是调试的利器。

Function Calling不是一个“黑魔法”，而是一个设计精巧的协议。理解其工作原理，遵循最佳实践，你就能可靠地将大模型的“思考”能力，转化为实实在在的“行动”能力，构建出真正智能、有用的应用程序。从今天这个5分钟的快速上手开始，去探索更广阔的可能性吧。

日记详情

5分钟上手Function Calling：让大模型从聊天到执行的关键技术