通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

开始使用 Azure OpenAI 批处理部署

Azure OpenAI Batch API 设计用于高效处理大规模和大容量处理任务。 处理具有单独配额的异步请求组，目标周转时间为 24 小时，成本比全局标准低 50%。 使用批处理，你可以在单个文件中发送大量请求，而不是一次发送一个请求。 全局批处理请求具有单独的入队令牌配额，避免对你的在线工作负载造成任何中断。

关键用例包括：

  • 大规模数据处理：并行快速分析广泛的数据集。

  • 内容生成：创建大量文本，例如产品说明或文章。

  • 文档审查和总结：自动执行对长篇文档的审查和总结。

  • 客户支持自动化：同时处理大量查询，以提高响应速度。

  • 数据提取和分析：从大量非结构化数据中提取和分析信息。

  • 自然语言处理 (NLP) 任务：对大型数据集执行情绪分析或翻译等任务。

  • 营销和个性化：大规模生成个性化内容和建议。

提示

如果你的批处理作业太大，导致即使在用尽部署配额后仍然达到排队令牌限制，那么某些地区现在支持一种新的功能，该功能允许你以指数退避的方式，对多个批处理作业进行排队。

在排队令牌配额可用后，可以自动创建并启动下一个批处理作业。 若要了解详细信息，请参阅 使用指数退避自动重试大型批处理作业。

重要

我们的目标是在 24 小时内处理批处理请求;我们不会使需要更长时间的作业过期。 可以随时 取消 任务。 取消作业时，任何剩余的工作将被取消，已完成的工作会保留。 你将需要为任何已完成的工作付费。

静态存储的数据仍保留在指定的 Azure 地理位置中，而数据可能会被处理，以便在任何 Azure OpenAI 位置进行推理。 详细了解数据存储位置。 

批处理支持

全局批处理模型可用性

地区 o3， 2025-04-16 o4-mini， 2025-04-16 gpt-4.1， 2025-04-14 gpt-4.1-nano， 2025-04-14 gpt-4.1-mini， 2025-04-14 o3-mini， 2025-01-31 gpt-4o，2024-05-13 gpt-4o，2024-08-06 gpt-4o，2024-11-20 gpt-4o-mini，2024-07-18
australiaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
brazilsouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
canadaeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
eastus2 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
francecentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
德国西中部 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
日本东部 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
koreacentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
northcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
norwayeast ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
polandcentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southafricanorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
southcentralus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
南印度 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
spaincentral ✅ ✅ ✅ ✅ ✅ - - - - -
Swedencentral ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
switzerlandnorth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
uksouth ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
欧洲西部 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅
westus3 ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

需要注册才能访问 o3-mini。 有关详细信息，请参阅我们的 推理模型指南。

以下模型支持全局批处理：

模型 版本 输入格式
o3-mini 2025年1月31日 文本
gpt-4o 2024-08-06 文本 + 图像
gpt-4o-mini 2024年07月18日 文本 + 图像
gpt-4o 2024年5月13日 文本 + 图像

API 支持

API 版本
最新 GA API 版本： 2024-10-21
最新支持的预览版 API 版本： 2025-04-01-preview

注意

虽然 Global Batch 支持较旧的 API 版本，但某些模型需要更新的预览 API 版本。 例如，o3-mini 与 2024-10-21 不兼容，因为它是在此日期之后发布的。 若要使用全局批处理访问较新的模型，请使用最新的预览 API 版本。

功能支持

当前不支持以下项：

  • 与 Assistants API 集成。
  • 与“基于自有数据的 Azure OpenAI”功能集成

批量部署

注意

在 Azure AI Foundry 门户中 ，批处理部署类型将显示为 Global-Batch 和 Data Zone Batch。 若要详细了解 Azure OpenAI 部署类型，请参阅我们的 部署类型指南。

显示 Azure AI Foundry 门户中的模型部署对话框的屏幕截图，其中突出显示了 Global-Batch 部署类型。

提示

建议为所有全局批处理模型部署启用 动态配额 ，以帮助避免由于排队令牌配额不足而导致的作业失败。 使用动态配额后，部署可在有额外容量时适时利用更多配额。 动态配额设为关闭时，部署能够处理的请求数最多达到在创建部署时定义的排队令牌上限。

先决条件

准备批处理文件

与 微调一样，全局批处理使用 JSON 行 （.jsonl） 格式的文件。 下面是一些包含不同类型的受支持内容的示例文件：

输入格式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id 是必需的，用于识别哪个单独的批处理请求对应于给定的响应。 响应将不会按照 .jsonl 批处理文件中定义的顺序返回。

应将 model 属性设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。

重要

model 属性必须设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。 批处理文件的每一行上都必须存在相同的全局批处理模型部署名称。如果要以其他部署为目标，则必须在单独的批处理文件/作业中执行此操作。

为了获得最佳性能，建议提交大型文件进行批处理，而不是提交大量每个文件中只有几行内容小型文件。

创建输入文件

