🎯 今日核心问题
- 模型一次返回 3 个 tool_call,怎么判断哪些能并行、哪些必须串行?
- 并行执行时 TraceId、ThreadLocal、SecurityContext 为什么会丢?怎么传下去?
- 并行调用里一个失败,其余的结果要不要保留?怎么回填给模型?
- 模型自己不擅长"先查订单再查物流"这种依赖链,要不要替它编排?
📖 精读提纲
【一】并行是模型发起的,串行是协议强制的
当请求里开启 parallel_tool_calls(默认开启),模型可以在一条 assistant 消息里返回多个 tool_calls,比如"查 A123 的订单、查 B456 的物流、查当前时间"——这三件事互不依赖,天然可并行,串行执行等于白白叠加延迟。但有依赖的调用,模型无法在同一个响应里发起:查物流需要先拿到订单号,而订单号要等第一个工具返回,所以必须跨轮。协议层面这就决定了:同一响应内的 tool_calls 是并行候选,跨轮的一定是依赖关系。你不需要(也不应该)自己去推断依赖,只要按批次执行、把全部结果回填,模型自然会发下一轮。
【二】并行执行的三个工程陷阱
陷阱一:ThreadLocal 丢失。RequestContextHolder、MDC 的 traceId、SecurityContext 都绑定在请求线程上,丢进线程池就没了。解决方式是在主线程抓一份上下文快照(traceId、userId、tenantId),在子线程开头用 MDC.put / 显式参数恢复,结束清理。陷阱二:事务与连接池。工具方法别在大事务里跑并发,每个并发任务会各自占用连接;能并行执行的通常是查询,把它们放在 NOT_SUPPORTED 传播级别最安全。陷阱三:部分失败。不要用 CompletableFuture.allOf 直接 join——一个失败就整体抛异常,其余成功的结果全丢。正确做法是每个 future 各自兜住异常,转成 ToolResult.fail,最后每个 tool_call_id 都必须有一条对应的 tool 消息回填,缺一条模型就会报错或自行编造结果。
【三】实战应用:Spring Boot 场景
典型链路:模型说"帮我看看 A123 能不能退,顺便看看 B456 到哪了,今天几号"。响应含三个 tool_call:getOrderDetail、getShippingTrace、getCurrentTime。AgentService 把它们提交到 ExecutorService,主线程按 tool_call_id 收集结果,拼成三条 ToolExecutionResultMessage,一次性发起第二轮请求。如果业务上确实需要固定的多步依赖(比如"每次查订单都要顺带补一次用户等级"),不要把逻辑塞进 prompt 让模型去连,而是在工具内部直接调用另一个 Service 组合好——能用代码固化的依赖,就别交给模型,稳定性和延迟都更好。
【四】常见误区
- ❌ 用
parallelStream()跑工具——共享 ForkJoin 池,容易被慢 IO 阻塞,还会干扰其他并行流。 - ❌ 并行结果按数组顺序回填而不按
tool_call_id——顺序错乱后模型会把物流结果当成订单结果。 - ❌ 有依赖的调用也强行并行——拿不到前置结果,参数只能是猜的。
- ❌ 为了"稳"全部串行——3 个 800ms 的独立查询变成 2.4s,用户能明显感到卡顿。
💻 代码示例
按 tool_call_id 收集、单点失败不影响全局的并行执行器:
@Service
@Slf4j
public class ParallelAgentService {
private final ChatModel model;
private final ToolExecutor executor;
private final ObjectMapper mapper;
private final ExecutorService pool = Executors.newFixedThreadPool(8);
public String chat(String sessionId, String userText, String traceId) {
List<ChatMessage> messages = new ArrayList<>(List.of(
SystemMessage.from("你是订单助手,需要事实时调用工具,不要编造。"),
UserMessage.from(userText)));
for (int round = 0; round < 5; round++) {
ChatResponse resp = model.chat(ChatRequest.builder()
.messages(messages).toolSpecifications(allSpecs()).build());
AiMessage ai = resp.aiMessage();
messages.add(ai);
List<ToolExecutionRequest> calls = ai.toolExecutionRequests();
if (calls == null || calls.isEmpty()) return ai.text();
// 同一响应内的调用彼此独立 → 并行提交
Map<String, CompletableFuture<String>> futures = new LinkedHashMap<>();
for (ToolExecutionRequest call : calls) {
futures.put(call.id(), CompletableFuture.supplyAsync(
() -> runWithContext(call, sessionId, traceId), pool));
}
// 按 tool_call_id 回填,顺序与模型发起的顺序一致
for (ToolExecutionRequest call : calls) {
String payload;
try {
payload = futures.get(call.id()).get(5, TimeUnit.SECONDS);
} catch (Exception e) {
payload = "{\"ok\":false,\"code\":\"PARALLEL_FAILED\",\"message\":\"并行执行失败\"}";
}
messages.add(ToolExecutionResultMessage.from(call, payload));
}
}
return "抱歉,我需要更多信息才能继续。";
}
/** 子线程恢复 MDC,否则日志里的 traceId 全丢 */
private String runWithContext(ToolExecutionRequest call, String sessionId, String traceId) {
MDC.put("traceId", traceId);
MDC.put("sessionId", sessionId);
MDC.put("tool", call.name());
try {
CallContext ctx = new CallContext(3_000);
return executor.execute(call.name(), call.arguments(), ctx);
} finally {
MDC.clear();
}
}
}
依赖调用由代码固化,工具内部组合,不让模型去连:
@Component
@RequiredArgsConstructor
public class CompositeTools {
private final OrderRepository orderRepo;
private final UserClient userClient;
/** 一次调用返回订单 + 用户等级,省掉模型发起的第二轮 */
@Tool("查询订单详情,同时带回下单用户的会员等级(用于判断运费/售后特权)")
public ToolResult<OrderWithLevel> getOrderWithUserLevel(
@P("订单号,形如 A123") String orderNo) {
Order o = orderRepo.findByOrderNo(orderNo).orElse(null);
if (o == null) return ToolResult.fail("ORDER_NOT_FOUND", "未找到订单 " + orderNo);
// 依赖调用在服务端完成,可并行也可串行,由代码决定
Level lv = userClient.levelOf(o.getUserId()); // 内部已有超时与降级
return ToolResult.ok(new OrderWithLevel(o.getOrderNo(), o.getStatusLabel(),
lv.name(), lv.freeShippingThreshold()), "订单已查,会员等级 " + lv.name());
}
}
/** 若两个依赖可并行,用 CompletableFuture 组合,主线程最后 join */
public OrderWithLevel loadParallel(String orderNo) {
CompletableFuture<Order> orderF = CompletableFuture.supplyAsync(
() -> orderRepo.findByOrderNo(orderNo).orElseThrow(), pool);
CompletableFuture<Level> levelF = orderF.thenComposeAsync(
o -> CompletableFuture.supplyAsync(() -> userClient.levelOf(o.getUserId()), pool));
return orderF.thenCombine(levelF, (o, lv) -> new OrderWithLevel(
o.getOrderNo(), o.getStatusLabel(), lv.name(), lv.freeShippingThreshold())).join();
}
一次真实的并行响应体(第一轮请求返回):
{
"choices": [{
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{"id": "call_01", "type": "function",
"function": {"name": "getOrderDetail", "arguments": "{\"orderNo\":\"A123\"}"}},
{"id": "call_02", "type": "function",
"function": {"name": "getShippingTrace", "arguments": "{\"orderNo\":\"B456\"}"}},
{"id": "call_03", "type": "function",
"function": {"name": "getCurrentTime", "arguments": "{\"zone\":\"Asia/Shanghai\"}"}}
]
}
}],
"usage": {"prompt_tokens": 812, "completion_tokens": 96, "total_tokens": 908}
}
✏️ 今日动手
1)给三个独立工具各加 800ms 延迟,先用串行跑一次记录总耗时,再改成并行,对比数字(应接近 800ms 而非 2400ms)。
2)让其中一个工具抛异常,验证其余两个结果仍然回填、模型能基于部分结果给出回答,并明确说明哪一项失败了。
3)把 MDC 恢复逻辑注释掉,观察日志中 traceId 变成 -,再把恢复逻辑加回来确认恢复——这个坑几乎所有初学者都踩过。
4)构造依赖链问题:"查 A123 的订单,然后根据它的订单号查物流",观察模型需要几轮完成,再对照 getOrderWithUserLevel 这类组合工具,比较轮数与延迟。
🔖 明日预告
本周收官:把 5 个工具(查数据库、调 HTTP、读文件、算数、查时间)组装成一个完整 Agent,跑通"问一个问题 → 并行查 → 汇总回答"的全链路,并给出下一周(多步推理与规划)的路线。