Batch API | OpenAI API

了解如何使用 OpenAI 的 Batch API 发送异步批量请求，成本降低 50%，享受独立且显著更高的速率限制池，并具有明确的 24 小时处理周期。该服务非常适合处理不需要立即响应的任务。您还可以直接在此处浏览 API 参考.

概览

虽然 OpenAI 平台的某些功能需要您发送同步请求，但在许多情况下，请求不需要立即响应，或者速率限制阻碍了您快速执行大量查询。批处理任务通常在以下用例中非常有用：

运行评估
对大型数据集进行分类
嵌入内容库
排队大型离线视频渲染任务

Batch API 提供了一套直观的端点，允许您将一组请求收集到单个文件中，启动批处理任务来执行这些请求，在底层请求执行期间查询该批次的状态，并在批次完成后最终检索汇总的结果。

与直接使用标准端点相比，Batch API 具有：

更高的成本效益： 相比同步 API 提供 50% 的成本折扣
更高的速率限制： 相比同步 API 具有显著更高的余量相比同步 API
快速的完成时间： 每个批次在 24 小时内完成（通常更快）

入门

1. 准备您的批处理文件

批次始于一个 .jsonl 文件，其中每一行包含对 API 的单个请求的详细信息。目前可用的端点有：

/v1/responses (Responses API)
/v1/chat/completions (Chat Completions API)
/v1/embeddings (Embeddings API)
/v1/completions (Completions API)
/v1/moderations (内容审核指南)
/v1/images/generations (Images API)
/v1/images/edits (Images API)
/v1/videos (视频生成指南)

对于给定的输入文件，每行 body 字段中的参数与底层端点的参数相同。每个请求必须包含一个唯一的 custom_id 值，您可以在完成后使用它来引用结果。以下是包含 2 个请求的输入文件示例。请注意，每个输入文件只能包含对单一模型的请求。

对于 Batch 中的视频生成：

Batch 目前支持 POST /v1/videos only.
Batch 的视频请求必须使用 JSON，而非 multipart。
请提前上传资产，并在请求体中传递支持的资产引用，而不是使用 multipart 上传。
使用 input_reference 用于 Batch 中的图像引导生成。在 JSON 请求中，将 input_reference 作为包含 file_id or image_url.
Multipart input_reference 上传（包括视频参考输入）在 Batch 中不受支持。
Batch 生成的视频在批次完成后最多可下载 24 小时。

当目标是 /v1/moderations, 包含一个 input 每个请求体中的字段。Batch 接受纯文本输入（用于 omni-moderation-latest and text-moderation-latest）和多模态内容数组（用于 omni-moderation-latest）。Batch 工作器执行与同步 Moderations API 相同的非流式请求要求，并将拒绝设置了 stream=true.

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo-0125", "messages": [{"role": "system", "content": "You are an unhelpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

Moderations 输入示例

纯文本请求：

1
2
3
4
5
6
7
8
9
{
  "custom_id": "moderation-text-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": "This is a harmless test sentence."
  }
}

多模态请求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "custom_id": "moderation-mm-1",
  "method": "POST",
  "url": "/v1/moderations",
  "body": {
    "model": "omni-moderation-latest",
    "input": [
      {
        "type": "text",
        "text": "Describe this image"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg"
        }
      }
    ]
  }
}

建议使用 image_url 引用远程资源（而非 base64 数据块），以使您的 .jsonl 文件远低于 200 MB 的 Batch 上传限制，这对于多模态 Moderations 请求尤为重要。

2. 上传您的批处理输入文件

与我们的 Fine-tuning API，您必须先上传输入文件，以便在启动批次时能正确引用它。请上传您的 .jsonl 文件使用 Files API.

上传 Batch API 的文件

javascript

1
2
3
4
5
6
7
8
9
10
import fs from "fs";
import OpenAI from "openai";
const openai = new OpenAI();

const file = await openai.files.create({
  file: fs.createReadStream("batchinput.jsonl"),
  purpose: "batch",
});

console.log(file);

1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()

batch_input_file = client.files.create(
    file=open("batchinput.jsonl", "rb"),
    purpose="batch"
)

print(batch_input_file)

1
2
3
4
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="batch" \
  -F file="@batchinput.jsonl"

1
2
3
openai files create \
  --file batchinput.jsonl \
  --purpose batch

3. 创建批次

成功上传输入文件后，您可以使用输入 File 对象的 ID 来创建批次。在本例中，假设文件 ID 是 file-abc123。目前，完成窗口只能设置为 24h。您还可以通过可选的 metadata parameter.

创建 Batch

javascript

1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.create({
  input_file_id: "file-abc123",
  endpoint: "/v1/chat/completions",
  completion_window: "24h"
});

console.log(batch);

1
2
3
4
5
6
7
8
9
10
11
12
from openai import OpenAI
client = OpenAI()

batch_input_file_id = batch_input_file.id
client.batches.create(
    input_file_id=batch_input_file_id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "description": "nightly eval job"
    }
)

1
2
3
4
5
6
7
8
curl https://api.openai.com/v1/batches \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

1
2
3
4
openai batches create \
  --input-file-id file-abc123 \
  --endpoint /v1/chat/completions \
  --completion-window 24h

此请求将返回一个 Batch 对象及其相关的元数据：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1714508499,
  "in_progress_at": null,
  "expires_at": 1714536634,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": null
}

4. 检查批次状态

您可以随时检查批次的状态，这同样会返回一个 Batch 对象。

检查批次状态

javascript

1
2
3
4
5
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.retrieve("batch_abc123");
console.log(batch);

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

batch = client.batches.retrieve("batch_abc123")
print(batch)

1
2
3
curl https://api.openai.com/v1/batches/batch_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2
openai batches retrieve \
  --batch-id batch_abc123

