限流与并发 - Tapapi 文档

限流用于保护平台稳定，也帮助用户控制成本。上线前不要只问“能跑多少 RPM”，更要明确你的并发池、队列、失败重试和降级策略。 Tapapi 的模型请求限流按用户和账户分组生效。不同模型的实际可用容量还会受上游通道、模型速度和平台调度影响。实际阈值以控制台、账户分组和支持团队确认为准，文档不写死固定 RPM。

当前后端存在两类保护：总请求数限制和成功请求数限制。失败请求也可能计入总请求数，所以错误参数无限重试会很快触发保护。

你需要关注

指标	说明
总请求数	一段时间内所有请求，包括失败请求
成功请求数	一段时间内成功响应的请求
并发	同时进行中的请求数，通常由你的业务队列控制
429	达到限流或上游负载饱和
重试间隔	指数退避 + 随机抖动，不要立即重打
分组	不同账户分组可能有不同容量和价格策略

推荐架构

Tapapi 的平台限流是入口保护，不是你业务自己的并发池替代品。只要你的产品里有多个终端用户、批量任务或自动 worker，就应该在自己的后端再做一层队列、并发控制和用户级限流。不要让前端直接并发打模型。生产接入建议用这条链路：

用户请求
  -> 你的后端鉴权和生成业务 task_id
  -> 队列或并发池
  -> worker 调 Tapapi
  -> 保存结果和用量
  -> 前端查询你的业务任务状态

同步文本或单张图片可以直接等待结果，但也应在你的后端设置并发池；批量跑图、高质量慢模型和视频任务建议一律走队列。

推荐策略

场景	建议
普通线上请求	服务端加并发池，不让用户请求直接打满模型
批量任务	队列 + worker，先低并发放量
慢模型	单独队列，避免拖慢快模型
多模型混用	按模型拆指标，分别看成功率、耗时和 429
高峰活动	提前确认账户限流和模型容量
失败重试	每个业务 `task_id` 限制最大重试次数
多用户共用 Key	给自己的业务用户做二级限流，避免一个用户打满全局额度

429 处理

收到 429 时，先降并发，再有限重试。不要把 429 当成普通失败立即并发重放。 429 不一定都有稳定的 error.code。客户侧应优先按 HTTP 429 判断，再记录 error.message、request_id、模型名和当前并发数用于排障。

429 -> 暂停当前 worker 1-2 秒
再次 429 -> 降低队列并发，等待 3-5 秒
连续 429 -> 停止自动放量，切换低峰执行或联系支持

生产代码建议记录：

模型名
业务 task_id
request_id
当前并发数
重试次数
HTTP 状态码
error.code 和 error.message

推荐 worker 逻辑：

if status == 429:
  reduce concurrency
  sleep with backoff + jitter
  retry only if retry_count < max_retry

if status in 400/401/403/413/422:
  mark failed, do not retry

if status is temporary 5xx:
  retry 1-2 times, then stop

批量跑图放量

阶段	目标	建议
小样本	验证参数和保存链路	先跑 20-50 条真实 prompt
小批量	验证稳定性	从低并发开始，观察成功率和平均耗时
放大	控制成本和峰值	按小时分批，不要一次性全量提交
异常升高	保护业务	先降并发，再决定是否切换兜底模型

什么时候联系支持

业务活动前需要确认容量
长期稳定触发 429
同一模型在低并发下仍大量 429
需要更高分组限流或专门通道

联系时带上模型、时间段、预期 QPS/RPM、平均图片数量、当前并发、失败比例、典型 request_id 和业务场景。