🎯 今日核心问题

  1. 模型一次返回 3 个 tool_call,怎么判断哪些能并行、哪些必须串行?
  2. 并行执行时 TraceId、ThreadLocal、SecurityContext 为什么会丢?怎么传下去?
  3. 并行调用里一个失败,其余的结果要不要保留?怎么回填给模型?
  4. 模型自己不擅长"先查订单再查物流"这种依赖链,要不要替它编排?

📖 精读提纲

【一】并行是模型发起的,串行是协议强制的

当请求里开启 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 组合好——能用代码固化的依赖,就别交给模型,稳定性和延迟都更好。

【四】常见误区

💻 代码示例

按 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,跑通"问一个问题 → 并行查 → 汇总回答"的全链路,并给出下一周(多步推理与规划)的路线。