OpenAI CTO

批量 API

了解如何使用 OpenAI 的批处理 API 以异步方式发送请求组，该方式具有 50% 的较低成本、单独的显着更高的速率限制池以及明确的 24 小时周转时间。该服务非常适合处理不需要即时响应的作业。您还可以在此处直接探索 API 参考。

概述

虽然 OpenAI 平台的一些使用要求您发送同步请求，但对于许多情况，请求不需要即时响应或速率限制会阻止您快速执行大量查询。批处理作业通常适用于以下用例：

  • 运行评估
  • 对大型数据集进行分类
  • 嵌入内容存储库

与直接使用标准端点相比，批处理 API 具有以下优势：

  • **更好的成本效率：**与同步 API 相比节省 50% 的成本
  • **更高的速率限制：**与同步 API 相比，更高的上限
  • **快速完成时间：**每个批处理在 24 小时内完成（通常更快）

入门

1.准备批处理文件

批处理以 .jsonl 文件开始，其中每行包含对 API 的单个请求的详细信息。目前，可用的端点是 /v1/chat/completions (聊天完成 API) 和 /v1/embeddings (嵌入 API)。对于给定的输入文件，body 字段中的参数与基础端点的参数相同。每个请求都必须包含唯一的 custom_id 值，您可以使用此值在完成后引用结果。以下是包含 2 个请求的示例输入文件。请注意，每个输入文件只能包含对单个模型的请求。

{
  "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
  }
}

2.上传批处理输入文件

与我们的微调 API一样，您必须首先上传输入文件，以便在启动批处理时正确引用该文件。使用文件 API上传 .jsonl 文件。

from openai import OpenAI

client = OpenAI()

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

3.创建批处理

上传输入文件后，您可以使用输入文件对象的 ID 创建批处理。在本例中，假设文件 ID 为 file-abc123。对于现在，完成窗口只能设置为 24h。您还可以通过可选的 metadata 参数提供自定义元数据。

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"
  }
)

此请求将返回一个批处理对象，其中包含有关您的批处理的信息：

{
  "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.检查批处理状态

您可以随时检查批处理的状态，这也会返回批处理对象。

from openai import OpenAI

client = OpenAI()

client.batches.retrieve("batch_abc123")

批处理对象的状态可以是以下任何状态：

  • validating：正在验证输入文件，然后批处理才能开始
  • failed：输入文件未通过验证过程
  • in_progress：输入文件已成功验证，批处理正在运行
  • finalizing：批处理已完成，正在准备结果
  • completed：批处理已完成，结果已准备就绪
  • expired：批处理无法在 24 小时时间窗口内完成
  • cancelling：已启动批处理取消
  • cancelled：批处理已取消

5.获取结果

一旦批处理完成，您可以通过文件 API下载输出，方法是对批处理的 output_file_id 字段进行请求，并将结果写入您机器上的文件，在本例中为 batch_output.jsonl

from openai import OpenAI

client = OpenAI()

content = client.files.content("file-xyz123")

输出 .jsonl 文件将包含对输入文件中每个成功请求的单个响应行。批处理中任何失败的请求都会将其错误信息写入可以通过批处理的 error_file_id 找到的错误文件。

注意：输出行顺序可能不匹配输入行顺序。不要依赖顺序来处理结果，而是使用自定义 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
  }
}

6.取消批处理

如果需要，您可以取消正在进行的批处理。批处理的状态将更改为 cancelling，直到正在进行的请求完成，之后状态将更改为 cancelled。

from openai import OpenAI

client = OpenAI()

client.batches.cancel("batch_abc123")

7.获取所有批处理列表

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

from openai import OpenAI

client = OpenAI()

client.batches.list(limit=10)

模型可用性

批处理 API 目前可用于执行对以下模型的查询。批处理 API 支持与这些模型相同的格式的文本和视觉输入：

  • gpt-4o
  • gpt-4-turbo
  • gpt-4
  • gpt-4-32k
  • gpt-3.5-turbo
  • gpt-3.5-turbo-16k
  • gpt-4-turbo-preview
  • gpt-4-vision-preview
  • gpt-4-turbo-2024-04-09
  • gpt-4-0314
  • gpt-4-32k-0314
  • gpt-4-32k-0613
  • gpt-3.5-turbo-0301
  • gpt-3.5-turbo-16k-0613
  • gpt-3.5-turbo-1106
  • gpt-3.5-turbo-0613
  • text-embedding-3-large
  • text-embedding-3-small
  • text-embedding-ada-002

批处理 API 还支持经过微调的模型。

速率限制

批处理 API 的速率限制与现有每个模型的速率限制分开。批处理 API 有两种新的速率限制类型：

  • **每个批处理的限制：**单个批处理最多可以包含 50,000 个请求，批处理输入文件的大小可以达到 100 MB。请注意，/v1/embeddings 批处理还限制为每个批处理最多 50,000 个嵌入输入。
  • **每个模型排队的提示令牌：**每个模型都有批处理处理允许的最大排队提示令牌数。您可以在平台设置页面上找到这些限制。

目前，批处理 API 没有输出令牌或已提交请求数量的限制。因为批处理 API 的速率限制是一个新的单独的池，所以使用批处理 API 不会消耗标准每个模型速率限制中的令牌，从而为您提供了增加可用于查询 API 的请求和处理令牌数量的便捷方法。

批处理过期

未及时完成的批处理最终会进入 expired 状态；未完成的请求将在批处理中取消，并且将提供对已完成请求的响应，作为批处理的输出文件的一部分。您将为已完成的请求消耗的令牌付费。

其他资源

有关更具体的示例，请访问OpenAI 食谱（The OpenAI Cookbook），其中包含分类、情绪分析和摘要生成等用例的示例代码。

Was this page helpful?