做 Agent Platform 开发这半年我最难忘的不是功能上线而是某个下午线上超时故障爆发时的无力感。当时平台已经稳定运行了两周P99 延迟稳定在 200ms 左右结果一个再普通不过的需求变更后监控面板突然全红超时率直线上升客户端重试像海浪一样一层层压回来。今天想把这个过程完整写下来从告警表象一直拆到协程栈里的等待链再到最终的超时治理方案。如果你也在做 Agent 编排类服务或者写过异步后端这篇文章应该能帮你少踩几个类似的坑。先说结论这次故障不是某个下游服务挂了也不是网络抖动而是我们在设计 Agent Platform 的执行模型时忽略了“整体请求超时”和“资源池隔离”把一个本可以快速失败的慢请求放大成了全平台雪崩。整个排查过程很有意思也很折磨人我把关键证据、定位思路和修复细节都整理在下面。1. 我所在的 Agent Platform 到底承担了什么职责1.1 它不是简单的 API 转发层我们内部代号 Agent Platform表面上是一个 HTTP 接口服务但实际职责比“转发”重得多。它要管理一组 Agent 实例的注册与调度维护会话级上下文编排多步推理流程还要在每一步调用不同的工具模型推理服务、知识库检索、搜索接口、内部业务系统。业务方只需要把用户问题传进来平台会负责拆解任务、选择 Agent、调用工具、汇总结果最后再返回给调用方。所以从调用链路看一次用户请求到达平台后可能内部要串行或并行执行多轮调用。典型链路是这样客户端请求先进 API 网关网关转发给 Agent Platform 的 OrchestratorOrchestrator 先调用 LLM 网关做意图识别再根据计划调知识库和业务工具最后把结果拼装返回。每一步都会产生额外的网络 RTT 和延迟任何一环变慢整个响应时间就会被拉上去。这个架构本身不复杂但它给所有后端工程师提了个醒Agent 平台和普通 CRUD 服务最大的区别在于一次用户请求对应着多次下游依赖调用而且这些调用是长尾、不可控的。你用服务本身的快慢去衡量健康度往往失真真正要盯的是“一次编排里最慢的那个外部调用”。1.2 技术选型和埋下的隐患我们用的是 Python FastAPI路由层用 async def 写下游 HTTP 调用统一走 httpx.AsyncClient长时间任务通过任务队列给 Worker 消费。进程内用 asyncio.Semaphore 控制并发上限防止下游被突发流量打爆单次下游调用的超时时间设了 30 秒重试策略做了 1 次。这套设计在上线初期看起来没什么问题。异步模型天然适合 I/O 密集型场景信号量也确实能限制最大并发。但我后来才意识到这里有两个隐蔽的坑第一个坑是“只给下游调用设了超时没给整个请求链路设超时”。假设一次 Agent 编排需要串行调用 3 次下游每次下游最多等 30 秒那么一次用户请求理论上最长可能要等 90 秒。可客户端一般只愿意等 10 秒甚至 5 秒于是大量请求在客户端侧直接断开而服务端还在傻等下游返回。第二个坑是信号量虽然是全局的但它保护的是“同时在跑的协程数”而不是“等待的总工作量”。慢请求会长时间占着信号量新请求只能排队排队时间一长客户端的等待时间就爆炸了。后来压测时我测算过只要下游出现 5% 的慢调用系统整体吞吐会掉到原来的十分之一都不到。这个数学模型当时没建等线上出事才回头补上。2. 故障先行线上告警和我的第一反应2.1 监控面板上那些刺眼的数字那天下午的故障不是瞬间发生的是逐步恶化的。最早的告警来自平台自身“HTTP 500 比例超过阈值”然后紧接着是网关告警“上游响应超时率偏高”。我打开监控面板时情况已经比较惊人了指标故障前近 7 天均值故障开始后 30 分钟P99 响应时间180ms8.5sP95 响应时间120ms3.2s错误率5xx4xx0.1%18%服务进程 CPU35%38%下游 LLM 网关平均延迟450ms470ms平台内信号量等待队列长度0持续 400看到 CPU 不高、下游延迟也正常我当时第一反应是“入口流量是不是突然暴涨了”。但打开流量曲线后发现请求量只比平时高了约 20%远远不足以解释错误率涨了 180 倍。这个矛盾点很重要服务不忙下游不慢请求却在超时那很大概率是内部排队了。2.2 服务端日志里的“等锁”痕迹我们当时的日志体系比较基础应用打点 访问日志 错误日志。翻错误日志时发现一个规律大量请求的返回时间不是集中在某个点而是非常均匀地分布在 5 秒、10 秒、30 秒这几个整点。5 秒是客户端网关的默认读超时10 秒是业务侧设置的等待阈值30 秒是我们给下游设的单次调用超时。这说明什么说明很多请求根本没走完正常的 Agent 编排流程而是卡在了某个等待环节最后是被外部机制强杀掉的。再往应用日志里挖能看到大量这样的行“waiting for semaphore, acquired100, waiting87”。也就是说并发许可已经占满了后续请求全部在排队等信号量。还有一个细节让我至今难忘服务 CPU 只有 38%内存也很正常但大量协程卡在信号量获取上。纯异步应用出现这种“低资源占用、高延迟”的现场基本可以断定是并发模型出了问题不是计算资源不够。2.3 用户视角的雪崩链条为了搞清楚影响范围我让前端同事模拟了一个真实用户操作。用浏览器直接请求 Agent Platform结果是请求发出去后转圈直到浏览器侧报 ERR_EMPTY_RESPONSE。再用 curl 带超时参数测发现只要超过 3 秒没有响应就会自动断开断开前收到的数据为空。从调用方的角度看这个现象特别像平台已经挂死。但其实平台还活着只是拿不出新的并发名额来处理请求。因为每个新请求最先进入 Orchestrator 时第一步就是获取信号量信号量被慢请求占住新请求就一直停在 acquire 上连后续的下游调用都不会发起。这已经形成了雪崩雏形慢请求占住信号量不释放新请求排队等待排队的请求又占用着 HTTP 连接和协程网关收到的连接越来越多最终不可避免地把入口也拖死。3. 排查链条从网关到协程栈逐层剥离3.1 先排除网络和网关的嫌疑故障排查最忌讳一上来就怀疑某一段具体代码我习惯先从入口往出口一层层剥。第一层是 API 网关检查网关转发耗时和上游连接数。结果显示网关到平台的 TCP 连接正常连接建立时间稳定在 5ms 以内网络层面没有丢包。网关把请求转发给应用后等待应用响应的时间非常久说明问题在应用侧不在入口网络。第二层是平台所在服务器的系统资源。用 uptime、free、top 看了一眼load average 只有 0.8内存余量充足磁盘 I/O 也没波动。CPU 每个核的使用率最多 45%没有出现单核打满的迹象。系统级排障基本结束接下来只能往应用层和代码层走。3.2 用 py-spy dump 看协程到底卡在哪异步应用有个好处是可以直接抓协程栈。我在一台出问题的实例上执行了 py-spy dump --pid 输出的结果里大量协程停在同一段代码上。典型栈长这样Task_1234 (coroutine...) File ./orchestrator.py, line 186, in run_agent await lock.acquire() File ./orchestrator.py, line 88, in acquire_slot await self._semaphore.acquire()一眼望过去几乎所有协程都阻塞在信号量 acquire 上只有少数协程真正在跑下游 HTTP 请求。这个证据基本把范围锁定到了两个方向要么信号量容量太小要么单个请求持有信号量的时间太长。我后来算了一下我们的信号量容量是 100如果每个请求都在 100ms 内结束100 并发足够支撑每秒 1000 个请求。但 Agent 编排请求平均持有信号量的时间是 800ms个别请求达到 30 秒。容量的确够小但真正致命的是“持有时间”出现长尾。3.3 复现实验并发度加到多少会崩既然证据指向信号量我就写了个压测脚本模拟线上请求对平台发起了阶梯式并发压测。脚本做的很简单用 aiohttp 并发请求 Agent Platform 的编排接口每个请求内再让 Orchestrator 调用一个 mock 下游服务mock 服务故意对 5% 的请求加 20 秒延迟。压测结果非常清晰并发 50 时P99 约 400ms一切正常。并发 80 时P99 涨到 1.2s少量请求开始等待。并发 100 时P99 直接跳到 9.8s错误率开始飙升。并发 120 时几乎所有请求都超时错误率超过 50%。这个实验把“慢请求 满容量信号量 雪崩”的等式钉死了。即使下游慢调用只占 5%一旦整体并发触顶系统就会完全丧失快速失败的能力。3.4 在下游找不到根因却在自家配置里找到了压测验证的同时我还让同事去查下游 LLM 网关的日志。结果发现一个特别微妙的现象某个时间点起LLM 网关确实出现了一点毛刺极少数请求耗时达到 28 秒但占比只有 2%-3%。这种现象在正常波动范围内谈不上故障。坏就坏在我们对下游毛刺的容忍度是 0。一个 28 秒的慢请求会占住一个信号量名额长达 28 秒。假设系统每秒新进来 60 个请求每个请求平均持有信号量 800ms稳态需要 48 个并发剩余 52 个名额本来可以应对毛刺但慢请求如果批量出现52 个名额很快被耗尽所有新请求开始排队。而排队中的请求又不会主动退出只是在等锁这等于把“延迟问题”变成了“资源耗尽问题”。所以最后定位到的根因其实是一个组合拳下游确有少量慢请求但我们没有为不同下游隔离资源也没有给整体请求设置最终超时还没做快速失败。这三件事单独看都不算什么合在一起就成了事故。4. 根因复盘一次 28s 的慢请求如何堵死整个平台4.1 “整体无超时”让上限失去了意义很多人会争论我们明明给 httpx 客户端的每个请求设置了 30 秒超时为什么还说无超时关键就在这里你给单个下游调用设置超时并不代表整条编排链路有终止时间。一个用户请求可能要先调意图识别再调知识库再调任务执行 Agent这三步串行加起来最坏可能 90 秒。线上客户端不会等 90 秒网关默认读超时是 5 秒应用侧最外层也设了 10 秒。于是服务端和客户端对“一个请求到底能跑多久”的理解完全不一致。客户端 5 秒就断了服务端还在跑 30 秒的下游调用下游最终返回了平台却想把结果回写给一个根本不存在的连接只能产生异常。这些“孤儿请求”虽然没有用户接收但它们同样占着信号量同样消耗资源。所以这次事故后我们把“链路总超时”列为第一优先级而且要求必须比外部超时更短。宁可让请求快速失败也不允许让请求在系统里多活一秒钟。4.2 全局共享信号量的放大效应信号量本身是好东西它避免了无脑打到下游。但全局共享一个信号量会让不同下游、不同业务性质的任务互相拖累。设想一下A 类任务主要调内部搜索服务B 类任务主要调 LLM 网关。如果某一天 LLM 网关变慢全局信号量会被 B 类任务占满A 类任务虽然依赖完全正常也会被连坐拿不到许可。更细节的放大效应来自 Agent 编排的特点一个编排任务内部可能会并行发起多个下游调用每个调用都要获取信号量。假设我们用信号量限制“同时调用下游的次数”而不是“同时执行的 Agent 任务数”那么每个任务实际占用的名额可能不止一个达到 3-4 个。并发上限看似 100实际最多只能容纳 30 个任务同时运行系统的真实吞吐远低于设计值。我用一个很简单的模型解释这次事故系统每秒到达 50 个请求平均每个请求需要持有信号量的时间是 0.5 秒那么稳态需要的并发数是 25信号量 100 时非常宽裕。但下游毛刺出现后2% 的请求持有时间变成 20 秒平均持有时间从 0.5 秒变成 0.5 * 0.98 20 * 0.02 0.89 秒稳态并发需求涨到 45还没事。如果慢请求占比涨到 5%平均持有时间变成 1.475 秒稳态并发需求变成 74已经接近上限再叠加到达率高峰系统立刻进入排队状态。排队时间等于队列长度乘以每个请求持有时间一旦开始排队整体响应时间不是线性增长而是接近线性叠加。这就是为什么监控上 P99 会在几分钟内从 200ms 跳到 8s。4.3 我们忽略了“快速失败”这个安全阀发生故障时平台缺少一个关键机制熔断降级。当检测到一个下游或整条链路超过阈值时应该直接短路让请求立刻返回 503 或 504而不是继续占用资源等待成功。快速失败的意义是牺牲少数请求保住整个平台让剩余容量能够处理那些真正健康的请求。当时我们以为“重试 1 次 30 秒超时”已经算降级保护其实完全不够。重试 1 次意味着在超时之后还要再发起一次同样会超时的请求慢请求占用的时间直接翻倍。而下游已经明显变慢时重试只是火上浇油。正确的策略应该是连续失败率达到阈值后直接短路若干秒连调用都不发给下游一个喘息时间。5. 修复过程超时链路、信号量隔离和熔断降级5.1 第一层修复给整个请求链路加硬性超时第一步改动是在 FastAPI 应用的最外层加一个中间件用 asyncio.wait_for 包住整个请求处理。这样无论内部编排了多少步总时间都受控。我们最终把整体超时设定为 5 秒比网关的 10 秒短比下游单次调用的 30 秒更短。核心代码大概是这样的import asyncio from fastapi import Request from fastapi.responses import JSONResponse app.middleware(http) async def overall_timeout(request: Request, call_next): try: return await asyncio.wait_for(call_next(request), timeout5) except asyncio.TimeoutError: return JSONResponse(status_code504, content{error: request timeout})注意一点中间件包住的是“整个 FastAPI 路由执行过程”包括所有下游调用和编排等待。如果编排内部已经拿到了信号量但下游迟迟不返回5 秒到了照样切断。切断后协程虽然会被取消但下游的 HTTP 请求是否真的取消取决于 httpx 的实现所以还要在每次下游调用附加上更短的超时时间。我们统一把下游单次调用超时从 30 秒改成 3 秒重试改为 0 次。这里的核心逻辑是梯度网关超时 10 秒应用整体超时 5 秒下游单次调用超时 3 秒。这样每一层都在上一层内部快速失败不会出现“网关还在等应用还能拖下游却更晚超时”的颠倒关系。5.2 第二层修复信号量按下游维度隔离第二步是把“全局一个信号量”改成“每个下游独立的一组信号量”。我们抽象了一个简单的限制器初始化时就为每个下游分配独立的 Semaphoreimport asyncio DOWNSTREAM_LIMITS { llm_gateway: asyncio.Semaphore(20), knowledge_base: asyncio.Semaphore(15), internal_search: asyncio.Semaphore(10), }每个下游调用前先获取对应下游的信号量再发请求。这样即使 LLM 网关慢占满的也只是 LLM 这一组名额知识库和搜索调用不受影响。更重要的是当一个下游持续变慢时该下游的排队请求会被整体超时快速清掉不会蔓延到其他依赖。隔离带来的另一个好处是容量可视每个信号量的等待队列长度可以单独上报到监控系统。以前只有一个“全局等待队列”根本无法判断是哪个下游拖垮了平台现在每个下游一个指标哪条线路排队了一眼就能看出来。要注意一个实现细节asyncio.Semaphore 必须在运行中的事件循环里创建写成全局变量在导入时初始化有时会踩 “Future attached to a different loop” 的坑。更稳妥的做法是在 FastAPI 的启动事件里初始化或者用一个 lazy 初始化的容器。我们后来改成了在 lifespan 里初始化避免循环绑定问题。5.3 第三层修复用快速失败替代无限等待第三步是引入一个很轻量的熔断器。因为折腾半天我们发现最有效的保护不是更复杂的算法而是“连续失败快速短路”。Python 里我们可以用一个简单的滑动窗口来实现from collections import deque import time class CircuitBreaker: OPEN open HALF_OPEN half_open CLOSED closed def __init__(self, failure_threshold5, window10): self.failure_threshold failure_threshold self.window window self.failures deque() self.state self.CLOSED self.open_since 0 def record_failure(self): now time.time() self.failures.append(now) while self.failures and self.failures[0] now - self.window: self.failures.popleft() if len(self.failures) self.failure_threshold: self.state self.OPEN self.open_since now def allow_request(self): if self.state self.OPEN: if time.time() - self.open_since 5: self.state self.HALF_OPEN return True return False return True这个熔断器挂在每个下游调用的外层如果 10 秒内有 5 次失败就先短路 5 秒5 秒后放一个试探请求试探成功就恢复失败则继续打开。虽然实现简单但效果立竿见影比任何超时参数都更能保证系统在极端情况下仍然有响应能力。我还给熔断器加了个降级分支短路期间不直接返回错误而是返回缓存里的旧结果没有缓存就返回一个明确的“依赖暂不可用”提示让调用方决定是否降级。这个做法极大减少了用户侧对错误的感知。5.4 压测验证修复前后的对比所有代码改完我们立刻在测试环境复现了故障场景。压测数据说话场景修复前 P99修复后 P99错误率正常流量 50 qps180ms210ms0%5% 慢调用 满并发9.8s780ms1.2%20% 慢调用 熔断触发全链路超时1.1s大量快速失败15%修复后即使模拟了 20% 的慢调用系统也没有被拖死平台仍然能以 1.1s 的 P99 响应大部分请求剩下 15% 快速失败并降级。这个结果比预想的好很多因为快速失败把资源释放了让剩余健康请求的延迟恢复到了接近正常水平。5.5 临时扩容不是解药但是止血手段故障当天我们还做了一件事直接把 Agent Platform 的实例数扩容了三倍。扩容后 10 分钟内错误率确实降下来了但我和同事都清楚这治标不治本。因为慢请求占比没有下降全局信号量的容量虽然随着实例数增加变大了可每个实例的全局信号量依然会被慢请求占满只是整体容量大了两三倍撑得更久而已。后面在一次真实毛刺中验证了这一点实例数已经回到正常水位LLM 网关又出现了一次几十秒的抖动因为熔断器已经生效平台没有再次雪崩。这让我坚信靠资源堆出来的稳定性永远不可持续只有代码层面的快速失败机制才是真安全阀。6. 后续经验如何让 Agent 类服务少踩超时坑6.1 超时是链路工程不是某个参数现在我把“超时”当成一条完整的链路来设计。客户端超时要短于网关超时网关超时要短于应用整体超时应用整体超时要短于下游单次调用超时重试次数要尽量少。我们最终沉淀出一个标准表格任何接入 Agent Platform 的新下游都按这个来层级超时时间说明客户端调用平台8s业务方等待上限API 网关转发10s网关等待应用响应应用整体链路5s中间件强制切断单次下游调用3shttpx 超时下游重试策略0 次推荐不重试或用熔断代替重试这个梯度表的核心理念是每一层都是上一层最后的安全兜底。如果你发现某一层超时时间比上层还长那这个配置本身就是一个故障源。6.2 可观测性必须回答“谁在等谁”排查这次故障时我们最大的痛是没有链路追踪。靠 py-spy dump 看到的是“等待信号量”但看不到“哪个下游占用了信号量”。后来我们在所有关心的地方埋了 span每个编排任务都有独立的 trace_id信号量获取前和后都打点计时。现在遇到超时告警第一件事就是打开追踪看 waterfall哪个环节耗时最长、哪个环节在等锁、哪个下游响应慢一目了然。如果你也想做类似的平台建议尽早接分布式追踪不要等线上出事了再补。排查超时问题最怕的就是“能看到结果但看不到等待过程”。可观测性不是锦上添花是基础设施。6.3 找时间做一次延迟故障演练这次事故后我们养成了一个习惯每个月主动给某个下游加 2 到 5 秒的延迟看看平台能不能扛住。做法也很简单写一个中间层代理故意把流量中的一部分请求延迟返回然后观察 Agent Platform 的整体延迟和错误率。演练的目的不是验证代码能不能扛而是让团队熟悉“当所有监控都不正常时第一反应去哪里看”。这个习惯帮我们提前发现了好几个问题比如某个连接池配置太小、某个下游调用的重试逻辑不生效、某个缓存过期策略会把压力集中到下一天。真到线上遇到故障处理速度比上次快很多。6.4 资源池水位指标记得单独监控最后分享一个小技巧对于任何用了信号量、线程池、连接池的服务务必把“等待队列长度”“资源使用率”单独接进监控面板。不要只看 CPU 和内存它们这两个指标在 I/O 密集型服务里极具欺骗性。本次故障期间 CPU 只有 38%但信号量等待队列已经 400这其实是“系统已经无法调度新请求”的最强信号。我们监控面板上现在常驻三个指标各下游信号量等待队列长度、HTTP 连接池活跃连接数、熔断器当前状态。这三个指标任何一个出现异常都比 CPU 冲到 90% 更值得警惕。如果你也在做 Agent Platform 这类编排型平台我的建议很简单把每一个外部调用都想象成“随时可能卡死 30 秒的未知依赖”然后问自己——如果它真的卡死了我的请求多久能失败我的其他依赖会受影响吗我的客户端会等到什么时候把这三个问题想清楚大部分超时事故都不会发生。
做 Agent Platform 开发这半年我最难忘的不是功能上线而是某个下午线上超时故障爆发时的无力感。当时平台已经稳定运行了两周P99 延迟稳定在 200ms 左右结果一个再普通不过的需求变更后监控面板突然全红超时率直线上升客户端重试像海浪一样一层层压回来。今天想把这个过程完整写下来从告警表象一直拆到协程栈里的等待链再到最终的超时治理方案。如果你也在做 Agent 编排类服务或者写过异步后端这篇文章应该能帮你少踩几个类似的坑。先说结论这次故障不是某个下游服务挂了也不是网络抖动而是我们在设计 Agent Platform 的执行模型时忽略了“整体请求超时”和“资源池隔离”把一个本可以快速失败的慢请求放大成了全平台雪崩。整个排查过程很有意思也很折磨人我把关键证据、定位思路和修复细节都整理在下面。1. 我所在的 Agent Platform 到底承担了什么职责1.1 它不是简单的 API 转发层我们内部代号 Agent Platform表面上是一个 HTTP 接口服务但实际职责比“转发”重得多。它要管理一组 Agent 实例的注册与调度维护会话级上下文编排多步推理流程还要在每一步调用不同的工具模型推理服务、知识库检索、搜索接口、内部业务系统。业务方只需要把用户问题传进来平台会负责拆解任务、选择 Agent、调用工具、汇总结果最后再返回给调用方。所以从调用链路看一次用户请求到达平台后可能内部要串行或并行执行多轮调用。典型链路是这样客户端请求先进 API 网关网关转发给 Agent Platform 的 OrchestratorOrchestrator 先调用 LLM 网关做意图识别再根据计划调知识库和业务工具最后把结果拼装返回。每一步都会产生额外的网络 RTT 和延迟任何一环变慢整个响应时间就会被拉上去。这个架构本身不复杂但它给所有后端工程师提了个醒Agent 平台和普通 CRUD 服务最大的区别在于一次用户请求对应着多次下游依赖调用而且这些调用是长尾、不可控的。你用服务本身的快慢去衡量健康度往往失真真正要盯的是“一次编排里最慢的那个外部调用”。1.2 技术选型和埋下的隐患我们用的是 Python FastAPI路由层用 async def 写下游 HTTP 调用统一走 httpx.AsyncClient长时间任务通过任务队列给 Worker 消费。进程内用 asyncio.Semaphore 控制并发上限防止下游被突发流量打爆单次下游调用的超时时间设了 30 秒重试策略做了 1 次。这套设计在上线初期看起来没什么问题。异步模型天然适合 I/O 密集型场景信号量也确实能限制最大并发。但我后来才意识到这里有两个隐蔽的坑第一个坑是“只给下游调用设了超时没给整个请求链路设超时”。假设一次 Agent 编排需要串行调用 3 次下游每次下游最多等 30 秒那么一次用户请求理论上最长可能要等 90 秒。可客户端一般只愿意等 10 秒甚至 5 秒于是大量请求在客户端侧直接断开而服务端还在傻等下游返回。第二个坑是信号量虽然是全局的但它保护的是“同时在跑的协程数”而不是“等待的总工作量”。慢请求会长时间占着信号量新请求只能排队排队时间一长客户端的等待时间就爆炸了。后来压测时我测算过只要下游出现 5% 的慢调用系统整体吞吐会掉到原来的十分之一都不到。这个数学模型当时没建等线上出事才回头补上。2. 故障先行线上告警和我的第一反应2.1 监控面板上那些刺眼的数字那天下午的故障不是瞬间发生的是逐步恶化的。最早的告警来自平台自身“HTTP 500 比例超过阈值”然后紧接着是网关告警“上游响应超时率偏高”。我打开监控面板时情况已经比较惊人了指标故障前近 7 天均值故障开始后 30 分钟P99 响应时间180ms8.5sP95 响应时间120ms3.2s错误率5xx4xx0.1%18%服务进程 CPU35%38%下游 LLM 网关平均延迟450ms470ms平台内信号量等待队列长度0持续 400看到 CPU 不高、下游延迟也正常我当时第一反应是“入口流量是不是突然暴涨了”。但打开流量曲线后发现请求量只比平时高了约 20%远远不足以解释错误率涨了 180 倍。这个矛盾点很重要服务不忙下游不慢请求却在超时那很大概率是内部排队了。2.2 服务端日志里的“等锁”痕迹我们当时的日志体系比较基础应用打点 访问日志 错误日志。翻错误日志时发现一个规律大量请求的返回时间不是集中在某个点而是非常均匀地分布在 5 秒、10 秒、30 秒这几个整点。5 秒是客户端网关的默认读超时10 秒是业务侧设置的等待阈值30 秒是我们给下游设的单次调用超时。这说明什么说明很多请求根本没走完正常的 Agent 编排流程而是卡在了某个等待环节最后是被外部机制强杀掉的。再往应用日志里挖能看到大量这样的行“waiting for semaphore, acquired100, waiting87”。也就是说并发许可已经占满了后续请求全部在排队等信号量。还有一个细节让我至今难忘服务 CPU 只有 38%内存也很正常但大量协程卡在信号量获取上。纯异步应用出现这种“低资源占用、高延迟”的现场基本可以断定是并发模型出了问题不是计算资源不够。2.3 用户视角的雪崩链条为了搞清楚影响范围我让前端同事模拟了一个真实用户操作。用浏览器直接请求 Agent Platform结果是请求发出去后转圈直到浏览器侧报 ERR_EMPTY_RESPONSE。再用 curl 带超时参数测发现只要超过 3 秒没有响应就会自动断开断开前收到的数据为空。从调用方的角度看这个现象特别像平台已经挂死。但其实平台还活着只是拿不出新的并发名额来处理请求。因为每个新请求最先进入 Orchestrator 时第一步就是获取信号量信号量被慢请求占住新请求就一直停在 acquire 上连后续的下游调用都不会发起。这已经形成了雪崩雏形慢请求占住信号量不释放新请求排队等待排队的请求又占用着 HTTP 连接和协程网关收到的连接越来越多最终不可避免地把入口也拖死。3. 排查链条从网关到协程栈逐层剥离3.1 先排除网络和网关的嫌疑故障排查最忌讳一上来就怀疑某一段具体代码我习惯先从入口往出口一层层剥。第一层是 API 网关检查网关转发耗时和上游连接数。结果显示网关到平台的 TCP 连接正常连接建立时间稳定在 5ms 以内网络层面没有丢包。网关把请求转发给应用后等待应用响应的时间非常久说明问题在应用侧不在入口网络。第二层是平台所在服务器的系统资源。用 uptime、free、top 看了一眼load average 只有 0.8内存余量充足磁盘 I/O 也没波动。CPU 每个核的使用率最多 45%没有出现单核打满的迹象。系统级排障基本结束接下来只能往应用层和代码层走。3.2 用 py-spy dump 看协程到底卡在哪异步应用有个好处是可以直接抓协程栈。我在一台出问题的实例上执行了 py-spy dump --pid 输出的结果里大量协程停在同一段代码上。典型栈长这样Task_1234 (coroutine...) File ./orchestrator.py, line 186, in run_agent await lock.acquire() File ./orchestrator.py, line 88, in acquire_slot await self._semaphore.acquire()一眼望过去几乎所有协程都阻塞在信号量 acquire 上只有少数协程真正在跑下游 HTTP 请求。这个证据基本把范围锁定到了两个方向要么信号量容量太小要么单个请求持有信号量的时间太长。我后来算了一下我们的信号量容量是 100如果每个请求都在 100ms 内结束100 并发足够支撑每秒 1000 个请求。但 Agent 编排请求平均持有信号量的时间是 800ms个别请求达到 30 秒。容量的确够小但真正致命的是“持有时间”出现长尾。3.3 复现实验并发度加到多少会崩既然证据指向信号量我就写了个压测脚本模拟线上请求对平台发起了阶梯式并发压测。脚本做的很简单用 aiohttp 并发请求 Agent Platform 的编排接口每个请求内再让 Orchestrator 调用一个 mock 下游服务mock 服务故意对 5% 的请求加 20 秒延迟。压测结果非常清晰并发 50 时P99 约 400ms一切正常。并发 80 时P99 涨到 1.2s少量请求开始等待。并发 100 时P99 直接跳到 9.8s错误率开始飙升。并发 120 时几乎所有请求都超时错误率超过 50%。这个实验把“慢请求 满容量信号量 雪崩”的等式钉死了。即使下游慢调用只占 5%一旦整体并发触顶系统就会完全丧失快速失败的能力。3.4 在下游找不到根因却在自家配置里找到了压测验证的同时我还让同事去查下游 LLM 网关的日志。结果发现一个特别微妙的现象某个时间点起LLM 网关确实出现了一点毛刺极少数请求耗时达到 28 秒但占比只有 2%-3%。这种现象在正常波动范围内谈不上故障。坏就坏在我们对下游毛刺的容忍度是 0。一个 28 秒的慢请求会占住一个信号量名额长达 28 秒。假设系统每秒新进来 60 个请求每个请求平均持有信号量 800ms稳态需要 48 个并发剩余 52 个名额本来可以应对毛刺但慢请求如果批量出现52 个名额很快被耗尽所有新请求开始排队。而排队中的请求又不会主动退出只是在等锁这等于把“延迟问题”变成了“资源耗尽问题”。所以最后定位到的根因其实是一个组合拳下游确有少量慢请求但我们没有为不同下游隔离资源也没有给整体请求设置最终超时还没做快速失败。这三件事单独看都不算什么合在一起就成了事故。4. 根因复盘一次 28s 的慢请求如何堵死整个平台4.1 “整体无超时”让上限失去了意义很多人会争论我们明明给 httpx 客户端的每个请求设置了 30 秒超时为什么还说无超时关键就在这里你给单个下游调用设置超时并不代表整条编排链路有终止时间。一个用户请求可能要先调意图识别再调知识库再调任务执行 Agent这三步串行加起来最坏可能 90 秒。线上客户端不会等 90 秒网关默认读超时是 5 秒应用侧最外层也设了 10 秒。于是服务端和客户端对“一个请求到底能跑多久”的理解完全不一致。客户端 5 秒就断了服务端还在跑 30 秒的下游调用下游最终返回了平台却想把结果回写给一个根本不存在的连接只能产生异常。这些“孤儿请求”虽然没有用户接收但它们同样占着信号量同样消耗资源。所以这次事故后我们把“链路总超时”列为第一优先级而且要求必须比外部超时更短。宁可让请求快速失败也不允许让请求在系统里多活一秒钟。4.2 全局共享信号量的放大效应信号量本身是好东西它避免了无脑打到下游。但全局共享一个信号量会让不同下游、不同业务性质的任务互相拖累。设想一下A 类任务主要调内部搜索服务B 类任务主要调 LLM 网关。如果某一天 LLM 网关变慢全局信号量会被 B 类任务占满A 类任务虽然依赖完全正常也会被连坐拿不到许可。更细节的放大效应来自 Agent 编排的特点一个编排任务内部可能会并行发起多个下游调用每个调用都要获取信号量。假设我们用信号量限制“同时调用下游的次数”而不是“同时执行的 Agent 任务数”那么每个任务实际占用的名额可能不止一个达到 3-4 个。并发上限看似 100实际最多只能容纳 30 个任务同时运行系统的真实吞吐远低于设计值。我用一个很简单的模型解释这次事故系统每秒到达 50 个请求平均每个请求需要持有信号量的时间是 0.5 秒那么稳态需要的并发数是 25信号量 100 时非常宽裕。但下游毛刺出现后2% 的请求持有时间变成 20 秒平均持有时间从 0.5 秒变成 0.5 * 0.98 20 * 0.02 0.89 秒稳态并发需求涨到 45还没事。如果慢请求占比涨到 5%平均持有时间变成 1.475 秒稳态并发需求变成 74已经接近上限再叠加到达率高峰系统立刻进入排队状态。排队时间等于队列长度乘以每个请求持有时间一旦开始排队整体响应时间不是线性增长而是接近线性叠加。这就是为什么监控上 P99 会在几分钟内从 200ms 跳到 8s。4.3 我们忽略了“快速失败”这个安全阀发生故障时平台缺少一个关键机制熔断降级。当检测到一个下游或整条链路超过阈值时应该直接短路让请求立刻返回 503 或 504而不是继续占用资源等待成功。快速失败的意义是牺牲少数请求保住整个平台让剩余容量能够处理那些真正健康的请求。当时我们以为“重试 1 次 30 秒超时”已经算降级保护其实完全不够。重试 1 次意味着在超时之后还要再发起一次同样会超时的请求慢请求占用的时间直接翻倍。而下游已经明显变慢时重试只是火上浇油。正确的策略应该是连续失败率达到阈值后直接短路若干秒连调用都不发给下游一个喘息时间。5. 修复过程超时链路、信号量隔离和熔断降级5.1 第一层修复给整个请求链路加硬性超时第一步改动是在 FastAPI 应用的最外层加一个中间件用 asyncio.wait_for 包住整个请求处理。这样无论内部编排了多少步总时间都受控。我们最终把整体超时设定为 5 秒比网关的 10 秒短比下游单次调用的 30 秒更短。核心代码大概是这样的import asyncio from fastapi import Request from fastapi.responses import JSONResponse app.middleware(http) async def overall_timeout(request: Request, call_next): try: return await asyncio.wait_for(call_next(request), timeout5) except asyncio.TimeoutError: return JSONResponse(status_code504, content{error: request timeout})注意一点中间件包住的是“整个 FastAPI 路由执行过程”包括所有下游调用和编排等待。如果编排内部已经拿到了信号量但下游迟迟不返回5 秒到了照样切断。切断后协程虽然会被取消但下游的 HTTP 请求是否真的取消取决于 httpx 的实现所以还要在每次下游调用附加上更短的超时时间。我们统一把下游单次调用超时从 30 秒改成 3 秒重试改为 0 次。这里的核心逻辑是梯度网关超时 10 秒应用整体超时 5 秒下游单次调用超时 3 秒。这样每一层都在上一层内部快速失败不会出现“网关还在等应用还能拖下游却更晚超时”的颠倒关系。5.2 第二层修复信号量按下游维度隔离第二步是把“全局一个信号量”改成“每个下游独立的一组信号量”。我们抽象了一个简单的限制器初始化时就为每个下游分配独立的 Semaphoreimport asyncio DOWNSTREAM_LIMITS { llm_gateway: asyncio.Semaphore(20), knowledge_base: asyncio.Semaphore(15), internal_search: asyncio.Semaphore(10), }每个下游调用前先获取对应下游的信号量再发请求。这样即使 LLM 网关慢占满的也只是 LLM 这一组名额知识库和搜索调用不受影响。更重要的是当一个下游持续变慢时该下游的排队请求会被整体超时快速清掉不会蔓延到其他依赖。隔离带来的另一个好处是容量可视每个信号量的等待队列长度可以单独上报到监控系统。以前只有一个“全局等待队列”根本无法判断是哪个下游拖垮了平台现在每个下游一个指标哪条线路排队了一眼就能看出来。要注意一个实现细节asyncio.Semaphore 必须在运行中的事件循环里创建写成全局变量在导入时初始化有时会踩 “Future attached to a different loop” 的坑。更稳妥的做法是在 FastAPI 的启动事件里初始化或者用一个 lazy 初始化的容器。我们后来改成了在 lifespan 里初始化避免循环绑定问题。5.3 第三层修复用快速失败替代无限等待第三步是引入一个很轻量的熔断器。因为折腾半天我们发现最有效的保护不是更复杂的算法而是“连续失败快速短路”。Python 里我们可以用一个简单的滑动窗口来实现from collections import deque import time class CircuitBreaker: OPEN open HALF_OPEN half_open CLOSED closed def __init__(self, failure_threshold5, window10): self.failure_threshold failure_threshold self.window window self.failures deque() self.state self.CLOSED self.open_since 0 def record_failure(self): now time.time() self.failures.append(now) while self.failures and self.failures[0] now - self.window: self.failures.popleft() if len(self.failures) self.failure_threshold: self.state self.OPEN self.open_since now def allow_request(self): if self.state self.OPEN: if time.time() - self.open_since 5: self.state self.HALF_OPEN return True return False return True这个熔断器挂在每个下游调用的外层如果 10 秒内有 5 次失败就先短路 5 秒5 秒后放一个试探请求试探成功就恢复失败则继续打开。虽然实现简单但效果立竿见影比任何超时参数都更能保证系统在极端情况下仍然有响应能力。我还给熔断器加了个降级分支短路期间不直接返回错误而是返回缓存里的旧结果没有缓存就返回一个明确的“依赖暂不可用”提示让调用方决定是否降级。这个做法极大减少了用户侧对错误的感知。5.4 压测验证修复前后的对比所有代码改完我们立刻在测试环境复现了故障场景。压测数据说话场景修复前 P99修复后 P99错误率正常流量 50 qps180ms210ms0%5% 慢调用 满并发9.8s780ms1.2%20% 慢调用 熔断触发全链路超时1.1s大量快速失败15%修复后即使模拟了 20% 的慢调用系统也没有被拖死平台仍然能以 1.1s 的 P99 响应大部分请求剩下 15% 快速失败并降级。这个结果比预想的好很多因为快速失败把资源释放了让剩余健康请求的延迟恢复到了接近正常水平。5.5 临时扩容不是解药但是止血手段故障当天我们还做了一件事直接把 Agent Platform 的实例数扩容了三倍。扩容后 10 分钟内错误率确实降下来了但我和同事都清楚这治标不治本。因为慢请求占比没有下降全局信号量的容量虽然随着实例数增加变大了可每个实例的全局信号量依然会被慢请求占满只是整体容量大了两三倍撑得更久而已。后面在一次真实毛刺中验证了这一点实例数已经回到正常水位LLM 网关又出现了一次几十秒的抖动因为熔断器已经生效平台没有再次雪崩。这让我坚信靠资源堆出来的稳定性永远不可持续只有代码层面的快速失败机制才是真安全阀。6. 后续经验如何让 Agent 类服务少踩超时坑6.1 超时是链路工程不是某个参数现在我把“超时”当成一条完整的链路来设计。客户端超时要短于网关超时网关超时要短于应用整体超时应用整体超时要短于下游单次调用超时重试次数要尽量少。我们最终沉淀出一个标准表格任何接入 Agent Platform 的新下游都按这个来层级超时时间说明客户端调用平台8s业务方等待上限API 网关转发10s网关等待应用响应应用整体链路5s中间件强制切断单次下游调用3shttpx 超时下游重试策略0 次推荐不重试或用熔断代替重试这个梯度表的核心理念是每一层都是上一层最后的安全兜底。如果你发现某一层超时时间比上层还长那这个配置本身就是一个故障源。6.2 可观测性必须回答“谁在等谁”排查这次故障时我们最大的痛是没有链路追踪。靠 py-spy dump 看到的是“等待信号量”但看不到“哪个下游占用了信号量”。后来我们在所有关心的地方埋了 span每个编排任务都有独立的 trace_id信号量获取前和后都打点计时。现在遇到超时告警第一件事就是打开追踪看 waterfall哪个环节耗时最长、哪个环节在等锁、哪个下游响应慢一目了然。如果你也想做类似的平台建议尽早接分布式追踪不要等线上出事了再补。排查超时问题最怕的就是“能看到结果但看不到等待过程”。可观测性不是锦上添花是基础设施。6.3 找时间做一次延迟故障演练这次事故后我们养成了一个习惯每个月主动给某个下游加 2 到 5 秒的延迟看看平台能不能扛住。做法也很简单写一个中间层代理故意把流量中的一部分请求延迟返回然后观察 Agent Platform 的整体延迟和错误率。演练的目的不是验证代码能不能扛而是让团队熟悉“当所有监控都不正常时第一反应去哪里看”。这个习惯帮我们提前发现了好几个问题比如某个连接池配置太小、某个下游调用的重试逻辑不生效、某个缓存过期策略会把压力集中到下一天。真到线上遇到故障处理速度比上次快很多。6.4 资源池水位指标记得单独监控最后分享一个小技巧对于任何用了信号量、线程池、连接池的服务务必把“等待队列长度”“资源使用率”单独接进监控面板。不要只看 CPU 和内存它们这两个指标在 I/O 密集型服务里极具欺骗性。本次故障期间 CPU 只有 38%但信号量等待队列已经 400这其实是“系统已经无法调度新请求”的最强信号。我们监控面板上现在常驻三个指标各下游信号量等待队列长度、HTTP 连接池活跃连接数、熔断器当前状态。这三个指标任何一个出现异常都比 CPU 冲到 90% 更值得警惕。如果你也在做 Agent Platform 这类编排型平台我的建议很简单把每一个外部调用都想象成“随时可能卡死 30 秒的未知依赖”然后问自己——如果它真的卡死了我的请求多久能失败我的其他依赖会受影响吗我的客户端会等到什么时候把这三个问题想清楚大部分超时事故都不会发生。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