在本文中，我们将创建一个名为 test.jsonl 的文件，并将上面的标准输入代码块中的内容复制到该文件。 你需要修改该文件并将你的全局批处理部署名称添加到该文件的每一行。

上传批处理文件

准备好输入文件后，首先需要上传该文件，然后才能启动批处理作业。 可以通过编程方式或通过 Azure AI Foundry 门户完成文件上传。 此示例演示如何将文件直接上传到 Azure OpenAI 资源。 或者，可以为 Azure OpenAI Batch 配置 Azure Blob 存储。

  1. 登录到 Azure AI Foundry 门户。

  2. 选择其中有全局批处理模型部署可用的 Azure OpenAI 资源。

  3. 选择“Batch 作业”“+创建批处理作业”。>

    显示 Azure AI Foundry 门户中的批处理作业创建体验的屏幕截图。

  4. 从“批处理数据”“上传文件”下的下拉列表中 > 选择“上传文件”，并提供在上一步骤中创建的 文件的路径 > 单击“下一步”。test.jsonl>

    显示上传文件体验的屏幕截图。

创建批处理作业

选择“创建”以启动你的批处理作业。

创建批处理作业 Azure AI Foundry 门户体验的屏幕截图。

跟踪批处理作业进度

创建作业后，可以通过选择最近创建的作业的作业 ID 来监视作业的进度。 默认情况下，系统会将你带到最近创建的批处理作业的状态页。

显示了当前正在进行验证的作业的批处理作业 ID 的屏幕截图。

可以在右侧窗格中跟踪作业的作业状态：

显示 Azure AI Foundry 门户中的批处理作业状态体验的屏幕截图。

检索批处理作业输出文件

一旦作业完成或达到最终状态，它会生成一个错误文件和一个输出文件。您可以通过选择带有向下箭头图标的相应按钮下载这些文件进行审查。

显示可用于下载的批处理作业输出和错误文件的屏幕截图。

取消批处理

取消正在进行的批处理。 批处理将处于 cancelling 状态最长达 10 分钟，然后变为 cancelled 状态，在这种状态下，输出文件中将有部分结果可用（如果有）。

显示 Azure AI Foundry 门户中的批处理作业取消按钮的屏幕截图。

先决条件

本文中的步骤旨在按顺序在 Jupyter Notebook 中运行。 因此，我们将只在示例开头将 Azure OpenAI 客户端实例化一次。 如果你想无序运行某个步骤，你通常需要将 Azure OpenAI 客户端设置为该调用的一部分。

即使已安装 OpenAI Python 库，也可能需要将你的安装升级到最新版本：

!pip install openai --upgrade

准备批处理文件

与 微调一样，全局批处理使用 JSON 行 （.jsonl） 格式的文件。 下面是一些包含不同类型的受支持内容的示例文件：

输入格式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id 是必需的，用于识别哪个单独的批处理请求对应于给定的响应。 响应将不会按照 .jsonl 批处理文件中定义的顺序返回。

应将 model 属性设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。

重要

model 属性必须设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。 批处理文件的每一行上都必须存在相同的全局批处理模型部署名称。如果要以其他部署为目标，则必须在单独的批处理文件/作业中执行此操作。

为了获得最佳性能，建议提交大型文件进行批处理，而不是提交大量每个文件中只有几行内容小型文件。

创建输入文件

在本文中，我们将创建一个名为 test.jsonl 的文件，并将上面的标准输入代码块中的内容复制到该文件。 你需要修改该文件并将你的全局批处理部署名称添加到该文件的每一行。 将此文件保存到你在其中执行 Jupyter Notebook 的同一目录中。

上传批处理文件

准备好输入文件后，首先需要上传该文件，然后才能启动批处理作业。 可以通过编程方式或通过 Azure AI Foundry 门户完成文件上传。 此示例演示如何将文件直接上传到 Azure OpenAI 资源。 或者，可以为 Azure OpenAI Batch 配置 Azure Blob 存储。

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
  azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
  azure_ad_token_provider=token_provider,
  api_version="2025-04-01-preview"
)

# Upload a file with a purpose of "batch"
file = client.files.create(
  file=open("test.jsonl", "rb"), 
  purpose="batch",
  extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)


print(file.model_dump_json(indent=2))

print(f"File expiration: {datetime.fromtimestamp(file.expires_at) if file.expires_at is not None else 'Not set'}")

file_id = file.id

通过取消注释和添加 extra_body={"expires_after":{"seconds": 1209600, "anchor": "created_at"}} ，可将上传文件设置为在 14 天内过期。 如果未设置过期，则每个资源的最大批文件数限制为 500 个。 通过设置过期值，每个资源的批处理文件数将增加到每个资源 10,000 个文件。

输出：

{
  "id": "file-655111ec9cfc44489d9af078f08116ef",
  "bytes": 176064,
  "created_at": 1743391067,
  "filename": "test.jsonl",
  "object": "file",
  "purpose": "batch",
  "status": "processed",
  "expires_at": 1744600667,
  "status_details": null
}
File expiration: 2025-04-13 23:17:47

