Toonflow 怎么控制 API 并发调用上限，超出上限时该排队还是直接失败？

Toonflow 控制 API 并发调用上限的核心手段，是在调用层设一个最大同时在途请求数的闸门，再配合等待队列、超时和退避重试，而不是把请求简单发慢一点。它约束的是同一时刻已经发出、尚未返回的请求数量；如果上游限制的是每分钟请求数或每分钟 token 数，光调这个数字解决不了问题。反过来，只要上游给的是硬性并发上限，客户端任何参数都突破不了。 并发数和每分钟请求数、每分钟 token 数是三种不同约束，混在一起调往往两头都调不好。并发描述的是在途请求数，速率描述的是单位时间的发送量，两者之间靠平均响应时间换算，响应变慢时同样的并发会打出更少的请求。所以先确认上游限制的到底是哪一种，再决定在 Toonflow 侧是压并发、压发送速率还是压 token 消耗。 并发上限通常需要按层级设置，越靠近调用点的配置越应该拥有更高优先级。常见的做法是给全局一个保守默认值，再按模型或上游服务商覆盖，最后允许单个工作流节点单独放宽；具体字段名、优先级顺序和是否需要重启生效，以官方说明为准。把全局值压低、只给关键节点放宽，出问题时更容易定位是哪一层放开了。 闸门的实现形式是信号量或固定大小的工作池，本质是申请名额、执行、释放三步。调用发出前先占用一个名额，名额用尽时请求进入等待队列，而不是先发出去再补限制；请求返回、超时或抛异常后名额必须释放。只有这样才能保证上限是硬的，批量任务同时提交也不会瞬间打爆上游。 超过上限后是排队还是立即失败，取决于这个任务能不能等、能不能丢。可延迟的批处理任务适合排队，代价是端到端耗时变长；面向用户实时交互的任务适合设很短的队列并快速失败，避免让人等一个注定超时的结果。两类任务最好走不同队列，否则慢任务的堆积会连带拖慢实时请求。 遇到 429 或限流错误时，退避重试必须带抖动，而且重试请求同样要占用并发名额。固定间隔的重试会让所有被卡住的请求在同一时刻再次涌向上游，形成新的尖峰；重试若绕开名额计数，实际并发就会超过你设定的上限。重试次数要有上限，并且只对幂等调用开放，写操作类调用宁可失败交给上游业务层处理。 多实例部署时，单机信号量会失效，这是并发控制里最容易踩的坑。每个实例各自限制同一个数值，上游看到的并发就是实例数乘以单实例额度，扩容一次实际并发跟着放大一次。可行做法有两种：把计数放到集中式存储里做全局令牌桶或漏桶，或者把总并发额度静态切分给每个实例，并在扩缩容时同步调整单实例额度。 按上游服务商和密钥分组限流，能避免一个慢节点把整个池子拖垮。不同上游的限制规则不同，同一上游的不同密钥也可能有独立配额；如果所有调用共用一个名额池，某个响应极慢的模型会长期占住名额，原本正常的调用被迫一起排队。分组后每组独立计数，异常只影响一组，也更容易看出是哪一家在限流。 把并发上限当成吞吐开关是常见误判，调高并发并不等于出量变大。当上游给的是速率配额时，超出部分只会以限流错误的形式返回，还额外消耗重试次数和名额；真正决定吞吐的是配额、平均响应时间和失败率。先把失败率和排队时长压下去，再谈加并发，顺序反了只会让指标更差。 超时时间、连接池大小和并发上限必须对齐设置，否则名额会被僵尸请求占住。超时设得过长，一个卡住的调用会一直占着名额等到超时；连接池上限低于并发上限时，多出来的请求其实卡在本地连接获取环节，看起来像是并发上限没生效。还要保证超时、取消、异常这几条路径上名额一定被释放。 并发上限的合适数值靠阶梯压测找拐点，不靠经验拍。从一个较低的数值开始逐级上调，每一级观察限流错误比例、队列长度和延迟分位数；当限流错误明显上升或延迟开始非线性抬升时，那一级就是当前配置下的实际拐点。日常运行要留出余量给突发流量，并且至少盯住在途请求数、排队长度、重试次数和端到端延迟这几项指标。 需要说清的边界是，Toonflow 侧的并发设置在客户端，越不过上游的硬性限制。上游按账号或密钥给出的并发、速率、配额上限，客户端怎么调都突破不了；客户端能做的只是不让情况更糟，比如不因重试放大并发、不让队列无上限堆积、不在多实例下重复计算额度。需要更高总吞吐时，跨多个上游分散负载是可行方向，但每一路仍受各自配额约束。