> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 限流与并发

> 账户限流、429、并发池和批量保护

限流用于保护平台稳定，也帮助用户控制成本。上线前不要只问“能跑多少 RPM”，更要明确你的并发池、队列、失败重试和降级策略。

Tapapi 的模型请求限流按用户和账户分组生效。不同模型的实际可用容量还会受上游通道、模型速度和平台调度影响。实际阈值以控制台、账户分组和支持团队确认为准，文档不写死固定 RPM。

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

## 你需要关注

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

## 推荐架构

Tapapi 的平台限流是入口保护，不是你业务自己的并发池替代品。只要你的产品里有多个终端用户、批量任务或自动 worker，就应该在自己的后端再做一层队列、并发控制和用户级限流。

不要让前端直接并发打模型。生产接入建议用这条链路：

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

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

## 推荐策略

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

## 429 处理

收到 429 时，先降并发，再有限重试。不要把 429 当成普通失败立即并发重放。

429 不一定都有稳定的 `error.code`。客户侧应优先按 HTTP 429 判断，再记录 `error.message`、`request_id`、模型名和当前并发数用于排障。

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

生产代码建议记录：

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

推荐 worker 逻辑：

```text theme={null}
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` 和业务场景。