创建批处理作业

成功上传文件后，可以提交文件进行批处理。

# Submit a batch job with the file
batch_response = client.batches.create(
    input_file_id=file_id,
    endpoint="/chat/completions",
    completion_window="24h",
    extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} # Optional you can set to a number between 1209600-2592000. This is equivalent to 14-30 days
)


# Save batch ID for later use
batch_id = batch_response.id

print(batch_response.model_dump_json(indent=2))

每个资源的默认 500 个最大文件限制也适用于输出文件。 可以在此处取消注释此行以添加 extra_body={"output_expires_after":{"seconds": 1209600, "anchor": "created_at"}} ，以便输出文件在 14 天内过期。 通过设置过期值，每个资源的批处理文件数将增加到每个资源 10,000 个文件。

注意

当前，完成窗口必须设置为 24h。 如果设置为 24h 以外的任何其他值，作业将失败。 超过 24 小时的作业将继续执行，直到取消。

输出：

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-655111ec9cfc44489d9af078f08116ef",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": null,
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": null,
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

如果你的批处理作业太大，导致即使在用尽部署配额后仍然达到排队令牌限制，那么某些地区现在支持一种新的快速失败功能，该功能允许你以指数退避的方式，对多个批处理作业进行排队。因此一旦一个大型批处理作业完成，就可以自动启动下一个批处理作业。 若要详细了解哪些区域支持此功能以及如何调整代码以利用此功能，请参阅 排队批处理作业。

跟踪批处理作业进度

成功创建批处理作业后，可以在 Studio 中或以编程方式监视其进度。 检查批处理作业进度时，建议在每个状态调用之间等待至少 60 秒。

import time
import datetime 

status = "validating"
while status not in ("completed", "failed", "canceled"):
    time.sleep(60)
    batch_response = client.batches.retrieve(batch_id)
    status = batch_response.status
    print(f"{datetime.datetime.now()} Batch Id: {batch_id},  Status: {status}")

if batch_response.status == "failed":
    for error in batch_response.errors.data:  
        print(f"Error code {error.code} Message {error.message}")

输出：

2024-07-31 21:48:32.556488 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: validating
2024-07-31 21:49:39.221560 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:50:53.383138 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:52:07.274570 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: in_progress
2024-07-31 21:53:21.149501 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:54:34.572508 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:55:35.304713 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:56:36.531816 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: finalizing
2024-07-31 21:57:37.414105 Batch Id: batch_6caaf24d-54a5-46be-b1b7-518884fcbdde,  Status: completed

以下状态值是可能的：

地位 描述
validating 在批处理开始之前，正在验证输入文件。
failed 输入文件未能通过验证过程。
in_progress 输入文件已成功验证，批处理当前正在运行。
finalizing 批处理已完成，结果正在被准备中。
completed 批处理已完成，结果已准备就绪。
expired 批处理没能在 24 小时时间窗口内完成。
cancelling 批处理正在进行cancelled（这可能需要等待长达 10 分钟才能生效）。
cancelled 批处理已被 cancelled。

若要检查作业状态详细信息，可以运行：

print(batch_response.model_dump_json(indent=2))

输出：

{
  "id": "batch_6caaf24d-54a5-46be-b1b7-518884fcbdde",
  "completion_window": "24h",
  "created_at": 1722476583,
  "endpoint": null,
  "input_file_id": "file-9f3a81d899b4442f98b640e4bc3535dd",
  "object": "batch",
  "status": "completed",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": 1722477429,
  "error_file_id": "file-c795ae52-3ba7-417d-86ec-07eebca57d0b",
  "errors": null,
  "expired_at": null,
  "expires_at": 1722562983,
  "failed_at": null,
  "finalizing_at": 1722477177,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "file-3304e310-3b39-4e34-9f1c-e1c1504b2b2a",
  "request_counts": {
    "completed": 3,
    "failed": 0,
    "total": 3
  }
}

请注意，那里同时存在 error_file_id 和一个单独的 output_file_id。 使用 error_file_id 来帮助调试批处理作业发生的任何问题。

检索批处理作业输出文件

import json

output_file_id = batch_response.output_file_id

if not output_file_id:
    output_file_id = batch_response.error_file_id

if output_file_id:
    file_response = client.files.content(output_file_id)
    raw_responses = file_response.text.strip().split('\n')  

    for raw_response in raw_responses:  
        json_response = json.loads(raw_response)  
        formatted_json = json.dumps(json_response, indent=2)  
        print(formatted_json)

输出：

为简洁起见，我们将仅包括输出中的单个聊天完成响应。 如果你遵循本文中的步骤，你应该有三个类似于以下内容的响应：

