🎯 今日核心问题
- 模型"调用函数"到底是什么动作?它真的执行代码了吗?
- 一次完整的工具调用,HTTP 请求体里到底长什么样、返回体里又长什么样?
- 模型凭什么在 20 个工具里选中某一个?是关键词匹配还是有别的机制?
- 为什么后端必须在 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 展开。
【四】常见误区
- ❌ 以为模型"记住"了工具结果,下一轮对话不用带历史——结果必须作为消息进入上下文,否则模型完全不知道查过什么。
- ❌ 把业务逻辑写进工具方法里(比如在
getOrderDetail里直接抛 BusinessException)——工具方法应该返回数据,判断留在 Service 或用返回值表达失败。 - ❌ 认为
tool_choice能"强制"模型一定调对工具——它只能强制"必须调用某个工具",选错仍然是选错。
💻 代码示例
下面是不依赖框架、手写一轮 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 反模式。