1. 项目背景与整体设计思路1.1 为什么要在 WMS 仓储系统里集成 AI Agent做过 WMS 的人都知道传统仓储系统的交互模式基本是“人找功能”——仓管员要查库存得点进库存模块要生成拣货波次得进波次管理要处理异常单得翻到异常处理页面。系统功能越堆越多菜单越做越深一线操作员的培训成本居高不下。我们这套 WMS 已经跑了三年多SKU 数量过了两万日均出库单量在旺季能到八千单以上操作员抱怨最多的不是系统慢而是“找不到功能”和“操作步骤太多”。集成 AI Agent 的核心动机就在这里把“人找功能”变成“人说需求Agent 调功能”。仓管员直接说“帮我查一下 A 区还有多少件 SKU-10234”Agent 解析意图后调用库存查询接口返回结果说“给今天下午的急单生成拣货波次”Agent 调用波次生成服务并返回波次号。这个思路听起来简单但落到生产环境问题全在并发和资源管理上。这一讲是终篇前面七讲分别覆盖了 Agent 的意图识别、工具注册、上下文管理、多轮对话、异常兜底、权限控制、灰度发布。到了生产部署这一步真正的硬骨头才露出来——并发安全。WMS 本身是高频并发系统Agent 作为新增的入口层如果并发处理不当轻则响应变慢重则拖垮整个仓储作业链路。1.2 技术选型为什么是 Spring AI Agent Reactor我们的 WMS 后端是 Spring Boot 体系Java 17所以 Agent 框架自然选了 Spring AI Agent 这条线。Spring AI 在 2025 年之后的版本对 Agent 的支持已经比较成熟工具调用、对话记忆、多模型适配都有现成抽象。更关键的是它天然构建在 Reactor 之上返回Mono和Flux这和我们 WMS 现有的响应式数据访问层能对上。选 Reactor 而不是阻塞式线程池理由很直接Agent 的一次完整调用链路里最耗时的部分是 LLM 推理通常 1 到 5 秒如果每个请求占一个线程200 个并发就把线程池打满了。用 Reactor 的非阻塞模型少量线程就能撑住高并发这是响应式编程的核心优势。但响应式带来一个经典陷阱副作用代码的执行时机。这也是这一讲标题里说的“Semaphore 放进 Flux.defer 的坑”的根源。我先把这个坑的结论放在这里Flux.defer里的代码在每次订阅时执行如果你把 Semaphore 的acquire放在defer外面信号量只获取一次放在里面每次订阅都获取一次但释放逻辑如果没对齐就会泄漏许可最终导致所有请求卡死。这个坑我们压测抓了整整一晚上。1.3 整体架构分层生产部署的架构分四层从外到内依次是接入层Nginx 做负载均衡后面挂两个 Agent 服务实例会话粘性通过 Redis 共享对话上下文实现不依赖 Nginx 的 sticky session。Agent 服务层Spring Boot 应用内部包含意图识别、工具路由、对话管理三个核心模块所有对外接口返回Mono或Flux。并发控制层这是本讲的重点用 Semaphore 限制同时进行的 LLM 调用数量用 Reactor 的Schedulers控制线程切换用Flux.defer保证副作用的正确时机。工具执行层Agent 调用的 WMS 内部服务包括库存查询、波次生成、异常处理等这些是阻塞式 JDBC 调用需要切换到Schedulers.boundedElastic()执行。这个分层的关键设计原则是Agent 服务层全程非阻塞只有工具执行层的阻塞调用才切线程。如果把 LLM 调用和工具调用混在同一个线程模型里并发一上来就会出现线程饥饿。2. 核心细节解析Semaphore 与 Flux.defer 的正确配合2.1 Semaphore 在 Agent 场景里到底限制什么先说清楚 Semaphore 在这里的作用。Agent 服务最贵的资源不是 CPU 也不是内存而是下游 LLM 服务的并发配额。我们用的是企业级 API有明确的 RPM每分钟请求数和并发连接数限制。如果不加控制高峰期几百个请求同时打过去要么被限流返回 429要么排队等到超时。Semaphore 的作用就是给 LLM 调用加一个“闸门”同时最多放 N 个请求过去。N 的取值需要算假设 LLM 单次调用平均耗时 2 秒我们希望每秒能处理 50 个 Agent 请求那么并发数 N 50 × 2 100。但实际要考虑 P99 耗时如果 P99 是 8 秒那 N 取 100 就意味着最坏情况下有 100 个请求各占 8 秒吞吐会掉到 12.5 QPS。所以我们的做法是 N 取 60配合请求排队超时超过 3 秒没拿到许可就返回“系统繁忙请稍后重试”保证用户体验。// 信号量初始化60 个许可公平模式 private final Semaphore llmSemaphore new Semaphore(60, true);公平模式fairtrue很重要。非公平模式下新来的请求可能插队到排队请求前面导致某些请求长时间饥饿。Agent 场景里用户对延迟敏感公平模式虽然吞吐略低但延迟分布更稳定。2.2 Flux.defer 的执行时机一个必须搞清楚的语义Flux.defer的语义是每次订阅时才创建 Flux 实例。这意味着defer里面的代码块每有一个订阅者就执行一次。这个特性用对了是利器用错了就是灾难。看一个错误示范// 错误写法Semaphore 在 defer 外面获取 public MonoString handleAgentRequest(String query) { return Mono.fromCallable(() - { llmSemaphore.acquire(); // 这里在组装阶段就执行了 return callLlm(query); }).subscribeOn(Schedulers.boundedElastic()); }这段代码的问题在于Mono.fromCallable里的acquire是在订阅时执行的看起来没问题。但如果外层还有一层Flux.defer包裹而acquire写在了defer外面那么每次订阅都会重新执行defer外面的代码导致许可被重复获取。正确的写法是把整个“获取许可 → 调用 → 释放许可”的完整生命周期都放在defer内部public MonoString handleAgentRequest(String query) { return Flux.defer(() - { // 每次订阅都重新走一遍获取-释放流程 return Mono.fromCallable(() - { if (!llmSemaphore.tryAcquire(3, TimeUnit.SECONDS)) { throw new AgentBusyException(系统繁忙); } try { return callLlm(query); } finally { llmSemaphore.release(); } }).subscribeOn(Schedulers.boundedElastic()); }).next(); }关键点tryAcquire带超时避免无限等待release放在finally里保证异常时也能释放整个逻辑包在defer里每次订阅独立执行。2.3 为什么不用 Reactor 自带的限流算子Reactor 有limitRate、onBackpressureBuffer等算子为什么不直接用因为它们的语义和 Semaphore 不一样。limitRate控制的是上游向下游发射元素的速率是背压机制不是并发控制。onBackpressureBuffer是缓冲策略不限制并发数。Semaphore 控制的是同时进行的操作数量这个语义在 Agent 场景里是刚需。而且 Semaphore 的tryAcquire带超时能实现“排队等 3 秒等不到就拒绝”的业务逻辑这是 Reactor 算子做不到的。注意Semaphore 的许可数量必须和下游 LLM 服务的实际并发能力匹配。设大了会被限流设小了吞吐上不去。建议先用压测工具测出 LLM 服务在目标延迟下的最大并发再留 20% 余量。2.4 线程切换的时机与陷阱Agent 请求的处理链路里线程切换有三次接入线程 → 业务线程Nginx 转发过来的请求由 Tomcat 的 IO 线程接收进入 Controller 后需要切到业务线程池。业务线程 → LLM 调用线程LLM 调用是阻塞的 HTTP 请求需要切到boundedElastic。LLM 调用线程 → 工具执行线程工具调用是阻塞的 JDBC同样需要boundedElastic。每次切换都有开销所以能合并的切换要合并。我们的做法是Controller 层直接返回Mono不切线程在defer内部一次性切到boundedElasticLLM 调用和工具调用都在这个线程上完成。这样整个链路只有一次线程切换。但这里有个坑boundedElastic的默认线程数是 CPU 核数 × 10。如果 Agent 请求里既有 LLM 调用又有工具调用且两者都阻塞那么线程占用时间会翻倍。我们的服务器是 16 核默认 160 个线程压测时发现 200 并发下线程池很快打满。解决办法是显式配置更大的线程池Scheduler agentScheduler Schedulers.newBoundedElastic( 300, // 最大线程数 100000, // 任务队列容量 agent-worker, 60, // 线程存活时间秒 true // 守护线程 );300 个线程对应 60 个 Semaphore 许可看起来线程数远大于许可数但这是故意的——因为工具调用不占 Semaphore 许可只有 LLM 调用占。工具调用的并发可能远高于 LLM 调用所以线程池要留足余量。3. 实操过程从压测到生产部署的完整记录3.1 压测环境搭建压测环境必须尽量贴近生产否则测出来的数据没意义。我们的配置是组件生产环境压测环境说明Agent 实例数21压测单实例数据乘以 2 估算CPU16 核16 核保持一致内存32G32G保持一致LLM 服务企业 API同企业 API 测试配额避免用 MockMock 测不出真实延迟WMS 数据库主从集群单机工具调用延迟会偏低需注意压测工具-JMeter 自定义 Java 客户端JMeter 对响应式接口支持一般自定义客户端更准压测工具的选择很关键。JMeter 默认是阻塞式请求模型测响应式接口时自身会成为瓶颈。我们最后用 Java 写了一个基于WebClient的压测客户端能精确控制并发数和请求速率。3.2 第一轮压测Semaphore 许可泄漏第一轮压测100 并发持续 5 分钟。前 30 秒一切正常QPS 稳定在 45 左右P99 延迟 3.2 秒。30 秒后 QPS 开始断崖式下跌到 1 分钟时 QPS 掉到 5 以下大量请求返回“系统繁忙”。看日志发现Semaphore 的可用许可数在持续减少最终归零。但代码里明明有finally块释放许可为什么会泄漏排查过程很痛苦。先怀疑是tryAcquire超时后没有正确释放检查代码发现超时抛异常后确实没进finally——因为tryAcquire返回 false 时直接抛了AgentBusyException而release写在try块里根本没执行到。// 有问题的写法 if (!llmSemaphore.tryAcquire(3, TimeUnit.SECONDS)) { throw new AgentBusyException(系统繁忙); // 这里抛出后下面的 try-finally 不会执行 } try { return callLlm(query); } finally { llmSemaphore.release(); }修正后的写法boolean acquired false; try { acquired llmSemaphore.tryAcquire(3, TimeUnit.SECONDS); if (!acquired) { throw new AgentBusyException(系统繁忙); } return callLlm(query); } finally { if (acquired) { llmSemaphore.release(); } }这个坑的教训是Semaphore 的 acquire 和 release 必须严格配对且 release 只在 acquire 成功时执行。用布尔标记位是最稳妥的写法。3.3 第二轮压测Flux.defer 导致的重复获取修完许可泄漏后第二轮压测。这次 QPS 稳定了但发现一个诡异现象Semaphore 的许可数在请求结束后没有完全恢复偶尔会少 1 到 2 个。而且并发越高泄漏越明显。抓了一晚上最后定位到Flux.defer的嵌套问题。我们的代码里有一层重试逻辑return Flux.defer(() - handleAgentRequest(query)) .retryWhen(Retry.backoff(2, Duration.ofMillis(500))) .next();retryWhen在重试时会重新订阅上游也就是重新执行Flux.defer里的代码。如果defer里的acquire和release没有严格配对重试一次就泄漏一个许可。更隐蔽的是retryWhen的重试是在同一个订阅链上发生的如果release写在defer外面重试时就不会重新acquire导致许可数对不上。最终方案是把重试逻辑也包进defer内部保证每次重试都是完整的“获取-调用-释放”循环return Flux.defer(() - { return Mono.fromCallable(() - { boolean acquired false; try { acquired llmSemaphore.tryAcquire(3, TimeUnit.SECONDS); if (!acquired) { throw new AgentBusyException(系统繁忙); } return callLlm(query); } finally { if (acquired) { llmSemaphore.release(); } } }) .subscribeOn(agentScheduler) .retryWhen(Retry.backoff(2, Duration.ofMillis(500)) .filter(e - e instanceof TimeoutException)); // 只对超时重试 }).next();注意retryWhen的filter只对超时异常重试不对AgentBusyException重试。因为系统繁忙时重试只会加重负担应该直接返回给用户。3.4 第三轮压测线程池打满与背压修完前两个问题第三轮压测。这次 Semaphore 工作正常但出现了新问题boundedElastic线程池在 200 并发下被打满新请求排队等待线程延迟飙升到 10 秒以上。分析线程 dump 发现大量线程卡在 JDBC 调用上。工具执行层的数据库查询没有走索引单次查询要 2 到 3 秒。60 个 LLM 许可对应的线程只占 60 个但工具调用不占许可200 个并发请求全部涌向工具执行线程池瞬间打满。解决办法有两个层面第一给工具调用也加并发控制。但不是用 Semaphore而是用 Reactor 的flatMap并发参数return Flux.fromIterable(toolCalls) .flatMap(tool - executeTool(tool) .subscribeOn(agentScheduler), 20) // 最多 20 个工具并发执行 .collectList();第二优化工具执行层的数据库查询。给库存查询的sku_id和warehouse_id加了联合索引单次查询从 2.3 秒降到 80 毫秒。这个优化比任何并发控制都有效。实操心得并发问题的根因往往不在并发控制本身而在下游服务的响应速度。先把下游优化到极致再考虑加并发控制顺序不能反。3.5 生产部署配置清单经过三轮压测最终的部署配置如下# application-prod.yml agent: semaphore: llm-permits: 60 # LLM 并发许可数 acquire-timeout-ms: 3000 # 获取许可超时 scheduler: max-threads: 300 # 业务线程池最大线程数 queue-capacity: 100000 # 任务队列容量 retry: max-attempts: 2 # 最大重试次数 backoff-ms: 500 # 重试退避基数 tool: max-concurrent: 20 # 工具并发执行数JVM 参数-Xms16g -Xmx16g -XX:UseG1GC -XX:MaxGCPauseMillis200 -XX:ParallelGCThreads8 -XX:ConcGCThreads4G1GC 的MaxGCPauseMillis设 200 毫秒是因为 Agent 请求对延迟敏感超过 200 毫秒的 GC 停顿会导致 P99 延迟明显上升。实测下来16G 堆内存下 G1 的停顿基本能控制在 150 毫秒以内。4. 常见问题与排查技巧实录4.1 并发问题速查表现象可能原因排查方法解决方案QPS 逐渐下降至零Semaphore 许可泄漏打印可用许可数观察是否持续减少检查 acquire/release 配对用布尔标记位重试后许可数对不上Flux.defer 嵌套导致重复获取在 defer 内外打日志对比执行次数把重试逻辑包进 defer 内部延迟飙升但 CPU 不高线程池打满请求排队jstack 看线程状态统计 WAITING 线程数扩大线程池或加工具并发控制部分请求永远超时信号量公平模式下的饥饿打印每个请求的等待时间分布改用公平模式或缩短 acquire 超时压测结果波动大下游 LLM 服务不稳定单独压测 LLM 接口看 P99 波动加熔断降级或调整许可数4.2 日志与监控的关键指标生产环境必须监控的指标Semaphore 可用许可数低于 10 时告警说明并发接近上限。acquire 等待时间 P99超过 1 秒说明许可数偏少或下游变慢。boundedElastic 活跃线程数超过最大线程数的 80% 时告警。LLM 调用 P99 延迟超过 5 秒时检查 LLM 服务状态。工具调用 P99 延迟超过 500 毫秒时检查数据库慢查询。这些指标用 Micrometer 暴露到 PrometheusGrafana 做面板。我们踩过的坑是一开始只监控了 QPS 和错误率没有监控 Semaphore 许可数导致许可泄漏了半小时才发现。4.3 独家避坑技巧技巧一用tryAcquire而不是acquire。acquire会无限阻塞一旦下游卡死所有线程都会挂起。tryAcquire带超时超时后返回“系统繁忙”用户体验反而更好。技巧二Semaphore 的 release 一定要在 finally 里且用布尔标记位。这是用血泪换来的教训前面已经详细说过。技巧三压测时用真实的下游服务。Mock 的下游延迟是固定的测不出真实场景下的延迟抖动。我们第一轮压测用 Mock结果一切正常上生产就崩了。技巧四重试策略要区分异常类型。超时可以重试系统繁忙不能重试业务异常更不能重试。用filter精确控制。技巧五线程池大小要算不要拍脑袋。公式是线程数 并发数 × 平均耗时 / 目标响应时间。但实际要考虑 P99 耗时和阻塞比例建议先用小并发压测逐步增加观察线程池活跃数。4.4 一个容易被忽略的细节信号量的公平性Semaphore 的公平模式fairtrue和非公平模式在低并发下差异不大但在高并发下差异明显。非公平模式下新来的请求可能插队导致排队中的请求饥饿。我们实测下来非公平模式的 P99 延迟比公平模式高 40% 左右因为部分请求等了很久都拿不到许可。但公平模式也有代价吞吐量比非公平模式低约 10%。因为公平模式需要维护一个 FIFO 队列每次 release 都要唤醒队首线程有额外的上下文切换开销。选择建议如果业务对延迟分布敏感比如 Agent 交互场景用公平模式如果追求极致吞吐比如批量任务用非公平模式。5. 生产环境的灰度与回滚策略5.1 灰度发布方案Agent 服务上线不能一刀切必须灰度。我们的灰度策略是按仓库维度切流先在一个仓库试点观察一周没问题再扩到三个仓库最后全量。灰度期间重点观察的指标Agent 请求的成功率和 P99 延迟对比非 Agent 入口的基线。Semaphore 许可数的波动范围确认没有泄漏。工具调用的错误率确认 Agent 调用的工具和非 Agent 调用的工具行为一致。用户反馈特别是一线操作员的使用体验。灰度切流用 Nginx 的split_clients实现按仓库 ID 做哈希保证同一仓库的请求始终走同一个版本。5.2 回滚触发条件定义明确的回滚触发条件避免犹豫Agent 入口的错误率超过 5%持续 5 分钟。P99 延迟超过 10 秒持续 3 分钟。Semaphore 可用许可数持续 10 分钟低于 5。出现任何数据一致性问题比如 Agent 生成的波次和手动生成的波次冲突。回滚操作要一键化我们写了一个脚本执行后 30 秒内完成流量切换。回滚后 Agent 服务不停止继续接收少量影子流量方便排查问题。5.3 生产环境的一个真实故障上线第二周周五下午出过一次故障。现象是 Agent 入口的 QPS 突然掉到接近零但非 Agent 入口正常。查日志发现 Semaphore 许可数归零且没有恢复。根因是 LLM 服务的一次网络抖动导致一批请求的callLlm抛出了IOException。我们的代码里finally块正确释放了许可但有一批请求在tryAcquire成功后、进入try块之前线程被中断了因为 Tomcat 的请求超时机制导致finally没执行。修复方案是在tryAcquire和try块之间不留任何可能抛异常的代码boolean acquired false; try { acquired llmSemaphore.tryAcquire(3, TimeUnit.SECONDS); if (!acquired) { throw new AgentBusyException(系统繁忙); } // 这里直接进入业务逻辑不留空隙 return callLlm(query); } finally { if (acquired) { llmSemaphore.release(); } }这个故障的教训是并发控制的代码要尽可能紧凑acquire 之后立刻进入 try 块中间不要有任何可能被中断的操作。6. 性能优化后的最终压测数据经过三轮压测和优化最终的压测数据如下并发数QPSP50 延迟P99 延迟错误率Semaphore 可用许可50480.8s2.1s0%12-15100521.2s3.5s0%5-10200552.1s6.8s0.3%0-3300543.5s12.4s2.1%0200 并发是拐点超过后 P99 延迟明显上升错误率增加。生产环境的容量规划按 200 并发设计两个实例合计支撑 400 并发对应约 110 QPS满足旺季峰值需求。对比优化前的数据第一轮压测 100 并发时 QPS 只有 45P99 延迟 8 秒错误率 15%。优化后 QPS 提升 15%P99 延迟降低 56%错误率降到 0。7. 后续可扩展的方向这套并发控制框架不只适用于 Agent 场景。我们后来把它抽象成了一个通用的“下游资源保护”组件任何需要限制并发调用的场景都可以复用比如批量导入、报表生成、消息推送。另一个扩展方向是动态调整 Semaphore 许可数。目前许可是静态配置的但下游 LLM 服务的容量可能随时间变化。可以结合监控数据用定时任务动态调整许可数延迟低时增加许可延迟高时减少许可。这个思路类似 TCP 的拥塞控制我们还在试验阶段效果好的话后续再分享。最后分享一个我在这次压测里体会最深的点响应式编程的调试难度远高于阻塞式编程。阻塞式代码里线程栈能直接告诉你卡在哪里响应式代码里一个Flux链可能跨越多个线程异常栈信息经常不完整。我的建议是在关键的defer、subscribeOn、flatMap节点都打上带请求 ID 的日志压测时用请求 ID 串联整条链路否则排查问题真的会抓瞎。那一晚上抓 Semaphore 泄漏如果没有请求 ID 日志可能还要再抓一晚。