OpenAI CTO

批处理

创建大量的 API 请求批次，用于异步处理。批处理 API 在 24 小时内返回完成结果，并享受 50% 的折扣。

相关指南：批处理

创建批处理

从请求文件创建并执行批处理。

端点：

POST https://api.openai.com/v1/batches

请求正文：

参数类型必需描述
input_file_idstring必需包含新批处理请求的上传文件的 ID。有关如何上传文件的信息，请参见上传文件。您的输入文件必须格式化为 JSONL 文件，并且必须使用目的 batch 上传。该文件最多可包含 50,000 个请求，并且可以达到 100 MB 的大小。
endpointstring必需批处理中所有请求都将使用的端点。目前支持 /v1/chat/completions、/v1/embeddings 和 /v1/completions。请注意，/v1/embeddings 批处理还限制为所有批处理请求中的 50,000 个嵌入输入的最大值。
completion_windowstring必需应在其中处理批处理的时间框架。目前仅支持 24h。
metadataobject or null可选批处理的可选自定义元数据。

返回：

已创建的批处理对象。

示例请求：

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

响应：

{
  "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": 1711471533,
  "in_progress_at": null,
  "expires_at": null,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

检索批处理

检索批处理。

端点：

GET (https://api.openai.com/v1/batches/{batch_id})

路径参数：

参数类型必需描述
batch_idstring必需要检索的批处理的 ID。

返回：

与指定 ID 匹配的批处理对象。

示例请求：

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

响应：

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

取消批处理

取消正在进行的批处理。

端点：

POST https://api.openai.com/v1/batches/{batch\_id}/cancel

路径参数：

参数类型必需描述
batch_idstring必需要取消的批处理的 ID。

返回：

与指定 ID 匹配的批处理对象。

示例请求：

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

响应：

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "cancelling",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": null,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": 1711475133,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 23,
    "failed": 1
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job",
  }
}

列表批次

GET https://api.openai.com/v1/batches

列出您组织的批次。

查询参数

名称类型描述
after
Optional

string

用于分页的游标。after 是一个对象 ID，它定义了您在列表中的位置。例如，如果您发出一个列表请求并收到 100 个对象，以 obj_foo 结束，则您的后续调用可以包含 after=obj_foo 以便检索列表的下一页。
limit
Optional
Defaults to 20

integer

要返回的对象数量的限制。限制可以在 1 到 100 之间，默认为 20。

返回

一些分页的 Batch 对象的列表。

示例请求

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

响应

{
  "object": "list",
  "data": [
    {
      "id": "batch_abc123",
      "object": "batch",
      "endpoint": "/v1/chat/completions",
      "errors": null,
      "input_file_id": "file-abc123",
      "completion_window": "24h",
      "status": "completed",
      "output_file_id": "file-cvaTdG",
      "error_file_id": "file-HOWS94",
      "created_at": 1711471533,
      "in_progress_at": 1711471538,
      "expires_at": 1711557933,
      "finalizing_at": 1711493133,
      "completed_at": 1711493163,
      "failed_at": null,
      "expired_at": null,
      "cancelling_at": null,
      "cancelled_at": null,
      "request_counts": {
        "total": 100,
        "completed": 95,
        "failed": 5
      },
      "metadata": {
        "customer_id": "user_123456789",
        "batch_description": "Nightly job"
      }
    },
    { ... },
  ],
  "first_id": "batch_abc123",
  "last_id": "batch_abc456",
  "has_more": true
}

批处理对象

属性类型描述
idstring批处理的唯一标识符。
objectstring对象类型，始终为batch。
endpointstring批处理使用的OpenAI API端点。
errorsobject处理批处理期间发生的任何错误的字典。
input_file_idstring批处理的输入文件的ID。
completion_windowstring应在其中处理批处理的时间框架。
statusstring批处理的当前状态。
output_file_idstring成功执行的请求的输出的文件的ID。
error_file_idstring具有错误的请求的输出的文件的ID。
created_atinteger批处理创建时的Unix时间戳（以秒为单位）。
in_progress_atinteger批处理开始处理时的Unix时间戳（以秒为单位）。
expires_atinteger批处理到期时的Unix时间戳（以秒为单位）。
finalizing_atinteger批处理开始最终化时的Unix时间戳（以秒为单位）。
completed_atinteger批处理完成时的Unix时间戳（以秒为单位）。
failed_atinteger批处理失败时的Unix时间戳（以秒为单位）。
expired_atinteger批处理到期时的Unix时间戳（以秒为单位）。
cancelling_atinteger批处理开始取消时的Unix时间戳（以秒为单位）。
cancelled_atinteger批处理取消时的Unix时间戳（以秒为单位）。
request_countsobject批处理内不同状态的请求计数。
metadatamap可附加到对象的16对键值对。这对以结构化格式存储有关对象的附加信息非常有用。键最多可以是64个字符长，值最多可以是512个字符长。

批处理对象的示例：

{
  "id": "batch_abc123",
  "object": "batch",
  "endpoint": "/v1/completions",
  "errors": null,
  "input_file_id": "file-abc123",
  "completion_window": "24h",
  "status": "completed",
  "output_file_id": "file-cvaTdG",
  "error_file_id": "file-HOWS94",
  "created_at": 1711471533,
  "in_progress_at": 1711471538,
  "expires_at": 1711557933,
  "finalizing_at": 1711493133,
  "completed_at": 1711493163,
  "failed_at": null,
  "expired_at": null,
  "cancelling_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 100,
    "completed": 95,
    "failed": 5
  },
  "metadata": {
    "customer_id": "user_123456789",
    "batch_description": "Nightly eval job"
  }
}

请求输入对象

批处理输入文件的每行对象

  • custom_id (string)：开发者提供的每个请求的id，将用于将输出与输入匹配。批次中的每个请求都必须是唯一的。
  • method (string)：用于请求的HTTP方法。当前仅支持POST。
  • url (string)：用于请求的OpenAI API相对URL。当前支持/v1/chat/completions，/v1/embeddings和/v1/completions。

请求输入对象

{
  "custom_id": "request-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "gpt-3.5-turbo",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is 2+2?"
      }
    ]
  }
}

请求输出对象

批处理输出和错误文件的每行对象

属性类型描述
idstring
custom_idstring开发者提供的每个请求的id，用于将输出与输入进行匹配。
responseobject or null显示属性
errorobject or null对于因非HTTP错误而失败的请求，这将包含有关失败原因的更多信息。 显示属性

response 属性

属性类型描述
status_codenumber
request_idstring
bodyobject

error 属性

属性类型描述
messagestring
typestring
paramstring
codestring

示例

{
  "id": "batch_req_wnaDys",
  "custom_id": "request-2",
  "response": {
    "status_code": 200,
    "request_id": "req_c187b3",
    "body": {
      "id": "chatcmpl-9758Iw",
      "object": "chat.completion",
      "created": 1711475054,
      "model": "gpt-3.5-turbo",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "2 + 2 equals 4."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 24,
        "completion_tokens": 15,
        "total_tokens": 39
      },
      "system_fingerprint": null
    }
  },
  "error": null
}

Was this page helpful?