{
  "custom_id": "task-0",
  "response": {
    "body": {
      "choices": [
        {
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          },
          "finish_reason": "stop",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": "Microsoft was founded on April 4, 1975, by Bill Gates and Paul Allen in Albuquerque, New Mexico.",
            "role": "assistant"
          }
        }
      ],
      "created": 1722477079,
      "id": "chatcmpl-9rFGJ9dh08Tw9WRKqaEHwrkqRa4DJ",
      "model": "gpt-4o-2024-05-13",
      "object": "chat.completion",
      "prompt_filter_results": [
        {
          "prompt_index": 0,
          "content_filter_results": {
            "hate": {
              "filtered": false,
              "severity": "safe"
            },
            "jailbreak": {
              "filtered": false,
              "detected": false
            },
            "self_harm": {
              "filtered": false,
              "severity": "safe"
            },
            "sexual": {
              "filtered": false,
              "severity": "safe"
            },
            "violence": {
              "filtered": false,
              "severity": "safe"
            }
          }
        }
      ],
      "system_fingerprint": "fp_a9bfe9d51d",
      "usage": {
        "completion_tokens": 24,
        "prompt_tokens": 27,
        "total_tokens": 51
      }
    },
    "request_id": "660b7424-b648-4b67-addc-862ba067d442",
    "status_code": 200
  },
  "error": null
}

其他批处理命令

取消批处理

取消正在进行的批处理。 批处理将处于 cancelling 状态最长达 10 分钟，然后变为 cancelled 状态，在这种状态下，输出文件中将有部分结果可用（如果有）。

client.batches.cancel("batch_abc123") # set to your batch_id for the job you want to cancel

列出批处理

列出特定 Azure OpenAI 资源的批处理作业。

client.batches.list()

Python 库中的列表方法会分页。

要列出所有作业，请执行以下操作：

all_jobs = []
# Automatically fetches more pages as needed.
for job in client.batches.list(
    limit=20,
):
    # Do something with job here
    all_jobs.append(job)
print(all_jobs)

列出批处理（预览版）

使用 REST API 列出具有其他排序/筛选选项的所有批处理作业。

在下面的示例中，我们提供了 generate_time_filter 函数来简化筛选器的构造。 如果不想使用此函数，该筛选器字符串的格式将如下所示：created_at gt 1728860560 and status eq 'Completed'。

import requests
import json
from datetime import datetime, timedelta
from azure.identity import DefaultAzureCredential

token_credential = DefaultAzureCredential()
token = token_credential.get_token('https://cognitiveservices.azure.com/.default')

endpoint = "https://{YOUR_RESOURCE_NAME}.openai.azure.com/"
api_version = "2025-03-01-preview"
url = f"{endpoint}openai/batches"
order = "created_at asc"
time_filter =  lambda: generate_time_filter("past 8 hours")

# Additional filter examples:
#time_filter =  lambda: generate_time_filter("past 1 day")
#time_filter =  lambda: generate_time_filter("past 3 days", status="Completed")

def generate_time_filter(time_range, status=None):
    now = datetime.now()
    
    if 'day' in time_range:
        days = int(time_range.split()[1])
        start_time = now - timedelta(days=days)
    elif 'hour' in time_range:
        hours = int(time_range.split()[1])
        start_time = now - timedelta(hours=hours)
    else:
        raise ValueError("Invalid time range format. Use 'past X day(s)' or 'past X hour(s)'")
    
    start_timestamp = int(start_time.timestamp())
    
    filter_string = f"created_at gt {start_timestamp}"
    
    if status:
        filter_string += f" and status eq '{status}'"
    
    return filter_string

filter = time_filter()

headers = {'Authorization': 'Bearer ' + token.token}

params = {
    "api-version": api_version,
    "$filter": filter,
    "$orderby": order
}

response = requests.get(url, headers=headers, params=params)

json_data = response.json()

if response.status_code == 200:
    print(json.dumps(json_data, indent=2))
else:
    print(f"Request failed with status code: {response.status_code}")
    print(response.text)

输出：

{
  "data": [
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729011896,
      "completion_window": "24h",
      "created_at": 1729011128,
      "error_file_id": "file-472c0626-4561-4327-9e4e-f41afbfb30e6",
      "expired_at": null,
      "expires_at": 1729097528,
      "failed_at": null,
      "finalizing_at": 1729011805,
      "id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
      "in_progress_at": 1729011493,
      "input_file_id": "file-f89384af0082485da43cb26b49dc25ce",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-62bebde8-e767-4cd3-a0a1-28b214dc8974",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    },
    {
      "cancelled_at": null,
      "cancelling_at": null,
      "completed_at": 1729016366,
      "completion_window": "24h",
      "created_at": 1729015829,
      "error_file_id": "file-85ae1971-9957-4511-9eb4-4cc9f708b904",
      "expired_at": null,
      "expires_at": 1729102229,
      "failed_at": null,
      "finalizing_at": 1729016272,
      "id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43",
      "in_progress_at": 1729016126,
      "input_file_id": "file-686746fcb6bc47f495250191ffa8a28e",
      "errors": null,
      "metadata": null,
      "object": "batch",
      "output_file_id": "file-04399828-ae0b-4825-9b49-8976778918cb",
      "request_counts": {
        "total": 3,
        "completed": 2,
        "failed": 1
      },
      "status": "completed",
      "endpoint": "/chat/completions"
    }
  ],
  "first_id": "batch_4ddc7b60-19a9-419b-8b93-b9a3274b33b5",
  "has_more": false,
  "last_id": "batch_6287485f-50fc-4efa-bcc5-b86690037f43"
}

