Batch API：减少带宽浪费，提升 API 效率

开发者在发送数千个独立的 API 调用时，常常会遇到响应缓慢和网络成本高昂的问题。Batch API 通过将多个独立请求合并为一个操作，降低了延迟、带宽使用和连接开销。

本文将解释什么是 Batch API、它与标准 API 的区别，以及 Novita AI 的 Batch API 如何通过结构化的 JSONL 输入、高效的文件处理和可靠的错误追踪来实现大规模异步推理。同时，文章还将概述成本、延迟和吞吐量等关键效率因素，并提供简洁的实施与监控指南。

[试用批处理推理，享受 50% 折扣

更快、更便宜地运行大规模预测，支持以下模型：
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8。](https://novita.ai/docs/guides/llm-batch-api)

试用批处理推理，享受 50% 折扣

更快、更便宜地运行大规模预测，支持以下模型：
qwen/qwen3-vl-235b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8。

什么是 Batch API？

Batch API：将多个独立的 API 调用（如 GET、POST、PUT、DELETE）组合成一个 HTTP 请求。
响应结构：服务器按顺序返回所有子请求的结果，并标明每个请求的成功或失败状态。

Batch API 与标准 API 的关键区别

普通请求

Client
 ├──► Request 1 (/user/1)
 │       └──► Server Response 1
 ├──► Request 2 (/user/2)
 │       └──► Server Response 2
 └──► Request 3 (/order)
         └──► Server Response 3

批量请求

Client
 └──► Single Request (/batch)
          ├─ Sub-request 1: GET /user/1
          ├─ Sub-request 2: GET /user/2
          └─ Sub-request 3: POST /order
          ↓
       Server processes all
          ↓
       Combined Response:
          [Result1, Result2, Result3]

Batch API 可以帮助：

减少网络延迟 —— 发送一个合并请求，而不是多个请求。

降低带宽和连接开销 —— 共享头部和握手过程。

提升客户端性能 —— 尤其是在移动端或慢速网络环境下。

简化事务逻辑 —— 实现统一的错误处理或回滚。

优化 API 网关吞吐量 —— 防止请求洪泛。

Batch API 的典型使用场景

场景	描述
1. 批量数据查询	一次性获取多个用户、产品或帖子，避免重复请求。
2. 批量写入或更新	一次操作创建或更新多条记录（如批量上传、库存更新）。
3. 前端性能优化	减少浏览器或移动应用发起的 HTTP 调用次数，加快加载速度。
4. 后端任务聚合	在微服务系统中，将多个内部 API 调用合并为一次外部调用。
5. 数据同步	同步多个资源状态或执行批量操作（如打标签、删除）。
6. 速率限制优化	通过合并请求降低 API 网关负载并节省带宽。

影响 Batch API 效率的关键因素

相比实时 API，Batch API 能节省多少成本？

行业分析 (Growth-onomics) 显示，成本可降低约 20–45%，主要得益于更少的网络往返、更低的连接开销以及集中的处理过程。但具体节省取决于调用频率、批次大小和系统设计。

延迟方面——Batch API 真的能“在 24 小时内”完成吗？

Batch API 通常异步运行，延迟远高于实时 API；许多系统会按小时或按天执行，因此“24 小时内”取决于 SLA 而非保证。

批次大小或文件大小会影响速度吗？

是的。更大的批次（例如更多 JSONL 行数）会几乎线性地增加传输和解析时间；虽然吞吐量得以提升，但每个批次的完成总时间会增加。

为什么 Batch API 更适合高吞吐量工作负载？

通过将数千个请求聚合成一个处理过程，Batch API 减少了每次调用的开销，并允许并行执行或缓存复用。在大规模操作中，吞吐量通常可提升 17–92%，但代价是更高的延迟。

如何使用 Batch API？

Novita 的 Batch API 与 OpenAI 的接口高度兼容，支持 /v1/chat/completions 和 /v1/completions，因此现有代码只需少量修改即可复用。它接受 .jsonl 输入文件，其中每一行代表一个发送给相同模型的独立请求，并通过唯一的 custom_id 进行跟踪。输出也采用 JSONL 格式，使大规模的后处理、分析和集成变得简单高效。

立即试用 Novita AI 的 Batch API 服务！

1. 准备批量输入文件

创建一个 .jsonl 文件，其中 每一行是一个 JSON 格式的 API 请求。
示例 (batch_input.jsonl)：

{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}

规则：

• 每行一个请求。
• 所有请求必须使用相同的模型。
• 每行必须包含一个唯一的 custom_id。

2. 上传输入文件并创建批次

使用 Python 或 curl 上传文件并立即启动批量任务。

Python

from openai import OpenAI

client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")

# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")

batch = client.batches.create(
    input_file_id=uploaded.id,
    endpoint="/v1/chat/completions",
    completion_window="48h"
)

print("file_id:", uploaded.id)
print("batch_id:", batch.id)

curl

export API_KEY="YOUR_API_KEY"

# Upload file
upload_response=$(curl -s -X POST \
  -H "Authorization: Bearer ${API_KEY}" \
  -F 'file=@batch_input.jsonl' -F 'purpose=batch' \
  https://api.novita.ai/openai/v1/files)

# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')

curl -X POST https://api.novita.ai/openai/v1/batches \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"

查看你的 API Key

3. 检查批次状态

你可以随时使用批次 ID 检查进度。

batch = client.batches.retrieve("batch_xxx")
print(batch.status)

状态包括：

• VALIDATING – 输入文件正在校验
• PROGRESS – 运行中
• COMPLETED – 成功完成
• FAILED – 失败
• EXPIRED – 超出 48 小时窗口

4. 获取结果

完成后，通过 output_file_id 下载结果文件：

output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))

