# 两万条 LLM 批量请求，缺的不是速度而是刹车

> 并发、节奏、超时、重试四道限制，告别 429 风暴、PoolTimeout 和卡在 97%。

原文: https://fdetimes.net/zh/guides/python-asyncio-llm-batch-rate-limits/

客户发来 20,000 张客服工单，要求周一早上之前用 LLM 完成分类。顺序执行的 `for` 循环估计要跑一整天，于是你改用 `asyncio.gather`，一次性全部发出去。屏幕上先是满屏的 429 错误，接着是 `PoolTimeout`，到 97% 时脚本卡住不动了。

几乎每个前线部署工程师（FDE）都遇到过这种情况，无论对面是 OpenAI 的 API、Anthropic 的 API，还是客户老旧的内部系统。问题不在于慢：慢的任务终究会跑完。

真正出问题的，是一个**没有刹车**的脚本。本指南介绍需要装上的四道刹车、一个完整的管道，以及如何正确解读 429，判断什么时候该等、什么时候该停。

## 为什么一次全发出去反而更慢？

每个 API 都有限额。OpenAI 的文档写得很明确：超出限额的请求会暂时收到 `429` 错误。20,000 个协程一起排队时，大多数只会收到 429，然后在同一时刻重试，再一起被拦下。

客户端也会堵住。httpx 维护一个大小有限的连接池。请求等待连接的时间超过 `pool` 超时，就会抛出 `PoolTimeout`，说明你创建的并发请求超过了连接池能提供的连接数。

卡在 97%，通常是因为某个请求卡住了，却没有任何机制把它切断；或者某个重试循环没有出口。这类错误不会暴露出来。脚本就那样停着，你也看不出它卡在哪里。

## 光有 Semaphore 不够，还要控制节奏

第一道刹车是 `asyncio.Semaphore`。Python 文档将它描述为一个永远不会低于零的计数器。计数器归零时，调用 `acquire()` 的任务会等待，直到另一个任务调用 `release()`。使用 `Semaphore(20)`，同时运行的请求永远不会超过 20 个。

接下来这一点常被忽略。Anthropic 说明其 API 采用令牌桶算法：容量持续补充，而不是在每分钟开始时重置。因此 60 RPM 的限额实际上可能按每秒 1 个请求执行，短时间的突发请求就可能超限。

设想 20 个请求并行，每个只需 300 ms。一秒之内你就发出了约 60 个请求，用光了整分钟的配额，而并发数从未超过 20。

**要点:** 只限制并发请求数还不够，还必须让发送速度保持平稳。

所以第二道刹车是限速器，它强制两次发送之间保持最小间隔。Anthropic 还建议逐步提升流量、保持用量平稳，以免触发加速限制。实践中，先用较大的间隔起步，在最初几分钟内逐步缩小。

两道刹车分工不同，动手前最好先算一笔账。限速器决定吞吐量上限：每秒 1 个请求，20,000 张工单就要 20,000 秒，约 5.5 小时，无论允许多少请求并行都一样。

Semaphore 限制的是在途请求数。这个数大致等于发送速度乘以单个请求的耗时：如果每次 LLM 调用耗时 10 秒，在途请求约为 10 个，所以 `Semaphore(20)` 主要是在 API 异常变慢时兜底。

如果 5.5 小时仍赶得上周一的截止时间，就让任务跑一夜。如果赶不上，调大 Semaphore 也不会让任务变快，该做的是请客户申请更高的配额。

## 分类 20,000 张工单的管道

下面是用 httpx 调用分类 API 的骨架代码。剩下的两道刹车是超时和有上限的重试。请仔细看这些数字：每个都位于不同的层。