对批处理作业进行排队

如果你的批处理作业太大，导致即使在用尽部署配额后仍然达到排队令牌限制，那么某些地区现在支持一种新的“快速失败”功能，该功能允许你以指数退避的方式，对多个批处理作业进行排队。 一个大型批处理作业完成后，排队令牌配额再次可用，可以自动创建和启动下一个批处理作业。

旧行为：

  1. 已运行并使用所有可用于部署的令牌的大型批处理作业。
  2. 提交的新批处理作业。
  3. 新的批处理作业进入验证阶段，最长可能需要几分钟时间。
  4. 根据当前可用的配额检查新作业的令牌计数。
  5. 新批处理作业失败，错误报告为超出令牌限制。

新行为：

  1. 已运行并使用所有可用于部署的令牌的大型批处理作业
  2. 提交的新批处理作业
  3. 与当前可用的批处理配额作业相比，新作业的大致令牌计数会快速失败，因此你可以更轻松地以编程方式处理重试。

区域支持

以下区域支持新的快速失败行为：

  • australiaeast
  • eastus
  • 德国西中部
  • italynorth
  • northcentralus
  • polandcentral
  • Swedencentral
  • switzerlandnorth
  • eastus2
  • westus

下面的代码演示了处理快速失败行为的基本机制，以使用指数退避策略自动重试和对批处理作业进行排队。

根据批处理作业的大小，可能需要进一步增加 max_retries 或更改此示例。

import time
from openai import BadRequestError

max_retries = 10
retries = 0
initial_delay = 5
delay = initial_delay

while True:
    try:
        batch_response = client.batches.create(
            input_file_id=file_id,
            endpoint="/chat/completions",
            completion_window="24h",
        )
        
        # Save batch ID for later use
        batch_id = batch_response.id
        
        print(f"✅ Batch created successfully after {retries} retries")
        print(batch_response.model_dump_json(indent=2))
        break  
        
    except BadRequestError as e:
        error_message = str(e)
        
        # Check if it's a token limit error
        if 'token_limit_exceeded' in error_message:
            retries += 1
            if retries >= max_retries:
                print(f"❌ Maximum retries ({max_retries}) reached. Giving up.")
                raise
            
            print(f"⏳ Token limit exceeded. Waiting {delay} seconds before retry {retries}/{max_retries}...")
            time.sleep(delay)
            
            # Exponential backoff - increase delay for next attempt
            delay *= 2
        else:
            # If it's a different error, raise it immediately
            print(f"❌ Encountered non-token limit error: {error_message}")
            raise

输出：

⏳ Token limit exceeded. Waiting 5 seconds before retry 1/10...
⏳ Token limit exceeded. Waiting 10 seconds before retry 2/10...
⏳ Token limit exceeded. Waiting 20 seconds before retry 3/10...
⏳ Token limit exceeded. Waiting 40 seconds before retry 4/10...
⏳ Token limit exceeded. Waiting 80 seconds before retry 5/10...
⏳ Token limit exceeded. Waiting 160 seconds before retry 6/10...
⏳ Token limit exceeded. Waiting 320 seconds before retry 7/10...
✅ Batch created successfully after 7 retries
{
  "id": "batch_1e1e7b9f-d4b4-41fa-bd2e-8d2ec50fb8cc",
  "completion_window": "24h",
  "created_at": 1744402048,
  "endpoint": "/chat/completions",
  "input_file_id": "file-e2ba4ccaa4a348e0976c6fe3c018ea92",
  "object": "batch",
  "status": "validating",
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "error_file_id": "",
  "errors": null,
  "expired_at": null,
  "expires_at": 1744488444,
  "failed_at": null,
  "finalizing_at": null,
  "in_progress_at": null,
  "metadata": null,
  "output_file_id": "",
  "request_counts": {
    "completed": 0,
    "failed": 0,
    "total": 0
  }
}

先决条件

准备批处理文件

与 微调一样，全局批处理使用 JSON 行 （.jsonl） 格式的文件。 下面是一些包含不同类型的受支持内容的示例文件：

输入格式

{"custom_id": "task-0", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was Microsoft founded?"}]}}
{"custom_id": "task-1", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "When was the first XBOX released?"}]}}
{"custom_id": "task-2", "method": "POST", "url": "/chat/completions", "body": {"model": "REPLACE-WITH-MODEL-DEPLOYMENT-NAME", "messages": [{"role": "system", "content": "You are an AI assistant that helps people find information."}, {"role": "user", "content": "What is Altair Basic?"}]}}

