Function Calling 入门

6.1 今天你要完成什么

模型很会理解语言，但精确计算应该交给代码函数。这样结果更稳定，也更容易检查。

• 能解释为什么不要让模型猜计算结果。
• 能设计 add、multiply、divide 三个函数。
• 能让 AI 从一句话里找出函数名和参数。
• 能把函数结果再交给 AI 用自然语言解释。

6.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：Function Calling 的重点不是让 AI 执行代码，而是让 AI 决定“应该调用哪个工具”。真正执行函数的是你的程序。
• 可靠性理论：数学计算、成绩统计、日期规则等确定性任务，应该交给函数完成，避免让模型猜。
• 回传理论：函数执行完以后，要把结果回传给模型，模型再把结果解释成学生能懂的话。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI计算小助手”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“工具定义、参数、函数结果回传”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

6.3 课堂讲解

这一课的项目是“AI计算小助手”，重点是“工具定义、参数、函数结果回传”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Function Calling。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课开始让 AI 和函数合作。模型听懂人的话，函数做确定的事。这样的分工很像课堂小组：一个同学负责读题，一个同学负责计算。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：帮我算 23 乘以 17；48 除以 6 是多少？；长方形宽 8 高 5，面积多少？。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

不要让模型负责精确计算。它可以解释过程，但平均分、面积、乘法结果应该由函数给出。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI计算小助手”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

6.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

你可以替换成这些输入

• 帮我算 23 乘以 17。
• 48 除以 6 是多少？
• 长方形宽 8 高 5，面积多少？
• 把 72 和 89 相加。
• 我想知道 15 的平方。

6.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-06.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-06.mjs
6. 把最后一行的示例输入换成你自己的测试内容。

Node.js 完整代码

import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const tools = [
  {
    type: "function",
    name: "calculate",
    description: "完成基础数学计算。",
    parameters: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["add", "subtract", "multiply", "divide"],
        },
        a: { type: "number" },
        b: { type: "number" },
      },
      required: ["operation", "a", "b"],
      additionalProperties: false,
    },
    strict: true,
  },
];

function calculate({ operation, a, b }) {
  if (operation === "add") return a + b;
  if (operation === "subtract") return a - b;
  if (operation === "multiply") return a * b;
  if (operation === "divide") {
    if (b === 0) return "错误：不能除以 0";
    return a / b;
  }
  return "错误：未知运算";
}

let input = [
  { role: "user", content: "帮我算一下 23 乘以 17，并用一句话解释过程。" },
];

let response = await client.responses.create({
  model: MODEL,
  input,
  tools,
});

input.push(...response.output);

for (const item of response.output) {
  if (item.type !== "function_call") continue;
  if (item.name === "calculate") {
    const args = JSON.parse(item.arguments);
    const result = calculate(args);
    input.push({
      type: "function_call_output",
      call_id: item.call_id,
      output: JSON.stringify({ result }),
    });
  }
}

response = await client.responses.create({
  model: MODEL,
  input,
  tools,
  instructions: "请用学生能懂的话解释计算结果，不要编造函数没有返回的数字。",
});

console.log(response.output_text);

Python 运行方式

1. 新建文件 lesson-06.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-06.py
6. 把 main 里的示例输入换成你自己的测试内容。

Python 完整代码

from openai import OpenAI
import json
import os

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

tools = [
    {
        "type": "function",
        "name": "calculate",
        "description": "完成基础数学计算。",
        "parameters": {
            "type": "object",
            "properties": {
                "operation": {
                    "type": "string",
                    "enum": ["add", "subtract", "multiply", "divide"],
                },
                "a": {"type": "number"},
                "b": {"type": "number"},
            },
            "required": ["operation", "a", "b"],
            "additionalProperties": False,
        },
        "strict": True,
    }
]


def calculate(operation, a, b):
    if operation == "add":
        return a + b
    if operation == "subtract":
        return a - b
    if operation == "multiply":
        return a * b
    if operation == "divide":
        if b == 0:
            return "错误：不能除以 0"
        return a / b
    return "错误：未知运算"


input_items = [
    {"role": "user", "content": "帮我算一下 23 乘以 17，并用一句话解释过程。"}
]

response = client.responses.create(model=MODEL, input=input_items, tools=tools)
input_items += response.output

for item in response.output:
    if item.type != "function_call":
        continue
    if item.name == "calculate":
        args = json.loads(item.arguments)
        result = calculate(**args)
        input_items.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"result": result}, ensure_ascii=False),
        })

response = client.responses.create(
    model=MODEL,
    input=input_items,
    tools=tools,
    instructions="请用学生能懂的话解释计算结果，不要编造函数没有返回的数字。",
)

print(response.output_text)

6.6 跟着做

1. 先写一个普通函数，例如 multiply(a, b)。
2. 给函数写清楚参数名和参数类型。
3. 让 AI 判断用户需要哪个函数。
4. 程序执行函数，拿到真实结果。
5. 把结果展示给用户，并说明过程。

6.7 常见错误

• 函数名字不清楚，模型不知道什么时候用。
• 参数类型没有规定，数字被当成文字。
• 函数返回后没有检查结果。
• 把所有任务都交给模型，程序没有发挥作用。

6.8 课后练习

1. 新增 area_rectangle(width, height) 函数。
2. 让用户用自然语言提问面积问题。
3. 输出答案和一句适合学生理解的解释。

6.9 自测清单

• 我知道模型和函数各自负责什么吗？
• 我的函数参数清楚吗？
• 我有没有测试小数、负数或空输入？
• 我能解释为什么函数结果更可靠吗？