Function Calling
🎯 引言
在电商后台询问 AI:“SKU-A100 还有多少库存?” 模型虽然能解释库存的含义,却不知道你的业务系统里还有多少件商品。后端已经有查询库存的函数,怎样让模型利用这个函数回答问题?
这就是 Function Calling(函数调用,也称 Tool Calling) 的用途。本篇沿用 AIHubMix + OpenAI SDK,通过一个库存查询案例,学习 声明工具、读取模型的调用请求、执行本地函数,以及将结果交还给模型。先掌握一次完整调用,连续调用工具与任务规划留给后续 AI Agent 课程。
🧱 Function Calling 是怎样工作的
先看用户查询 SKU-A100 库存时,程序与模型之间发生了什么:
| 顺序 | 谁来处理 | 做什么 |
|---|---|---|
| 1 | Node.js | 把库存查询工具的名称、用途和参数要求告诉模型 |
| 2 | 模型 | 根据问题提出调用 get_stock 的请求,参数为 SKU-A100 |
| 3 | Node.js | 检查请求,执行 getStock("SKU-A100"),得到库存 18 |
| 4 | Node.js | 把查询结果作为工具消息发回模型 |
| 5 | 模型 | 根据实际结果回答:“SKU-A100 当前库存为 18 件。” |
这里要分清楚:模型只提出调用请求,不会直接运行你的 JavaScript 函数。是否执行、允许执行哪个函数、传入什么参数,由 Node.js 后端决定。
这也解释了为什么通常需要 两次模型请求:第一次让模型提出工具调用,第二次让模型读取工具执行结果并生成最终回答。
🛠 声明库存查询工具
继续使用前面创建的 ai-sdk-course 项目,环境为 Node.js 24.x、openai@7.62.0,直接沿用 .env 中的 AI_API_KEY、AI_BASE_URL 和 AI_MODEL。本例使用支持 Chat Completions 工具调用的模型,例如课程前面使用的 gpt-4o-mini;实际可用模型以 AIHubMix 当前提供的能力为准。
在项目根目录创建 06.function-calling.mjs,先添加库存函数:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.AI_API_KEY,
baseURL: process.env.AI_BASE_URL
});
const stockTable = {
"SKU-A100": 18,
"SKU-B200": 0
};
function getStock(sku) {
if (!Object.hasOwn(stockTable, sku)) {
return { sku, found: false, stock: null };
}
return { sku, found: true, stock: stockTable[sku] };
}
这里用模拟数据代替数据库,以便集中理解工具调用。返回结果特意区分了 库存为零(found: true, stock: 0)和 商品不存在(found: false),两种情况不能混为一谈。
现在 getStock() 只是普通的 Node.js 函数,模型还不知道它的存在。继续在同一个文件中声明工具:
const tools = [
{
type: "function",
function: {
name: "get_stock",
description: "根据商品 SKU 查询当前库存数量",
parameters: {
type: "object",
properties: {
sku: {
type: "string",
description: "商品编号,例如 SKU-A100"
}
},
required: ["sku"],
additionalProperties: false
},
strict: true
}
}
];
这里没有把 getStock() 的函数代码发送给模型,而是提供了一份 工具调用说明:
name:模型看到的工具名称get_stock,与实际的 JavaScript 函数getStock()并不是同一个东西。description:说明工具可以用来查询库存。parameters:声明工具所需参数,本例只有sku。
上一课已经学过 JSON Schema,这里不重复解释 properties、required 等语法。区别在于:上一课的 Schema 用来约束 生成的数据,本篇用它来描述 调用工具所需的参数。strict: true 用于要求模型尽量严格遵循声明的参数结构,但后端仍然必须校验实际参数。
🛠 让模型提出工具调用请求
接着在同一个文件末尾添加:
const messages = [
{
role: "system",
content: "查询库存必须使用工具。根据查询结果回答;商品不存在时不要编造数量。"
},
{
role: "user",
content: "SKU-A100 还有多少库存?"
}
];
const first = await client.chat.completions.create({
model: process.env.AI_MODEL,
messages,
tools,
tool_choice: "required",
parallel_tool_calls: false
});
const assistantMessage = first.choices[0]?.message;
const calls = assistantMessage?.tool_calls ?? [];
if (calls.length !== 1 || calls[0].type !== "function" ||
calls[0].function.name !== "get_stock") {
throw new Error("模型没有返回预期的库存查询请求");
}
const call = calls[0];
console.log("模型的工具请求:", JSON.stringify(call, null, 4));
第一次演示只提供一个工具,并使用两个设置控制调用行为:
tool_choice: "required":要求模型提出工具调用,而不是直接给出文字回答。parallel_tool_calls: false:限制并行工具调用,使本例只处理一个调用请求。
这两个参数要由所选模型和 AIHubMix 的接口支持。这里检查 calls.length,是为了在实际返回结果与预期不符时明确报错,而不是让后续代码处理错误数据。
模型返回的是什么?
此时模型可能返回这样的 tool_calls(省略了其他响应字段,调用 ID 为示意):
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_stock",
"arguments": "{\"sku\":\"SKU-A100\"}"
}
}
这段数据 不是库存结果,而是模型提出的调用请求:
| 字段 | 含义 |
|---|---|
function.name | 模型希望使用的工具:get_stock |
function.arguments | 模型给出的参数,是 JSON 字符串 |
id | 本次工具调用的标识,稍后回传结果时需要用到 |
到这里,库存查询函数还没有被执行。 模型只知道需要查询 SKU-A100,并不知道它的库存是 18。
🛠 执行函数并回传结果
拿到工具调用请求后,Node.js 才真正执行库存查询。继续在同一个文件末尾添加:
const args = JSON.parse(call.function.arguments);
if (typeof args?.sku !== "string" || !/^SKU-[A-Z]\d{3}$/.test(args.sku)) {
throw new Error("SKU 参数不合法,已拒绝执行");
}
const result = getStock(args.sku);
console.log("后端查询结果:", result);
// 保留模型提出的工具调用,再追加与之对应的执行结果
messages.push(assistantMessage);
messages.push({
role: "tool",
tool_call_id: call.id,
content: JSON.stringify(result)
});
const second = await client.chat.completions.create({
model: process.env.AI_MODEL,
messages
});
console.log("模型最终回答:", second.choices[0]?.message?.content ?? "未返回文字");
先解析 function.arguments,检查 sku 是否符合本例的商品编号规则,再调用 getStock()。如果参数格式不合法,程序会拒绝执行;即使工具声明中已经开启 strict,也不能省去后端校验。
对于 SKU-A100,函数返回的是:
{
"sku": "SKU-A100",
"found": true,
"stock": 18
}
接下来是整篇最关键的步骤:把工具结果放进 messages,再发送第二次模型请求。
| 消息角色 | 这条消息的内容 |
|---|---|
user | SKU-A100 还有多少库存? |
assistant | 模型提出 get_stock 调用,并附带调用 ID 和参数 |
tool | Node.js 返回该工具调用的查询结果:库存 18 |
assistant | 模型根据查询结果形成最终回答 |
前面学习多轮对话时,已经知道 messages 用来保留对话上下文。本篇新增的是 工具调用消息:
messages.push(assistantMessage)保留模型发起的调用请求。role: "tool"表示这条消息是工具执行结果,而不是用户的新问题。tool_call_id: call.id把结果准确对应到先前的调用请求。
所以,不能把库存结果随意伪装成新的 user 消息。第二次请求需要同时知道 模型之前请求了什么工具,以及 后端实际返回了什么数据。本例第二次请求不再提供 tools,只让模型根据查询结果组织回答。
运行完整示例
上面四段 JavaScript 代码都写在 06.function-calling.mjs 中,保存后在项目根目录运行:
node --env-file=.env 06.function-calling.mjs
如果需要使用前面验证过的本地代理:
HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 06.function-calling.mjs
终端可能输出以下内容(仅为示意,实际调用 ID 和模型回答不固定):
模型的工具请求: {
"id": "call_abc123",
"type": "function",
"function": {
"name": "get_stock",
"arguments": "{\"sku\":\"SKU-A100\"}"
}
}
后端查询结果: { sku: 'SKU-A100', found: true, stock: 18 }
模型最终回答: SKU-A100 当前库存为 18 件。
从这个输出可以看到:第一次模型请求产生工具调用信息,Node.js 执行库存函数,第二次模型请求使用工具结果生成回答。两次模型请求中间的函数执行,才是 Function Calling 与普通文本生成最大的不同。
🪤 其他情况需要怎么处理
先完成正常流程,再考虑几种实际开发中必须区分的情况:
| 情况 | 本例如何处理 |
|---|---|
| 模型没有按要求返回工具调用 | 抛出错误,不把模型文字误当成实时库存 |
工具名不属于允许的 get_stock | 拒绝执行 |
| 参数不是合法 JSON 或 SKU 格式不正确 | 解析失败或拒绝执行,不查询库存 |
| SKU 格式合法,但商品不存在 | 正常查询,返回 found: false,而不是库存 0 |
模型或平台不支持 required、parallel_tool_calls、strict | 查看模型能力与错误信息,按支持情况调整参数 |
默认情况下,tool_choice: "auto" 允许模型自行决定是否使用工具;"none" 禁止使用工具;本例选用的 "required" 则更适合第一次演示完整流程。实际应用允许模型自主选择工具时,仍须处理没有工具调用的响应。
⚖️ Function Calling 与结构化输出的区别
上一课《结构化输出》用于让模型按指定结构整理输入信息;Function Calling 则让模型请求 应用程序执行某个能力。
| 需求 | 更合适的方式 |
|---|---|
| 从商品介绍中提取名称、价格 | 结构化输出 |
| 从库存系统查询实时库存 | Function Calling |
两者都可能使用 JSON Schema,但目的不同:前者约束 最终数据,后者约束 工具参数。
❓ 知识问答
Q1:为什么查询完库存,还要让模型再生成一次回答?
工具返回的是结构化业务数据,模型可以结合用户的问题组织自然语言回复。但如果页面只需要展示库存数字,也可以直接使用后端查询结果,不一定非要发起第二次模型请求。
Q2:为什么 tool 消息必须带 tool_call_id?
因为模型可能在一次请求中提出多个工具调用。调用 ID 用来标明这条结果对应哪次请求,避免把不同工具的结果混在一起。本篇只演示一次工具调用,后续再学习连续执行与编排。
🧪 小练习
- 在
stockTable中增加"SKU-C300": 42,让模型查询这个商品,确认工具参数、函数结果和最终回答一致。 - 将问题改成查询
SKU-D400(格式正确,但库存表中不存在),观察函数返回的found: false。确认模型没有把“商品不存在”误说成“库存为 0”。 - 将
tool_choice改成"auto",观察模型是否仍会调用库存工具,并解释为什么应用不能假设每次一定都有tool_calls。
验证标准: 能指出模型在哪一步只提出工具调用请求、Node.js 在哪一步真正执行函数,以及 assistant 工具调用消息和 tool 结果消息为什么必须对应。
🎉 你已经完成一次从模型请求工具、后端执行函数,到模型利用执行结果回答用户的完整流程。