custom_id 是必需的，用于识别哪个单独的批处理请求对应于给定的响应。 响应将不会按照 .jsonl 批处理文件中定义的顺序返回。

应将 model 属性设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。

重要

model 属性必须设置为与你希望用作推理响应目标的全局批处理部署的名称相匹配。 批处理文件的每一行上都必须存在相同的全局批处理模型部署名称。如果要以其他部署为目标，则必须在单独的批处理文件/作业中执行此操作。

为了获得最佳性能，建议提交大型文件进行批处理，而不是提交大量每个文件中只有几行内容小型文件。

创建输入文件

在本文中，我们将创建一个名为 test.jsonl 的文件，并将上面的标准输入代码块中的内容复制到该文件。 你需要修改该文件并将你的全局批处理部署名称添加到该文件的每一行。

上传批处理文件

准备好输入文件后，首先需要上传该文件，然后才能启动批处理作业。 可以通过编程方式或通过 Azure AI Foundry 门户完成文件上传。 此示例演示如何将文件直接上传到 Azure OpenAI 资源。 或者，可以为 Azure OpenAI Batch 配置 Azure Blob 存储。

重要

请谨慎使用 API 密钥。 请不要直接在代码中包含 API 密钥，并且切勿公开发布该密钥。 如果使用 API 密钥，请将其安全地存储在 Azure Key Vault 中。 有关在应用中安全地使用 API 密钥的详细信息，请参阅 使用 Azure Key Vault 的 API 密钥。

有关 AI 服务安全性的详细信息，请参阅 对 Azure AI 服务的请求进行身份验证。

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files?api-version=2025-03-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -F "purpose=batch" \
  -F "file=@C:\\batch\\test.jsonl;type=application/json" \
  -F "expires_after.seconds=1209600" \
  -F "expires_after.anchor=created_at"

上面的代码为你的 test.jsonl 文件假设了一个特定的文件路径。 请根据需要针对你的本地系统调整此文件路径。

通过添加可选的 "expires_after.seconds=1209600" 和 "expires_after.anchor=created_at" 参数，您将使上传的文件在 14 天后过期。 如果未设置过期，则每个资源的最大批文件数限制为 500 个。 通过设置过期值，每个资源的批处理文件数将增加到每个资源 10,000 个文件。 可以设置为介于 1209600-2592000 之间的数字。 这相当于 14-30 天。

输出：

{
  "status": "processed",
  "bytes": 817,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1743398147,
  "object": "file"
}

跟踪文件上传状态

可能需要一些时间才能完全完成上传和处理，具体取决于上传文件的大小。 若要检查文件上传状态，请运行：

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{file-id}?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

输出：

{
  "status": "processed",
  "bytes": 686,
  "purpose": "batch",
  "filename": "test.jsonl",
  "expires_at": 1744607747,
  "id": "file-7733bc35e32841e297a62a9ee50b3461",
  "created_at": 1721408291,
  "object": "file"
}

创建批处理作业

成功上传文件后，可以提交文件进行批处理。

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/chat/completions",
    "completion_window": "24h",
    "output_expires_after": {
        "seconds": 1209600
    },
    "anchor": "created_at"
  }'

每个资源的默认 500 个最大文件限制也适用于输出文件。 可在此处选择添加 "output_expires_after":{"seconds": 1209600}, 和 "anchor": "created_at"，以便使输出文件在 14 天内过期。 通过设置过期值，每个资源的批处理文件数将增加到每个资源 10,000 个文件。

注意

当前，完成窗口必须设置为 24h。 如果设置为 24h 以外的任何其他值，作业将失败。 超过 24 小时的作业将继续执行，直到取消。

输出：

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:13:57.2491382+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:13:57.1918498+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_fe3f047a-de39-4068-9008-346795bfc1db",
  "in_progress_at": null,
  "input_file_id": "file-21006e70789246658b86a1fc205899a4",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

跟踪批处理作业进度

成功创建批处理作业后，可以在 Studio 中或以编程方式监视其进度。 检查批处理作业进度时，建议在每个状态调用之间等待至少 60 秒。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

输出：

{
  "cancelled_at": null,
  "cancelling_at": null,
  "completed_at": null,
  "completion_window": "24h",
  "created_at": "2024-07-19T17:33:29.1619286+00:00",
  "error_file_id": null,
  "expired_at": null,
  "expires_at": "2024-07-20T17:33:29.1578141+00:00",
  "failed_at": null,
  "finalizing_at": null,
  "id": "batch_e0a7ee28-82c4-46a2-a3a0-c13b3c4e390b",
  "in_progress_at": null,
  "input_file_id": "file-c55ec4e859d54738a313d767718a2ac5",
  "errors": null,
  "metadata": null,
  "object": "batch",
  "output_file_id": null,
  "request_counts": {
    "total": null,
    "completed": null,
    "failed": null
  },
  "status": "Validating"
}

以下状态值是可能的：