```python
import asyncio, random, time
import httpx

MAX_CONCURRENT = 20
MIN_INTERVAL = 1.0      # 60 RPM -> 每秒 1 个请求 -> 20,000 张工单约 5.5 小时
RETRY_BUDGET_S = 120    # 重试允许的总时长
PER_ITEM_S = 150        # 每张工单的硬性上限

# 与服务商相关的开关：
# Anthropic：消费上限的 429 不带 retry-after，重试无用 -> True
# OpenAI：缺少该响应头时，使用指数退避 + 抖动 -> False
STOP_ON_BARE_429 = True

class SpendLimitError(Exception):
    """Anthropic 式的消费上限 429，不带 retry-after：重试无用。"""

class Pacer:
    def __init__(self, interval: float):
        self.interval = interval
        self._lock = asyncio.Lock()
        self._next = 0.0

    async def wait(self):
        async with self._lock:
            now = time.monotonic()
            if self._next > now:
                await asyncio.sleep(self._next - now)
            self._next = max(now, self._next) + self.interval

def retry_after_seconds(resp):
    try:
        return float(resp.headers["retry-after"])
    except (KeyError, ValueError):
        return None

async def call_with_retry(client, pacer, payload, max_attempts=5):
    start = time.monotonic()
    for attempt in range(max_attempts):
        await pacer.wait()
        resp = await client.post("/classify", json=payload)
        if resp.status_code not in (429, 503):
            resp.raise_for_status()
            return resp.json()
        if (resp.status_code == 429 and STOP_ON_BARE_429
                and "retry-after" not in resp.headers):
            raise SpendLimitError("429 且没有 retry-after")  # 停止，不要重试
        wait = retry_after_seconds(resp)
        if wait is None:                      # 响应头缺失或无效（开关关闭），或 503
            wait = min(2 ** attempt, 30)      # 指数退避
        wait += random.uniform(0, 1)          # 抖动
        if time.monotonic() - start + wait > RETRY_BUDGET_S:
            break
        await asyncio.sleep(wait)
    raise RuntimeError(f"重试次数已用尽，最后状态码 {resp.status_code}")

async def worker(client, sem, pacer, ticket):
    async with sem:
        try:
            async with asyncio.timeout(PER_ITEM_S):
                result = await call_with_retry(client, pacer, ticket)
            return {"id": ticket["id"], "ok": True, "result": result}
        except SpendLimitError:
            raise                             # 让 TaskGroup 取消整个任务
        except Exception as e:
            return {"id": ticket["id"], "ok": False, "error": repr(e)}

async def main(tickets):
    sem = asyncio.Semaphore(MAX_CONCURRENT)
    pacer = Pacer(MIN_INTERVAL)
    limits = httpx.Limits(max_connections=MAX_CONCURRENT)
    timeout = httpx.Timeout(60.0, pool=30.0)
    try:
        async with httpx.AsyncClient(base_url="https://api.khach.example",
                                     limits=limits, timeout=timeout) as client:
            async with asyncio.TaskGroup() as tg:
                tasks = [tg.create_task(worker(client, sem, pacer, t))
                         for t in tickets]
    except* SpendLimitError:
        print("已触达消费上限：停止任务，通知客户的账号负责人")
        raise
    return [t.result() for t in tasks]
```

重试逻辑遵循 OpenAI 的建议。`Retry-After` 的值只是**最短**等待时间：至少等这么久，再加上一小段随机时间。

如果该响应头缺失或无效，就退回到带抖动的指数退避，避免所有客户端同时重试。重试要同时限制尝试次数和总时长，这里是 5 次和 120 秒。

遇到不带该响应头的 429 时直接停止，这个分支由 `STOP_ON_BARE_429` 开关控制，必须按服务商分别设置。对 Anthropic，文档说明消费上限的 429 不带 `retry-after`，重试无用，所以打开开关是合理的。

对 OpenAI，官方建议在缺少该响应头时退避，所以要关掉开关。如果调用的是客户的 API，先问清他们如何表示“不要重试”，再相应修改这一个条件。

超时分三层。httpx 默认在 5 秒没有网络活动后抛出 `TimeoutException`。对需要生成长回复的 LLM 调用来说太短，这里调到 60 秒。中间一层是 120 秒的重试预算，最外层 `asyncio.timeout(150)` 包住全部逻辑，把任何卡住的情况都转成 `TimeoutError`，保证没有工单会永远挂起。

## 哪些错误该兜住，哪些该放行

容易忽略的细节是，`try/except` 位于 worker **内部**。使用 `TaskGroup` 时，只要有任务第一次因 `CancelledError` 以外的异常失败，组内其余任务都会被取消。一张坏工单不能连累另外 19,999 张，所以 worker 自己捕获普通错误，返回一条 `ok: False` 的记录。