输出中的每一行对应一个输入，通过 custom_id 匹配。

提示：

仅支持 deepseek/deepseek-r1-0528

每批最多 50 000 个请求

输入文件 ≤ 100 MB

完成窗口固定为 48 小时

输出保留 30 天

Batch API 中如何处理失败的请求？

批量处理过程中遇到的错误会记录在单独的 错误文件 中，可通过 error_file_id 字段访问。每个失败的子请求都包含错误代码和描述。常见示例：

错误码	描述	解决方案
400	请求格式无效	检查 JSONL 语法和必填字段
401	身份验证失败	验证 API 密钥
404	批次未找到	检查批次 ID
429	超过速率限制	降低请求频率
500	服务器错误	联系提供商或稍后重试

开发者应仅重新处理失败的条目（使用重试队列或较小的后续批次），而不是重新提交整个原始文件。

Novita AI 为 Batch API 操作提供了哪些端点？

端点	用途
创建批次	提交一个包含多个请求的批量任务。
检索批次	通过批次 ID 获取特定批次的状态或结果。
取消批次	在完成前停止正在运行的批量任务。
列出批次	列出账户下所有已提交的批量任务。
上传文件	上传输入数据文件（例如 JSONL）。
列出文件	查看所有已上传的文件。
检索文件	通过文件 ID 获取文件元数据。
删除文件	删除一个已上传的文件。
检索文件内容	下载文件的实际内容（例如结果或错误日志）。

Batch API 将许多小请求整合到一个高效的工作流中。通过使用 Novita AI 的 Batch API，开发者可以降低高达 45% 的网络成本，将吞吐量扩展至每批最多 50 000 个请求，并通过内置的日志和检索端点简化错误处理。虽然牺牲了实时性，但对于批量推理、同步和数据处理工作负载，它提供了卓越的效率。

Novita AI 是一个 AI 云平台，为开发者提供使用简单 API 部署 AI 模型的便捷方式，同时也提供经济实惠且可靠的 GPU 云服务用于构建和扩展。

推荐阅读

• 提示缓存：使用 Novita AI 实现稳定低成本缓存
• 比较 Kimi K2-0905 API 提供商：NovitaAI 为何脱颖而出
• 如何访问 Qwen3-VL-235B-A22B 并构建更智能的代码演示