地位 描述
validating 在批处理开始之前，正在验证输入文件。
failed 输入文件未能通过验证过程。
in_progress 输入文件已成功验证，批处理当前正在运行。
finalizing 批处理已完成，结果正在被准备中。
completed 批处理已完成，结果已准备就绪。
expired 批处理没能在 24 小时时间窗口内完成。
cancelling 批处理正被 cancelled（可能需要长达 10 分钟才能生效。）
cancelled 批处理已被 cancelled。

检索批处理作业输出文件

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/files/{output_file_id}/content?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" > batch_output.jsonl

其他批处理命令

取消批处理

取消正在进行的批处理。 批处理将处于 cancelling 状态最长达 10 分钟，然后变为 cancelled 状态，在这种状态下，输出文件中将有部分结果可用（如果有）。

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches/{batch_id}/cancel?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

列出批处理

列出给定 Azure OpenAI 资源的现有批处理作业。

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/batches?api-version=2025-03-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY"

列表 API 调用会分页。 响应包含一个布尔值 has_more，用于指示何时有更多结果需要循环访问。

列出批处理（预览版）

使用 REST API 列出具有其他排序/筛选选项的所有批处理作业。

curl "YOUR_RESOURCE_NAME.openai.azure.com/batches?api-version=2025-03-01-preview&$filter=created_at%20gt%201728773533%20and%20created_at%20lt%201729032733%20and%20status%20eq%20'Completed'&$orderby=created_at%20asc" \
  -H "api-key: $AZURE_OPENAI_API_KEY"

为了避免出现错误，可将 URL rejected: Malformed input to a URL function 空间替换为 %20。

Batch 限制

限制名称 限制值
每个资源的最大文件数 500
最大输入文件大小 200 MB
每个文件的最大请求数 100,000

批处理配额

该表展示了批处理配额限制。 全局批处理的配额值以入队令牌表示。 提交用于批处理的文件时，会计算文件中存在的令牌数。 在批处理作业达到终端状态之前，这些令牌将计入总入队令牌限制。

全局批处理

模型 企业协议 默认 信用卡支付的月度订阅 MSDN 订阅 面向学生的 Azure 免费试用版
gpt-4o 5 B 200米 50米 90 K 无
gpt-4o-mini 15 B 1 B 50米 90 K 无
gpt-4-turbo 300米 80米 40 M 90 K 无
gpt-4 150 M 30 M 5百万 100 K 无
gpt-35-turbo 10 B 1 B 100 M 2百万 5万
o3-mini 15 B 1 B 50米 90 K 无

B = 十亿 | M = 百万 | K = 千

数据区域批处理

模型 企业协议 默认 信用卡支付的月度订阅 MSDN 订阅 面向学生的 Azure 免费试用版
gpt-4o 500米 30 M 30 M 90 K 无
gpt-4o-mini 1.5 B 100 M 50米 90 K 无
o3-mini 1.5 B 100 M 50米 90 K 无

批处理对象

属性 类型 定义
id 字符串
object 字符串 batch
endpoint 字符串 批处理使用的 API 终结点
errors 对象
input_file_id 字符串 批处理的输入文件的 ID
completion_window 字符串 应在其中处理批处理的时间范围
status 字符串 批处理的当前状态。 可能的值：validating、failed、in_progress、finalizing、completed、expired、cancelling、cancelled。
output_file_id 字符串 包含成功执行的请求的输出的文件的 ID。
error_file_id 字符串 包含出错的请求的输出的文件的 ID。
created_at 整数 创建此批处理时的时间戳（以 Unix 纪元为单位）。
in_progress_at 整数 此批处理启动处理时的时间戳（采用 unix 纪元）。
expires_at 整数 此批处理的到期时间戳（采用 unix 纪元）。
finalizing_at 整数 此批处理启动最终完成时的时间戳（采用 unix 纪元）。
completed_at 整数 此批处理启动最终完成时的时间戳（采用 unix 纪元）。
failed_at 整数 此批处理失败时的时间戳（采用 unix 纪元）。
expired_at 整数 此批处理的过期时间戳（采用 unix 纪元）。
cancelling_at 整数 此批处理启动 cancelling 时的时间戳（采用 unix 纪元）。
cancelled_at 整数 此批处理被 cancelled 时的时间戳（采用 unix 纪元）。
request_counts 对象 对象结构：

total整数
批处理中的请求总数。
completed整数
批处理中已成功完成的请求数。
failed整数
批处理中已失败的请求数。
metadata 地图 可以附加到批处理的一组键值对。 此属性可用于以结构化格式存储有关批处理的其他信息。

常见问题 (FAQ)

图像是否可以与批处理 API 一起使用？

此功能仅限于某些多模式模型。 目前只有 GPT-4o 支持将图像作为批处理请求的一部分。 可以通过 图像 URL 或图像的 base64 编码表示形式提供图像作为输入。 GPT-4 Turbo 目前不支持对图像进行批处理。

是否可以将批处理 API 与优化的模型配合使用？

目前不支持。

