Python 批量请求:兼容 OpenAI 的 LLM API
对于 LLM API 批量 Python 工作,你不需要专用的批量接口:你需要一个遵守速率限制的 worker 池、针对 HTTP 429 的重试规则,以及一个可以从中恢复的结果文件。本指南使用指向你基础 URL 的 OpenAI SDK 构建这三部分。

要点
- API 有两个方法:聊天补全和模型,因此批量处理通过并发请求池在客户端完成。
- 完整密钥允许 8 个并发请求和每分钟 300 次;试用密钥允许 2 个和每分钟 60 次。调整你的池大小以匹配这些限制。
- 使用 Retry-After 标头在 429 时重试,并区分速率限制和并发。
- 每完成一个结果就写入 JSONL 文件,这样崩溃只损失几分钟,而不是整个运行。
这里的批量处理机制
该接口兼容 OpenAI,暴露 POST /v1/chat/completions 和 GET /v1/models。没有单独的作业提交端点来接收文件并稍后返回作业 ID。因此,批量处理是对正常请求的循环,并发运行,并将限制内置于你的代码中。这比听起来更简单,并且它会在请求完成时返回结果,而不是等到最后。
决定设计的关键数字是限制。完整密钥允许 8 个并发请求和每分钟 300 次请求。试用密钥允许 2 个并发和每分钟 60 次。最大请求体为 8 MB。流式请求会占用并发槽位直到流结束,因此批量工作请保持流式输出关闭。
为什么不一次性发送所有请求?因为批量处理是一个有上限的吞吐量问题,而这个上限需要你来遵守。一个以 Python 能创建请求的最快速度发送 5,000 个请求的循环会收到一堵 429 响应墙,在重试上浪费时间,并将有用的错误淹没在噪音中。一个最多保持 8 个请求在进行的池会让处理以服务允许的速度进行,并且无论你有 50 行还是 500,000 行,代码都是相同的。规划三个部分:有界池、一个重试规则和一个只追加的结果文件。
模型 ID 是 uncensored,认证方式是 Authorization: Bearer <key>,Base URL 是 https://api.unfilteredvideo.com/v1。如果你还没有密钥,API 密钥页面提供一键获取 $0.50试用额度。
安装和设置
你需要 Python 3.9 或更高版本以及官方的 openai 包。将密钥放在环境变量中,而不是脚本中。
pip install openai
export API_KEY="paste-your-key-here"
# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"
模型列表应显示 uncensored。现在准备你的输入为 JSONL 文件,每行一个对象,包含 id 和要处理的文本。id 用于稍后恢复。
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
保持在限制内的线程池
对于大多数脚本,ThreadPoolExecutor 是最短路径。OpenAI 客户端在线程间共享是安全的,且工作是网络绑定的,因此线程适合。将池大小设置为你的并发限制,不要更高:额外的工作者只会收集 429 错误。
import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8 # use 2 on a trial key
def run_one(row):
resp = client.chat.completions.create(
model=MODEL,
temperature=0.2,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
return {
"id": row["id"],
"output": resp.choices[0].message.content,
"in": resp.usage.prompt_tokens,
"out": resp.usage.completion_tokens,
}
rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
futures = [pool.submit(run_one, r) for r in rows]
for f in as_completed(futures):
out.write(json.dumps(f.result()) + "\n")
out.flush()
此版本没有重试和恢复功能,因此它只是一个起点。客户端使用 max_retries=0 创建,因为 SDK 默认会自行重试,而你希望有一个地方拥有重试规则。接下来的两部分将添加该规则和恢复逻辑。
正确处理 429
此 API 有三种 429 错误,需要略有不同的反应:
rate_limited:你在一分钟内发送了太多请求。放慢速度。减少工作线程数量的池或短暂睡眠可以解决。concurrency:同时处于飞行状态的请求太多。你的池比限制大,或者你有忘记关闭的流。- 临时过载:带有
Retry-After: 5标头的 429。你的代码没有问题。等待规定的时间并重试。
一个重试辅助函数涵盖所有三种情况。当存在 Retry-After 时等待,否则以少量抖动指数退避。失败和被拒绝的请求不收费,因此重试是免费的。
import random, time
import openai
from openai import OpenAI
client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
def call_with_retry(messages, attempts=6):
for n in range(attempts):
try:
return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
except openai.RateLimitError as e:
wait = e.response.headers.get("Retry-After")
delay = float(wait) if wait else min(60, 2 ** n) + random.random()
print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
time.sleep(delay)
except (openai.APIConnectionError, openai.APITimeoutError):
time.sleep(min(30, 2 ** n))
raise RuntimeError("gave up after %d attempts" % attempts)
不要对所有错误盲目重试。400 意味着你的请求有误,例如超过 8 MB 的请求体或格式错误的消息,再次发送会以相同方式失败。记录行 id 并继续。
带信号量的异步版本
如果你的脚本已经在事件循环中运行,或者你想为 Web 服务提供数据,请使用 AsyncOpenAI 和 asyncio.Semaphore 来限制进行中的请求。信号量起到池大小的作用。
import asyncio, json, os
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)
async def run_one(row, out):
async with sem:
resp = await client.chat.completions.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
out.flush()
async def main():
rows = [json.loads(l) for l in open("input.jsonl")]
with open("output.jsonl", "a") as out:
await asyncio.gather(*(run_one(r, out) for r in rows))
asyncio.run(main())
使用与上述相同的重试逻辑包装调用,使用 await asyncio.sleep 代替 time.sleep。一个注意事项:gather 与数万个协程一起使用时会一次性创建它们。对于非常大的输入,请以几千行为单位对文件进行切片处理。
使运行可恢复
长时间作业会以无聊的方式失败:笔记本电脑休眠、连接断开、你按下 Ctrl+C。由于每个完成的行都以其 id 追加到 output.jsonl,恢复意味着跳过你已经拥有的 id。
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"
def done_ids(path="output.jsonl"):
if not os.path.exists(path):
return set()
return {json.loads(line)["id"] for line in open(path) if line.strip()}
finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")
将 todo 输入到上述任一池中。以追加模式打开输出文件,不要使用写入模式,否则重启会擦除你的进度。还将错误写入第二个文件 errors.jsonl,以便在读取失败原因后重新运行失败的项。
为了在重运行时获得可重复的输出,传递固定的 seed 和低 temperature。seed 会与 top_p、stop 和惩罚一起传递给模型。
先在小样本上测试
在运行 20,000 行之前先运行 20 行。选择包含最坏情况的行:最长输入、包含奇怪字符的输入、空输入。肉眼检查输出,检查 usage 是否与你的成本估算匹配,并通过暂时将 worker 计数提高到限制以上来确认重试辅助函数的行为。你应该在日志中看到带有代码 concurrency 的 429,等待,然后成功重试。在 20 行上看到这一点,比在 9,000 行时发现要好得多。
如果任务需要结构化输出,请添加 JSON 模式,使用 response_format={"type": "json_object"},在提示词中描述键,并在 try 块中解析每次回复。统计测试片段中的解析失败次数。如果失败率超过一两个百分点,通常意味着提示词需要更清晰的结构定义,而现在修复它比稍后重新运行更便宜。无法解析的行会写入 errors.jsonl,并附带其 id,恢复逻辑将其视为未完成。
最后,设置适合你最长预期输出的客户端超时。SDK 接受客户端或每个请求的 timeout=60;否则,卡住且永不返回的请求将占用你的 8 个槽位之一,直到它停留在那里。
池大小估算和时间预估
吞吐量受两个因素限制:并发数除以单个请求的耗时,以及每分钟请求数上限。对于完整账户密钥,上限为每分钟 300 次,即每秒 5 次。如果典型请求耗时 2 秒,8 个工作线程会产生 8 / 2 = 4 次每秒请求,或每分钟 240 次,这低于上限。如果请求耗时 1 秒,8 个工作线程会尝试达到每秒 8 次并触及上限,因此请添加少量延迟或接受偶尔的 429 错误,你的重试辅助函数会吸收这些错误。
以每秒 4 次的速度,10,000 行需要 2,500 秒,约 42 分钟。在试用密钥下,具有 2 个并发请求和每分钟 60 次上限,上限为每秒 1 次,因此相同的 10,000 行需要 10,000 秒,近 2 小时 47 分钟。实际上,$0.50试用额度会在此之前耗尽,这使得它成为在几百行上测试脚本的好地方,而不是运行生产的地方。
大规模批量的成本
定价为每 1M 输入 token $0.15,每 1M 输出 token $0.50。以分类作业为例:50,000 行,每行约 200 输入 token 和 100 输出 token。
- 输入:50,000 × 200 = 10,000,000 个 token,即 10 × $0.15 = $1.50。
- 输出:50,000 × 100 = 5,000,000 个 token,即 5 × $0.50 = $2.50。
- 总计:$4.00,或每行 $0.00008。
上述脚本为每行记录 in 和 out,因此你可以从实际运行中计算相同数字。X-Balance-USD 响应标头也显示剩余额度,X-Request-Id 是在 docs 或支持页面寻求帮助时引用的内容。
预付额度以整美元充值,金额从 $20 到 $500 不等,其中 $50 起赠 +5%,$100 起赠 +10%,$200 起赠 +15%,支持加密货币支付(TRC20 链上的 USDT 或 Base 链上的 USDC)。额度永不失效。定价页面 包含完整详情。针对敏感数据集的说明:提示词不会用于模型训练。
更多指南
问答
API 是否有批量接口?
没有。API 提供 chat completions 和模型列表接口。你可以通过自己的代码并发发送多个普通请求来实现批量处理,全量密钥的并发限制为 8,每分钟请求上限为 300。
我应该使用多少个线程?
全量密钥使用 8 个工作线程,试用密钥使用 2 个工作线程,以匹配并发限制。增加工作线程只会导致代码层面的并发请求出现 429 错误。
收到 HTTP 429 错误时该怎么办?
如果响应中包含 Retry-After 值,请等待该时长;否则,等待几秒后重试。失败的请求不会扣费,因此重试不会产生额外费用。
我可以在批量任务中流式输出响应吗?
可以,但不建议这样做。流式请求会占用并发槽位,直到流结束,这会降低吞吐量。批量任务请关闭流式输出。