大模型 API 限流与重试最佳实践

在使用大模型 API 时，最常见也最头疼的问题莫过于“429 Too Many Requests”。无论是每分钟请求数（RPM）还是每秒令牌数（TPM）耗尽，如果没有合理的限流应对策略，你的应用就会在关键时刻掉链子。本文将拆解 API 限流背后的逻辑，并结合代码示例，分享一套生产可用的重试最佳实践。

## 理解限流：它为什么要拒绝你

API 限流是服务端为了保护基础设施、实现公平调度而设置的流量控制机制。常见的限流维度包括：

- **每分钟请求数（RPM）**：例如 500 次请求/分钟 - **每分钟令牌数（TPM）**：例如 100 万 tokens/分钟 - **并发连接数**：限制同时打开的 WebSocket 或 SSE 通道

当客户端超过阈值时，服务端会返回 `429` 状态码，并在响应头中带上 `Retry-After`（秒数）或 `X-RateLimit-Reset` 等提示。合理的客户端必须尊重这些信号，而不是无脑重试。

## 重试策略：别让重试变成“惊群”

### 1. 指数退避 + 随机抖动

最简单的重试是固定间隔，但这会加剧冲突。推荐使用“指数退避 + 随机抖动”：

``` backoff_time = min(base_delay * (2 ** attempt), max_delay) jitter = random.uniform(0, backoff_time * 0.5) sleep_time = backoff_time + jitter ```

这种组合让重试在时间上分散，避免多个客户端同时发起请求造成二次过载。

### 2. 尊重 `Retry-After` 头

如果响应里带有 `Retry-After`，应优先使用该值，它是服务端最准确的恢复指示。代码中可以这样处理：

```python def get_retry_after(response): retry_after = response.headers.get('Retry-After') if retry_after: try: return int(retry_after) except ValueError: pass return None ```

### 3. 使用成熟的退避库

手动实现退避逻辑容易出错，推荐 Python 的 `tenacity` 或 `backoff` 库。以下是基于 `backoff` 的健壮示例：

```python import backoff import requests import random

@backoff.on_exception( backoff.expo, # 指数退避 requests.exceptions.HTTPError, max_tries=5, # 最多重试5次 max_time=120, # 总重试时间不超过120秒 giveup=lambda e: e.response.status_code != 429 # 只在429时重试 ) def call_llm(url, payload, api_key): headers = {"Authorization": f"Bearer {api_key}"} response = requests.post(url, json=payload, headers=headers) if response.status_code == 429: # 如果存在 Retry-After，将其作为退避的“特殊”处理 # 这里简单抛出，让 backoff 自动等待 raise requests.exceptions.HTTPError(response=response) response.raise_for_status() return response.json() ```

`backoff.expo` 默认的退避因子是 2，并自动加入随机抖动，无需自己计算。若需要完全遵循服务端的 `Retry-After`，可以自定义 `factor` 或结合 `wait_gen`。

### 4. 客户端侧预限流

除了被动重试，还应在客户端实现速率控制。可以使用令牌桶（Token Bucket）或信号量，预先限制发出的请求速率，从源头减少 429 的发生。

### 5. 熔断与降级

当重试次数过多或时间内一直命中 429，应该触发熔断，暂停请求并快速失败，返回缓存数据或备用回复，避免雪崩。可以加入 gRPC 拦截器或 API 网关层统一处理。

## 一次配置，多模型无忧

虽然我们可以花大量时间针对每个模型 API 调优重试策略，但如果你同时接入了 DeepSeek、Qwen、Claude、Gemini 等多种模型，维护各自的限流逻辑会让代码变得臃肿。此时一个统一的中转站能极大减轻负担。

**TokenPocket API 中转站** (https://tokenpocket.site) 正是为此而生。它支持 DeepSeek、Qwen、Claude、Gemini 等主流模型的统一调用，全系按量计费，无需规划复杂的各厂商限流规则，新用户注册即送免费额度。你只需一个 token，一个 endpoint，就能用完全相同的调用风格访问所有模型，内部已优化好重试与容错，把你的精力留给业务创新。