是否可以将批处理 API 用于嵌入模型？

目前不支持。

内容筛选是否适用于全局批处理部署？

是的。 与其他部署类型类似，你可以创建内容筛选器并将其与全局批处理部署类型相关联。

我可以请求额外的配额吗？

是的，可以通过 Azure AI Foundry 门户中的配额页进行操作。 可以在 配额和限制文章中找到默认配额分配。

如果 API 未在 24 小时内完成我的请求，会发生什么情况？

我们的目标是在 24 小时内处理这些请求；我们不会让需要更长时间的作业过期。 你可以随时取消任务。 取消作业时，任何剩余的工作将被取消，已完成的工作会保留。 你将需要为任何已完成的工作付费。

我可以使用批处理对多少个请求进行排队？

你可以批处理的请求数量没有固定限制，不过，这将取决于你的入队令牌配额。 你的入队令牌配额包括一次可以排队的最大输入令牌数。

你的批处理请求完成后，批处理速率限制将重置，因为输入令牌已被清除。 该限制取决于队列中的全局请求数。 如果批处理 API 队列快速处理你的批处理，则批处理速率限制会更快地重置。

故障排除

当 status 为 Completed 时，作业成功。 成功的作业仍会生成一个“error_file_id”，但它将与一个包含零字节的空文件相关联。

发生作业失败时，可在 errors 属性中找到有关失败的详细信息：

"value": [
        {
          "id": "batch_80f5ad38-e05b-49bf-b2d6-a799db8466da",
          "completion_window": "24h",
          "created_at": 1725419394,
          "endpoint": "/chat/completions",
          "input_file_id": "file-c2d9a7881c8a466285e6f76f6321a681",
          "object": "batch",
          "status": "failed",
          "cancelled_at": null,
          "cancelling_at": null,
          "completed_at": 1725419955,
          "error_file_id": "file-3b0f9beb-11ce-4796-bc31-d54e675f28fb",
          "errors": {
                "object": “list”,
                "data": [
                {
               "code": "empty_file",
               "message": "The input file is empty. Please ensure that the batch contains at least one   request."
                    }
                ]
          },
          "expired_at": null,
          "expires_at": 1725505794,
          "failed_at": null,
          "finalizing_at": 1725419710,
          "in_progress_at": 1725419572,
          "metadata": null,
          "output_file_id": "file-ef12af98-dbbc-4d27-8309-2df57feed572",

            "request_counts": {
                "total": 10,
                "completed": null,
                "failed": null
            },
        }

错误代码

错误代码 定义
invalid_json_line 输入文件中的一行（或多行）无法解析为有效的 json。

请确保没有拼写错误，左括号和右括号正确，引号遵循了 JSON 标准，然后重新提交请求。
too_many_tasks 输入文件中的请求数超出了允许的最大值 100,000。

请确保您的请求总数不超过 100,000，并重新提交任务。
url_mismatch 输入文件中某一行的 URL 与其余行不匹配，或者输入文件中指定的 URL 与预期的终结点 URL 不匹配。

请确保所有请求 URL 都相同，并且它们与 Azure OpenAI 部署的关联终结点 URL 匹配。
model_not_found 找不到在输入文件的 model 属性中指定的 Azure OpenAI 模型部署名称。

请确保此名称指向有效的 Azure OpenAI 模型部署。
duplicate_custom_id 此请求的自定义 ID 与另一个请求中的自定义 ID 重复。
empty_batch 请检查输入文件，确保自定义 ID 参数对于批处理中的每个请求都是唯一的。
model_mismatch 输入文件中此请求的 model 属性中指定的 Azure OpenAI 模型部署名称与该文件的其余部分不匹配。

请确保批处理中的所有请求都指向请求的 model 属性中的同一“Azure AI Foundry 中的 Azure OpenAI 模型”模型部署。
invalid_request 输入行的架构无效或部署 SKU 无效。

请确保输入文件中请求的属性与预期的输入属性匹配，并且 Azure OpenAI 部署 SKU 在批处理 API 请求中为 globalbatch。

已知问题

  • 使用 Azure CLI 部署的资源不能直接用于 Azure OpenAI 全局批处理。 这是因为使用此方法部署的资源具有不遵循 https://your-resource-name.openai.azure.com 模式的终结点子域。 解决此问题的方法是使用其他常见部署方法之一部署新的 Azure OpenAI 资源，该方法在部署过程中将会正确处理子域设置。

  • 不支持 UTF-8-BOM 编码 jsonl 文件。 JSON 行文件应使用 UTF-8 进行编码。 JSON RFC 规范未正式支持使用字节顺序标记 (BOM) 编码文件，Azure OpenAI 目前将 BOM 编码的文件视为无效。 UTF-8-BOM 编码文件当前将返回通用错误消息：“验证失败：无法从输入文件中提取有效的模型部署名称。 请确保输入文件中的每一行都具有“模型”字段中指定的有效部署名称，并且部署名称在所有行中都是一致的。

另请参阅