# QPS 限流与容量升级

理解调用频率、并发和额度的区别，合理安排请求，并按业务需要申请 QPS 扩展。

## 核心步骤

- 在开发者中心确认目标接口的有效订阅与 QPS 权益。
- 统计高峰请求频率，统一控制多个任务的调用速率。
- 需要扩展时从“升级 QPS”入口核对报价并完成支付。
- 确认扩展状态后逐步增加流量，检查限流响应与调用耗时。

## 适用场景与准备

适合定时任务、批量处理和多个服务共同调用同一接口的场景。准备目标接口名称、有效订阅和高峰时段的请求记录，在 [开发者中心](https://www.gugudata.com/portal/) 查看对应产品的权限与升级入口。不要使用其他产品的 QPS 权益估算当前接口容量。

## QPS、并发和调用额度有什么区别

QPS 表示每秒发起的请求数，并发表示同时尚未完成的请求数，调用额度表示套餐允许消费的次数。三者需要分别管理。

| 指标 | 说明 | 常见误区 |
| --- | --- | --- |
| QPS | 控制单位时间内的请求频率 | 只限制同时运行的任务数，却没有限制发起速度 |
| 并发 | 受请求频率和单次耗时共同影响 | 把 5 QPS 理解为只能同时存在 5 个请求 |
| 调用额度 | 按目标接口与套餐的计费规则消费 | 以为加购次数包就会提高 QPS |

例如每秒均匀发起 5 次请求、平均耗时 2 秒，稳定负载下约有 10 个请求同时进行。这只是估算；实际还需要考虑超时、重试与耗时波动。QPS 扩展提高的是允许的请求频率，不保证单次响应更快，也不增加调用额度。

## 如何安排请求频率

普通正式调用默认额度为 5 QPS；已有扩展或特殊约定时，以当前接口权益为准。同一 AppKey 对同一接口的多个任务需要合并计算请求频率，不要让每个任务都按完整额度发送。

将请求均匀分散，并设置有界队列、最大并发与任务超时。例如希望保持 4 QPS，可将请求发起间隔安排为约 250 毫秒，而不是每秒开始时同时发出 4 次请求。多个进程或服务需要共同控制速率；重试请求也要占用同一份预算。

收到频率受限响应时先降低发送速度；响应提供有效的 `Retry-After` 时按提示等待。部分响应会提供 `X-RateLimit-Limit` 和 `X-RateLimit-Remaining`，可辅助观察当前限制，但不能把剩余值当作已预留的容量。完整处理方法见 [错误与重试](https://www.gugudata.com/developers/errors-and-retries)。

## 什么时候需要升级

先排除重复调用、任务扎堆和无上限重试。如果合理排队后仍无法在业务要求的时间内完成任务，再考虑扩展。接口本身的处理耗时、网络问题或额度不足，应分别排查，不能通过提高 QPS 一并解决。

目前标准扩展将符合条件的有效订阅从 5 QPS 提升至 10 QPS，仅适用于关联订单对应的接口。次数包和订阅是不同的购买方式，不能假定次数包具备同样的扩展入口。更高容量或特殊接入需求可 [联系支持团队](https://www.gugudata.com/contact)。

## 如何升级与确认生效

1. 登录 [开发者中心](https://www.gugudata.com/portal/)，找到目标接口的 APP KEY 管理记录。
2. 点击“升级 QPS”。没有入口时先确认订阅是否已支付、仍在有效期内，以及是否已有扩展订单。
3. 核对目标接口、扩展到的 QPS、有效期和应付金额，确认后再支付。
4. 支付成功后查看订单与扩展状态。系统自动处理扩展；在确认生效前，继续按原容量调用，不要重复购买。
5. 确认生效后逐步增加请求频率，观察限流响应、耗时和任务完成情况。验证请求仍遵循接口计费规则，不需要用持续压测确认升级。

扩展费用按当前有效订阅周期的实付金额的一半，再按剩余有效期比例折算，金额以结算页为准；有续费记录时，不应直接使用最初订单金额估算。QPS 扩展不使用新用户优惠券，也不单独延长接口订阅有效期。续费后应重新确认扩展期限，不要假定原扩展自动延续。

## 常见问题与下一步

| 问题 | 建议处理 |
| --- | --- |
| 支付后仍然限流 | 确认扩展已完成、调用的是对应接口与 AppKey，再检查所有任务的合计频率；暂未生效时保留订单号联系支持 |
| 没有“升级 QPS”入口 | 核对订阅状态、有效期和已有扩展记录；仍无法判断时联系支持，不拼接购买链接反复尝试 |
| 频率不高但任务很慢 | 检查单次响应耗时、网络、并发和排队时间，分别定位瓶颈 |
| 已升级但提示额度不足 | 检查产品额度与消费记录，QPS 扩展不会补充调用次数 |

排查时保留接口名称、发生时间、请求频率、HTTP 状态及脱敏响应；不要附上真实 AppKey。凭据或产品权限不匹配时，继续阅读 [鉴权与 AppKey](https://www.gugudata.com/developers/authentication)。

升级前可以通过 [请求分析与日志](https://www.gugudata.com/developers/portal/monitoring) 确认高峰流量；其他购买记录与续费操作见 [订单与续费管理](https://www.gugudata.com/developers/portal/orders)。