给定 Batch 对象的状态可以是以下任意一种：

状态	描述
`validating`	输入文件正在验证中，通过后批次才能开始运行
`failed`	输入文件未通过验证过程
`in_progress`	输入文件已成功通过验证，批次当前正在运行
`finalizing`	批次已完成，结果正在准备中
`completed`	批次已完成，结果已就绪
`expired`	批次未能在 24 小时时间窗口内完成
`cancelling`	批次正在取消（可能需要长达 10 分钟）
`cancelled`	the batch was cancelled

5. 获取结果

一旦批次完成，您就可以通过请求 Files API 通过 output_file_id Batch 对象中的字段，并将其写入您本机的文件中，在本例中为 batch_output.jsonl

获取批次结果

javascript

1
2
3
4
5
6
7
import OpenAI from "openai";
const openai = new OpenAI();

const fileResponse = await openai.files.content("file-xyz123");
const fileContents = await fileResponse.text();

console.log(fileContents);

1
2
3
4
5
from openai import OpenAI
client = OpenAI()

file_response = client.files.content("file-xyz123")
print(file_response.text)

1
2
curl https://api.openai.com/v1/files/file-xyz123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" > batch_output.jsonl

1
2
3
openai files content \
  --file-id file-xyz123 \
  --output batch_output.jsonl

The output .jsonl 输出文件中，对于输入文件中每个成功的请求行，都会有一行对应的响应。批次中任何失败的请求，其错误信息都将写入一个错误文件中，该文件可以通过批次的 error_file_id.

For /v1/videos, 已完成的批量结果包含已经达到终止状态的视频对象，例如 completed, failed, or expired。你可以使用返回的视频 ID 在批处理完成后立即下载最终资产。

请注意，输出行的顺序 可能不匹配 输入行的顺序。不要依赖顺序来处理结果，请使用 custom_id 字段，该字段将存在于输出文件的每一行中，方便您将输入中的请求映射到输出中的结果。

{"id": "batch_req_123", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_123", "body": {"id": "chatcmpl-123", "object": "chat.completion", "created": 1711652795, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello."}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 22, "completion_tokens": 2, "total_tokens": 24}, "system_fingerprint": "fp_123"}}, "error": null}
{"id": "batch_req_456", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "req_789", "body": {"id": "chatcmpl-abc", "object": "chat.completion", "created": 1711652789, "model": "gpt-3.5-turbo-0125", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello! How can I assist you today?"}, "logprobs": null, "finish_reason": "stop"}], "usage": {"prompt_tokens": 20, "completion_tokens": 9, "total_tokens": 29}, "system_fingerprint": "fp_3ba"}}, "error": null}

输出文件将在批次完成 30 天后自动删除。

6. 取消批次

如有必要，您可以取消正在进行的批处理。批处理的状态将更改为 cancelling 直到正在处理的请求完成（最多 10 分钟），之后状态将更改为 cancelled.

取消批处理

javascript

1
2
3
4
5
import OpenAI from "openai";
const openai = new OpenAI();

const batch = await openai.batches.cancel("batch_abc123");
console.log(batch);

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.batches.cancel("batch_abc123")

1
2
3
4
curl https://api.openai.com/v1/batches/batch_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST

1
2
openai batches cancel \
  --batch-id batch_abc123

7. 获取所有批处理的列表

您可以随时查看所有的批处理。对于拥有大量批处理的用户，可以使用 limit and after 参数来对结果进行分页。

获取所有批处理的列表

javascript

1
2
3
4
5
6
7
8
import OpenAI from "openai";
const openai = new OpenAI();

const list = await openai.batches.list();

for await (const batch of list) {
  console.log(batch);
}

1
2
3
4
from openai import OpenAI
client = OpenAI()

client.batches.list(limit=10)

1
2
3
curl https://api.openai.com/v1/batches?limit=10 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

1
2
openai batches list \
  --limit 10

模型可用性

Batch API 已广泛适用于我们的大多数模型，但并非全部。请查阅模型参考文档以确保您正在使用的模型支持 Batch API。

速率限制

Batch API 的速率限制与现有的按模型划分的速率限制相互独立。Batch API 包含三种类型的速率限制：

单批次限制： 单个批次最多可包含 50,000 个请求，批量输入文件最大可达 200 MB。请注意， /v1/embeddings 批处理还限制批次中所有请求的嵌入输入总数最多为 50,000 个。
每个模型排队的提示词令牌数： 每个模型在批处理中允许排队的提示词 token 数量都有上限。您可以在平台设置页面.
批量创建速率限制： 您每小时最多可以创建 2,000 个批量任务。如果需要提交更多请求，请增加每个批量任务中的请求数量。

目前 Batch API 的输出 token 没有限制。由于 Batch API 的速率限制是一个全新的独立池， 使用 Batch API 不会消耗你标准按模型计算的速率限制中的 token, 从而为你提供了一种便捷的方式，以便在查询我们的 API 时增加可用的请求数和处理 token 数。

Batch 过期

未能及时完成的 Batch 最终会进入 expired 状态；该 Batch 中未完成的请求将被取消，已完成请求的所有响应将通过该 Batch 的输出文件提供。已完成的请求所消耗的 token 将向你收费。

过期的请求将被写入你的错误文件中，并附带如下所示的消息。你可以使用 custom_id 以检索已过期请求的请求数据。

{"id": "batch_req_123", "custom_id": "request-3", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_123", "custom_id": "request-7", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

概览

入门

1. 准备您的批处理文件

Moderations 输入示例

2. 上传您的批处理输入文件

3. 创建批次

4. 检查批次状态

5. 获取结果

6. 取消批次

7. 获取所有批处理的列表

模型可用性

速率限制

Batch 过期