而对 `SpendLimitError`，这种取消行为正是你想要的。worker 重新抛出它，TaskGroup 取消所有剩余任务，`main` 通过 `except*` 捕获。任务立即停止，而不是让成千上万张工单一个接一个撞上同一堵墙。

为什么不用 `gather`？默认情况下，`gather` 会传播第一个异常，但其他可等待对象**不会被取消**，会继续运行。

你的 `main` 函数已经返回，请求却还在途，一些极难追查的 bug 就来源于此。使用 TaskGroup，一旦有错误抛出，其余任务都会被取消，不会留下脱离控制、仍在运行的请求。

## 不是每个 429 都该重试

如果通过官方 SDK 调用，不要再自己写上面那套重试循环。OpenAI 的文档说明，每个官方 SDK 都会按照其重试配置，自动重试符合条件的 `429` 和 `503` 响应。

算一笔账：如果 SDK 每次调用重试几次，你的循环再尝试 5 次，实际发出的请求数是两者的乘积，而不是相加。保留 Semaphore、限速器和超时，重试则在 SDK 的配置中调整。

还有另一种 429。根据 Anthropic 的文档，组织触达消费上限时，429 响应**不带** `retry-after` 响应头，在恢复访问之前，所有重试（包括 SDK 的自动重试）都会失败。这就是为什么对接 Anthropic 时，上面的代码打开开关并抛出 `SpendLimitError`，而不是继续退避。

如果使用 Anthropic 的 SDK，请在日志或 SDK 返回的异常中检查这个响应头。一旦遇到这种情况，就停止任务并通知客户的账号负责人。

## 客户现场的常见错误

第一，Semaphore 大于 httpx 的 `max_connections`。多出来的请求在连接池里等待并收到 `PoolTimeout`，看起来像网络错误，实际上是配置错误。让这两个数字保持一致。

第二，重试没有时间预算。尝试 5 次，每次都等 60 秒的 `Retry-After`，一张工单就要耗上五分钟。第三，日志只记录错误总数。如果结果里每张工单都带有 `id` 和 `error`，你只需重跑失败的 312 张，而不是全部 20,000 张。

最后一个是在客户系统上从第一分钟就满负荷运行。他们的内部 API 不一定会像 OpenAI 那样礼貌地返回 429，可能直接崩掉。先问清真实限额，再逐步加量。

## 这项技能如何体现在简历上

阅读 FDE 岗位描述时，留意关于对接客户 API 或处理大批量数据的条目：这正是这项技能的用武之地。

在简历上，与其写“精通 asyncio”，不如写成果：通过有速率限制的 API 处理了 N 条记录，使用节奏控制和有上限的重试，按记录报告错误，没有任何任务挂起。

面试时，讲清楚 `TaskGroup` 与 `gather` 有何不同，或者为什么对 Anthropic 来说不带 `retry-after` 的 429 意味着该停而不是该重试，远比罗列库名更有说服力。

好的批处理脚本不必最快。它需要跑完，并且在客户问起之前，就能准确告诉你哪些工单没有完成、原因是什么。

**本周动手试试:**

- 找一个使用无限制 asyncio.gather 的批处理脚本，加上 Semaphore、限速器和 asyncio.timeout，用 500 条记录测试。
- 检查使用 OpenAI 或 Anthropic 官方 SDK 的代码，删除叠加在 SDK 之上的手写重试循环，只在一处设置 max_retries。
- 让任务输出一个结果文件，每条记录带 ok/error 列，再按类型统计错误，决定是否重跑。

## 信源

- [Rate limits (OpenAI API docs)](https://developers.openai.com/api/docs/guides/rate-limits)

- [Synchronization Primitives — Python 3.15.0 documentation](https://docs.python.org/3/library/asyncio-sync.html)

- [Coroutines and tasks — Python 3.15.0 documentation](https://docs.python.org/3/library/asyncio-task.html)

- [Timeouts - HTTPX](https://www.python-httpx.org/advanced/timeouts/)

- [Rate limits (Claude API docs)](https://platform.claude.com/docs/en/api/rate-limits)
