Function Calling

使用 OpenAI SDK 声明工具、执行 Node.js 函数并回传结果,理解一次完整的 Function Calling 流程。

🎯 引言

在电商后台询问 AI:“SKU-A100 还有多少库存?” 模型虽然能解释库存的含义,却不知道你的业务系统里还有多少件商品。后端已经有查询库存的函数,怎样让模型利用这个函数回答问题?

这就是 Function Calling(函数调用,也称 Tool Calling) 的用途。本篇沿用 AIHubMix + OpenAI SDK,通过一个库存查询案例,学习 声明工具、读取模型的调用请求、执行本地函数,以及将结果交还给模型。先掌握一次完整调用,连续调用工具与任务规划留给后续 AI Agent 课程。


🧱 Function Calling 是怎样工作的

先看用户查询 SKU-A100 库存时,程序与模型之间发生了什么:

顺序谁来处理做什么
1Node.js把库存查询工具的名称、用途和参数要求告诉模型
2模型根据问题提出调用 get_stock 的请求,参数为 SKU-A100
3Node.js检查请求,执行 getStock("SKU-A100"),得到库存 18
4Node.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,再发送第二次模型请求。

消息角色这条消息的内容
userSKU-A100 还有多少库存?
assistant模型提出 get_stock 调用,并附带调用 ID 和参数
toolNode.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 则让模型请求 应用程序执行某个能力。

需求更合适的方式
从商品介绍中提取名称、价格结构化输出
从库存系统查询实时库存Function Calling

两者都可能使用 JSON Schema,但目的不同:前者约束 最终数据,后者约束 工具参数。


❓ 知识问答

Q1:为什么查询完库存,还要让模型再生成一次回答?

工具返回的是结构化业务数据,模型可以结合用户的问题组织自然语言回复。但如果页面只需要展示库存数字,也可以直接使用后端查询结果,不一定非要发起第二次模型请求。

Q2:为什么 tool 消息必须带 tool_call_id?

因为模型可能在一次请求中提出多个工具调用。调用 ID 用来标明这条结果对应哪次请求,避免把不同工具的结果混在一起。本篇只演示一次工具调用,后续再学习连续执行与编排。


🧪 小练习

  1. 在 stockTable 中增加 "SKU-C300": 42,让模型查询这个商品,确认工具参数、函数结果和最终回答一致。
  2. 将问题改成查询 SKU-D400(格式正确,但库存表中不存在),观察函数返回的 found: false。确认模型没有把“商品不存在”误说成“库存为 0”。
  3. 将 tool_choice 改成 "auto",观察模型是否仍会调用库存工具,并解释为什么应用不能假设每次一定都有 tool_calls。

验证标准: 能指出模型在哪一步只提出工具调用请求、Node.js 在哪一步真正执行函数,以及 assistant 工具调用消息和 tool 结果消息为什么必须对应。


🎉 你已经完成一次从模型请求工具、后端执行函数,到模型利用执行结果回答用户的完整流程。