两万条 LLM 批量请求,缺的不是速度而是刹车
并发、节奏、超时、重试四道限制,告别 429 风暴、PoolTimeout 和卡在 97%。
要点速览
- Semaphore 只限制同时运行的请求数。API 仍可能按秒执行限额,所以还需要限速器,而任务总耗时由限速器决定。
- 每一层等待都要有自己的上限:httpx 超时、重试的时间预算,以及外层的 asyncio.timeout。
- 在 worker 内部捕获单条记录的错误;触达消费上限这类错误则放行,让 TaskGroup 取消整个任务。
客户发来 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 的骨架代码。剩下的两道刹车是超时和有上限的重试。请仔细看这些数字:每个都位于不同的层。
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 意味着该停而不是该重试,远比罗列库名更有说服力。
好的批处理脚本不必最快。它需要跑完,并且在客户问起之前,就能准确告诉你哪些工单没有完成、原因是什么。
这篇文章对你有帮助吗?
感谢你的反馈!