🎯 今日核心问题

  1. 模型"调用函数"到底是什么动作?它真的执行代码了吗?
  2. 一次完整的工具调用,HTTP 请求体里到底长什么样、返回体里又长什么样?
  3. 模型凭什么在 20 个工具里选中某一个?是关键词匹配还是有别的机制?
  4. 为什么后端必须在 tool_call 返回后自己再发一轮请求,而不能一次拿到答案?

📖 精读提纲

【一】"调用"的真相:模型只输出 JSON,绝不执行代码

这是必须彻底纠正的第一个认知。模型在 function calling 中做的事只有一件:生成一段符合协议的结构化文本。它不知道你的 OrderService 存在,也不能访问数据库。所谓工具调用,其实是三方协作:你(服务端)把工具清单塞进请求 → 模型返回 tool_calls 数组 → 你解析参数、反射执行本地方法 → 把结果作为 role=tool 的消息再发回去 → 模型基于结果继续推理或给出最终答案。所以整条链路至少是两次模型请求,中间夹着一次你的本地执行。理解了这一点,后面所有"参数错、超时、幻觉工具名"的问题都能定位到具体环节:参数错在模型生成阶段,超时在执行阶段,幻觉工具名在注册阶段。

再往深一层:模型是怎么"决定"的?它其实是在做受约束的文本生成。提供商在推理时把工具 schema 转成一段特殊格式的上下文(有的模型走专门的训练通道,有的只是在 system 里塞一段"可用函数列表"),然后约束输出要么是普通文本,要么是符合 function-call 语法的 JSON。也就是说,工具选择的本质是基于描述的语义匹配——模型把用户意图和你写的 description 做相似度判断,而不是执行某个规则引擎。这个结论直接推出 D2 的核心:描述写得准,命中率才高。

【二】完整链路:请求 → tool_calls → 执行 → 回填 → 最终答案

一次真实的两轮交互如下。第一轮请求里带 tools 数组,模型不返回 content,而是返回 finish_reason: "tool_calls";第二轮请求把 assistant 的 tool_calls 消息原样带上,追加一条 {"role":"tool","tool_call_id":"call_xxx","content":"..."},模型才给出自然语言答案。tool_call_id 是配对的关键,漏传或改错会导致模型报协议错误,或者更糟——把结果错配到另一个调用上。在 Spring Boot 里这一层通常抽象成 AiServices,但你必须能手写这层,否则出问题只能靠猜。

第一轮请求的关键字段:tools(工具清单,每轮都要带,模型不记忆)、tool_choice(auto / required / 指定函数名)、parallel_tool_calls(是否允许一次返回多个)。模型返回的 tool_calls[].function.arguments 是字符串形式的 JSON,不是对象——这是第一次解析时最容易踩的坑。参数很长时(比如要传一段 SQL)模型可能生成不合法 JSON,所以生产环境必须在反序列化处捕获异常并回填"参数格式错误"让它重试(D5 展开)。

【三】实战应用:Spring Boot 场景

考虑一个订单助手:用户说"帮我看下 A123 这个订单还能不能退"。Controller 暴露 POST /api/agent/chat,Service 里组装工具清单并调用模型,模型返回 getOrderDetail(orderNo="A123"),Service 反射调用 Repository 拿到订单行,把 {"status":"SHIPPED","shippedAt":"2026-10-20","refundable":false,"reason":"已超过7天无理由"} 回填,模型据此组织话术。注意分层职责:Controller 只做协议转换,Service 负责编排循环,Repository 不感知 Agent 的存在。工具方法的入参必须是可序列化的 DTO,返回值要稳定可控——这两点在 D2、D4 展开。

【四】常见误区

💻 代码示例

下面是不依赖框架、手写一轮 function calling 的核心代码,先看清协议本身再看框架抽象:

@Service
@RequiredArgsConstructor
public class RawFunctionCallService {

    private final ChatModel chatModel;      // LangChain4j 的底层模型对象
    private final OrderRepository orderRepo;

    /** 第一轮请求体中的 tools 数组(节选) */
    private static final String TOOLS_JSON = """
        [{
          "type": "function",
          "function": {
            "name": "getOrderDetail",
            "description": "根据订单号查询订单状态、发货时间与是否可退",
            "parameters": {
              "type": "object",
              "properties": {
                "orderNo": { "type": "string", "description": "订单号,形如 A123" }
              },
              "required": ["orderNo"]
            }
          }
        }]
        """;

    public String ask(String userText) {
        // ── 第 1 轮:模型只返回 tool_calls,不产生文本
        ToolExecutionResult r1 = chatModel.executeToolCalls(userText, TOOLS_JSON);

        // ── 本地执行:这里才是真正的"函数调用"
        Object payload;
        if ("getOrderDetail".equals(r1.name())) {
            Order o = orderRepo.findByOrderNo(r1.arg("orderNo", String.class));
            payload = Map.of(
                "status", o.getStatus(),
                "shippedAt", o.getShippedAt().toString(),
                "refundable", o.isRefundable(),
                "reason", o.refundReason()
            );
        } else {
            payload = Map.of("error", "unknown tool: " + r1.name());
        }

        // ── 第 2 轮:把 tool 消息回填,模型给最终答案
        return chatModel.followUpWithToolResult(r1.toolCallId(), payload);
    }
}

同一件事用 LangChain4j 的 AiServices 做,声明式得多,但链路完全一致:

public interface OrderAssistant {
    @SystemMessage("你是订单客服,回答前必须先查订单事实,不要凭猜测回答。")
    String chat(@UserMessage String question);
}

@Configuration
class AssistantConfig {
    @Bean
    OrderAssistant orderAssistant(ChatModel model, OrderTools tools) {
        return AiServices.builder(OrderAssistant.class)
                .chatModel(model)
                .tools(tools)               // 注册后自动生成 schema 并执行回填
                .build();
    }
}

@Component
@RequiredArgsConstructor
class OrderTools {
    private final OrderRepository repo;

    @Tool("根据订单号查询订单状态、发货时间与是否可退")
    public OrderView getOrderDetail(@P("订单号,形如 A123") String orderNo) {
        return OrderView.from(repo.findByOrderNo(orderNo));
    }
}

✏️ 今日动手

1)把上面的 TOOLS_JSON 和用户问题"帮我看下 A123 还能不能退"发一次真实请求(curl 或 WebClient),把返回体原样保存成 round1.json,确认 finish_reason 是 tool_calls、content 为空。

2)手工拼装第二轮请求,把 tool_call_id 原样带回,观察模型如何基于你给的 JSON 组织话术;再故意把 tool_call_id 改成一个不存在的值,记录报错信息。

3)对照跑一次 AiServices 版本,打开 logging.level.dev.langchain4j=DEBUG,把框架打印的两轮请求体和你的手写版逐字段比对,找出框架替你补了哪些字段(提示:tool_choice、parallel_tool_calls、system 消息包装)。

🔖 明日预告

今天你看到了 description 和 parameters 是模型唯一的"使用说明书"。明天专攻工具描述(Schema)的写法:为什么同一个方法,换一句 description 命中率就从 40% 涨到 95%,以及 8 个把模型逼疯的 schema 反模式。