本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用以下命令提交一批提示 OpenAI Batch API
<a name="inference-openai-batch"></a>

您可以将 [OpenAI 创建批处理 API](https://platform.openai.com/docs/api-reference/batch) 与 Amazon Bedrock OpenAI 模型结合使用，来运行批量推理作业。

您可通过以下方式调用 OpenAI 创建批处理 API：
+ 通过 Amazon Bedrock 运行时端点发出 HTTP 请求。
+ 将 OpenAI SDK 请求和 Amazon Bedrock 运行时端点配合使用。

选择一个主题以了解更多信息：

**Topics**
+ [支持的型号和区域 OpenAI 批处理 API](#inference-openai-batch-supported)
+ [使用的前提条件 OpenAI 批处理 API](#inference-openai-batch-prereq)
+ [创建一个 OpenAI 批处理作业](#inference-openai-batch-create)
+ [检索 OpenAI 批处理作业](#inference-openai-batch-retrieve)
+ [列表 OpenAI 批处理作业](#inference-openai-batch-list)
+ [取消 OpenAI 批处理作业](#inference-openai-batch-cancel)

## 支持的型号和区域 OpenAI 批处理 API
<a name="inference-openai-batch-supported"></a>

您可以对 Amazon Bedrock 和支持这些OpenAI模型的 AWS 地区支持的所有型号使用OpenAI创建批处理 API。有关支持的模型和区域的更多信息，请参阅 [Amazon Bedrock 中支持的根基模型](models-supported.md)。

## 使用的前提条件 OpenAI 批处理 API
<a name="inference-openai-batch-prereq"></a>

要查看使用 OpenAI 批处理 API 操作的先决条件，请选择与您的首选方法对应的选项卡，然后按照以下步骤操作：

------
#### [ OpenAI SDK ]
+ **身份验证** – OpenAI SDK 仅支持使用 Amazon Bedrock API 密钥进行身份验证。生成 Amazon Bedrock API 密钥以对您的请求进行身份验证。要了解有关 Amazon Bedrock API 密钥以及如何生成密钥的信息，请参阅 “构建” 一章中的 API 密钥部分。
+ **终端节点** — 找到与要在 [Amazon Bedrock 运行时终端节点和配额中使用的 AWS 区域相对应的终端节点](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)。如果您使用 S AWS DK，则在设置客户端时可能只需要指定区域代码，而无需指定整个终端节点。
+ **模型访问权限** – 请求访问支持此功能的 Amazon Bedrock 模型。有关更多信息，请参阅[使用 SDK 和 CLI 管理模型访问权限](model-access.md#model-access-modify)。
+ **安装 OpenAI SDK** – 有关更多信息，请参阅 OpenAI 文档中的[库](https://platform.openai.com/docs/libraries)。
+ **上传到 S3 的批处理 JSONL 文件** – 按照 OpenAI 文档中[准备批处理文件](https://platform.openai.com/docs/guides/batch#1-prepare-your-batch-file)中的步骤，采用恰当的格式准备批处理文件。然后，将其上传到 Amazon S3 存储桶。
+ **IAM 权限** – 确保您拥有具适当权限的以下 IAM 身份：
  + 通过身份验证的 IAM 身份，该身份可以执行与批量推理相关的 API 操作。有关更多信息，请参阅[IAM 身份提交和管理批量推理作业所需的权限](batch-inference-permissions.md)。
  + 您使用的批量推理服务角色可以代入您的身份，调用您使用的 OpenAI 模型，以及访问 S3 中的批处理 JSONL 文件。有关更多信息，请参阅 [服务角色](security-iam-sr.md)。

------
#### [ HTTP request ]
+ **身份验证** — 您可以使用您的 AWS 证书或 Amazon Bedrock API 密钥进行身份验证。

  设置您的 AWS 凭证或生成 Amazon Bedrock API 密钥来验证您的请求。
  + 要了解如何设置 AWS 证书，请参阅使用[AWS 安全凭证进行编程访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds-programmatic-access.html)。
  + 要了解有关 Amazon Bedrock API 密钥以及如何生成密钥的信息，请参阅 “构建” 一章中的 API 密钥部分。
+ **终端节点** — 找到与要在 [Amazon Bedrock 运行时终端节点和配额中使用的 AWS 区域相对应的终端节点](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)。如果您使用 S AWS DK，则在设置客户端时可能只需要指定区域代码，而无需指定整个终端节点。
+ **模型访问权限** – 请求访问支持此功能的 Amazon Bedrock 模型。有关更多信息，请参阅[使用 SDK 和 CLI 管理模型访问权限](model-access.md#model-access-modify)。
+ **上传到 S3 的批处理 JSONL 文件** – 按照 OpenAI 文档中[准备批处理文件](https://platform.openai.com/docs/guides/batch#1-prepare-your-batch-file)中的步骤，采用恰当的格式准备批处理文件。然后，将其上传到 Amazon S3 存储桶。
+ **IAM 权限** – 确保您拥有具适当权限的以下 IAM 身份：
  + 通过身份验证的 IAM 身份，该身份可以执行与批量推理相关的 API 操作。有关更多信息，请参阅[IAM 身份提交和管理批量推理作业所需的权限](batch-inference-permissions.md)。
  + 您使用的批量推理服务角色可以代入您的身份，调用您使用的 OpenAI 模型，以及访问 S3 中的批处理 JSONL 文件。有关更多信息，请参阅 [服务角色](security-iam-sr.md)。

------

## 创建一个 OpenAI 批处理作业
<a name="inference-openai-batch-create"></a>

有关 OpenAI 创建批处理 API 的详细信息，请参阅 OpenAI 文档中的以下资源：
+ [创建批处理](https://platform.openai.com/docs/api-reference/batch/create) – 详细说明请求和响应。
+ [请求输出对象](https://platform.openai.com/docs/api-reference/batch/request-output) – 详细说明批处理作业所生成的输出的字段。如需解释 S3 存储桶中的结果，请参阅此文档。

**构造请求**  
在形成批量推理请求时，请注意以下 Amazon Bedrock-specific 字段和值：

**请求标头**
+ X-Amzn-Bedrock-RoleArn （必填）— 批量推理服务角色的 Amazon 资源名称 (ARN)。有关更多信息，请参阅 [为批量推理创建自定义服务角色](batch-iam-sr.md)。
+ X-Amzn-Bedrock-ModelId （必填）-用于推理的基础模型的 ID。有关更多信息，请参阅 [Amazon Bedrock 中支持的根基模型](models-supported.md)。
+ X-Amzn-Bedrock-OutputEncryptionKeyId （可选）— 要用于加密输出 S3 文件的 KMS 密钥的 ID。有关更多信息，请参阅[使用 AWS KMS (SSE-KMS) 指定服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/specifying-kms-encryption.html)。
+ X-Amzn-Bedrock-Tags （可选）— 键和值的字典，用于指示要附加到输出的标签。有关更多信息，请参阅 [标记 Amazon Bedrock 资源](tagging.md)。

**请求正文参数：**
+ 端点 – 必须是 `v1/chat/completions`。
+ input\_file\_id – 指定批处理 JSONL 文件的 S3 URI。

**查找生成的结果**  
创建的响应中包含批处理 ID。批量推理作业的结果和错误日志记录将写入包含输入文件的 S3 文件夹。结果位于与批处理 ID 同名的文件夹中，如以下文件夹结构所示：

```
---- {batch_input_folder}
        |---- {batch_input}.jsonl
        |---- {batch_id}
	           |---- {batch_input}.jsonl.out
	           |---- {batch_input}.jsonl.err
```

要查看结合不同方法使用 OpenAI 创建批处理 API 的示例，请选择与您的首选方法对应的选项卡，然后按照以下步骤操作：

------
#### [ OpenAI SDK (Python) ]

要使用 OpenAI SDK 创建批处理作业，请执行以下操作：

1. 导入 OpenAI SDK 并使用以下字段设置客户端：
   + `base_url` – 将 Amazon Bedrock 运行时端点添加为 `/openai/v1` 的前缀，格式如下：

     ```
     https://{{${bedrock-runtime-endpoint}}}/openai/v1
     ```
   + `api_key` – 指定 Amazon Bedrock API 密钥。
   + `default_headers` – 如果需要包含任何标头，可将其作为键值对包含在此对象中。也可在进行特定 API 调用时在 `extra_headers` 中指定标头。

1. 在客户端上使用 [batches.create()](https://platform.openai.com/docs/api-reference/batch/create) 方法。

在运行以下示例之前，请先替换以下字段中的占位符：
+ api\_key — 替换{{$AWS\_BEARER\_TOKEN\_BEDROCK}}为实际的 API 密钥。
+ X-Amzn-BedrockRoleArn — {{arn:aws:iam::123456789012:role/BatchServiceRole}} 替换为您设置的实际批量推理服务角色。
+ input\_file\_id — {{s3://amzn-s3-demo-bucket/openai-input.jsonl}} 替换为你将批处理 JSONL 文件上传到的实际 S3 URI。

以下示例在 `us-west-2` 中调用 OpenAI 创建批处理作业 API，并包含一段元数据。

```
from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1", 
    api_key="$AWS_BEARER_TOKEN_BEDROCK", # Replace with actual API key
    default_headers={
        "X-Amzn-Bedrock-RoleArn": "arn:aws:iam::123456789012:role/BatchServiceRole" # Replace with actual service role ARN
    }
)

job = client.batches.create(
    input_file_id="s3://amzn-s3-demo-bucket/openai-input.jsonl", # Replace with actual S3 URI
    endpoint="/v1/chat/completions",
    completion_window="24h",
    metadata={
        "description": "test input"
    },
    extra_headers={
        "X-Amzn-Bedrock-ModelId": "openai.gpt-oss-20b-1:0",
    }
)
print(job)
```

------
#### [ HTTP request ]

要通过直接 HTTP 请求创建聊天补全作业，请执行以下操作：

1. 使用 POST 方法，并通过将 Amazon Bedrock 运行时端点添加为 `/openai/v1/batches` 的前缀来指定 URL，格式如下：

   ```
   {{https://${bedrock-runtime-endpoint}}}/openai/v1/batches
   ```

1. 在`Authorization`标题中指定您的 AWS 证书或 Amazon Bedrock API 密钥。

在运行以下示例之前，请先替换以下字段中的占位符：
+ 授权-{{$AWS\_BEARER\_TOKEN\_BEDROCK}} 替换为实际的 API 密钥。
+ X-Amzn-BedrockRoleArn — {{arn:aws:iam::123456789012:role/BatchServiceRole}} 替换为您设置的实际批量推理服务角色。
+ input\_file\_id — {{s3://amzn-s3-demo-bucket/openai-input.jsonl}} 替换为你将批处理 JSONL 文件上传到的实际 S3 URI。

以下示例在 `us-west-2` 中调用创建聊天补全 API，并包含一段元数据：

```
curl -X POST 'https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/batches' \
    -H 'Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK' \  
    -H 'Content-Type: application/json' \
    -H 'X-Amzn-Bedrock-ModelId: openai.gpt-oss-20b-1:0' \
    -H 'X-Amzn-Bedrock-RoleArn: arn:aws:iam::123456789012:role/BatchServiceRole' \  
    -d '{    
    "input_file_id": "s3://amzn-s3-demo-bucket/openai-input.jsonl",    
    "endpoint": "/v1/chat/completions",    
    "completion_window": "24h",
    "metadata": {"description": "test input"}  
}'
```

------

## 检索 OpenAI 批处理作业
<a name="inference-openai-batch-retrieve"></a>

有关 OpenAI 检索批处理 API 请求和响应的详细信息，请参阅[检索批处理](https://platform.openai.com/docs/api-reference/batch/retrieve)。

在发出请求时，您需要指定要获取其信息的批处理作业的 ID。响应会返回有关批处理作业的信息，包括您可以在 S3 存储桶中查找的输出和错误文件名。

要查看运用不同方法使用 OpenAI 检索批处理 API 的示例，请选择与您的首选方法对应的选项卡，然后按照以下步骤操作：

------
#### [ OpenAI SDK (Python) ]

要使用 OpenAI SDK 检索批处理作业，请执行以下操作：

1. 导入 OpenAI SDK 并使用以下字段设置客户端：
   + `base_url` – 将 Amazon Bedrock 运行时端点添加为 `/openai/v1` 的前缀，格式如下：

     ```
     https://{{${bedrock-runtime-endpoint}}}/openai/v1
     ```
   + `api_key` – 指定 Amazon Bedrock API 密钥。
   + `default_headers` – 如果需要包含任何标头，可将其作为键值对包含在此对象中。也可在进行特定 API 调用时在 `extra_headers` 中指定标头。

1. 在客户端上使用 [batches.retrieve()](https://platform.openai.com/docs/api-reference/batch/create) 方法，并指定要检索其信息的批处理作业的 ID。

在运行以下示例之前，请先替换以下字段中的占位符：
+ api\_key — 替换{{$AWS\_BEARER\_TOKEN\_BEDROCK}}为实际的 API 密钥。
+ batch\_id — 替换为实际的 {{$AWS\_BEARER\_TOKEN\_BEDROCK}} API 密钥。

该示例在 ID 为的批处理作业中`us-west-2`调用OpenAI检索批处理作业 API {{batch\_abc123}}。

```
from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1", 
    api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)

job = client.batches.retrieve(batch_id="batch_abc123") # Replace with actual ID

print(job)
```

------
#### [ HTTP request ]

要通过直接 HTTP 请求检索批处理作业，请执行以下操作：

1. 使用 GET 方法，并通过将 Amazon Bedrock 运行时端点添加为 `/openai/v1/batches/{{${batch_id}}}` 的前缀来指定 URL，格式如下：

   ```
   {{https://${bedrock-runtime-endpoint}}}/openai/v1/batches/{{batch_abc123}}
   ```

1. 在`Authorization`标题中指定您的 AWS 证书或 Amazon Bedrock API 密钥。

在运行以下示例之前，请先替换以下字段中的占位符：
+ 授权-{{$AWS\_BEARER\_TOKEN\_BEDROCK}} 替换为实际的 API 密钥。
+ batch\_abc123 – 在路径中，将此值替换为批处理作业的实际 ID。

以下示例在 ID 为的批处理作业中`us-west-2`调用OpenAI检索批处理 API {{batch\_abc123}}。

```
curl -X GET 'https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/batches/batch_abc123' \
    -H 'Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK'
```

------

## 列表 OpenAI 批处理作业
<a name="inference-openai-batch-list"></a>

有关 OpenAI 列出批处理 API 请求和响应的详细信息，请参阅[列出批处理](https://platform.openai.com/docs/api-reference/batch/list)。响应会返回有关您的批处理作业的一组信息。

在发出请求时，您可以包含查询参数以筛选结果。响应会返回有关批处理作业的信息，包括您可以在 S3 存储桶中查找的输出和错误文件名。

要查看运用不同方法使用 OpenAI 列出批处理 API 的示例，请选择与您的首选方法对应的选项卡，然后按照以下步骤操作：

------
#### [ OpenAI SDK (Python) ]

要使用 OpenAI SDK 列出批处理作业，请执行以下操作：

1. 导入 OpenAI SDK 并使用以下字段设置客户端：
   + `base_url` – 将 Amazon Bedrock 运行时端点添加为 `/openai/v1` 的前缀，格式如下：

     ```
     https://{{${bedrock-runtime-endpoint}}}/openai/v1
     ```
   + `api_key` – 指定 Amazon Bedrock API 密钥。
   + `default_headers` – 如果需要包含任何标头，可将其作为键值对包含在此对象中。也可在进行特定 API 调用时在 `extra_headers` 中指定标头。

1. 在客户端上使用 [batches.list()](https://platform.openai.com/docs/api-reference/batch/list) 方法。您可以包括任何可选参数。

在运行以下示例之前，请先替换以下字段中的占位符：
+ api\_key — 替换{{$AWS\_BEARER\_TOKEN\_BEDROCK}}为实际的 API 密钥。

以下示例在 `us-west-2` 中调用 OpenAI 列出批处理作业 API，并指定返回的结果上限为 2 个。

```
from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1", 
    api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)

job = client.batches.list(limit=2)

print(job)
```

------
#### [ HTTP request ]

要通过直接 HTTP 请求列出批处理作业，请执行以下操作：

1. 使用 GET 方法，并通过将 Amazon Bedrock 运行时端点添加为 `/openai/v1/batches` 的前缀来指定 URL，格式如下：

   ```
   {{https://${bedrock-runtime-endpoint}}}/openai/v1/batches
   ```

   您可以包括任何可选的查询参数。

1. 在`Authorization`标题中指定您的 AWS 证书或 Amazon Bedrock API 密钥。

在运行以下示例之前，请先替换以下字段中的占位符：
+ 授权-{{$AWS\_BEARER\_TOKEN\_BEDROCK}} 替换为实际的 API 密钥。

以下示例在 `us-west-2` 中调用 OpenAI 列出批处理 API，并指定返回的结果上限为 2 个。

```
curl -X GET 'https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/batches?limit=2' \
    -H 'Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK' \
```

------

## 取消 OpenAI 批处理作业
<a name="inference-openai-batch-cancel"></a>

有关 OpenAI 取消批处理 API 请求和响应的详细信息，请参阅[取消批处理](https://platform.openai.com/docs/api-reference/batch/cancel)。响应会返回有关已取消的批处理作业的信息。

在发出请求时，您需要指定要取消的批处理作业的 ID。

要查看运用不同方法使用 OpenAI 取消批处理 API 的示例，请选择与您的首选方法对应的选项卡，然后按照以下步骤操作：

------
#### [ OpenAI SDK (Python) ]

要使用 OpenAI SDK 取消批处理作业，请执行以下操作：

1. 导入 OpenAI SDK 并使用以下字段设置客户端：
   + `base_url` – 将 Amazon Bedrock 运行时端点添加为 `/openai/v1` 的前缀，格式如下：

     ```
     https://{{${bedrock-runtime-endpoint}}}/openai/v1
     ```
   + `api_key` – 指定 Amazon Bedrock API 密钥。
   + `default_headers` – 如果需要包含任何标头，可将其作为键值对包含在此对象中。也可在进行特定 API 调用时在 `extra_headers` 中指定标头。

1. 在客户端上使用 [batches.cancel()](https://platform.openai.com/docs/api-reference/batch/cancel) 方法，并指定要检索其信息的批处理作业的 ID。

在运行以下示例之前，请先替换以下字段中的占位符：
+ api\_key — 替换{{$AWS\_BEARER\_TOKEN\_BEDROCK}}为实际的 API 密钥。
+ batch\_id — 替换为实际的 {{$AWS\_BEARER\_TOKEN\_BEDROCK}} API 密钥。

该示例在 ID 为的批处理作业`us-west-2`上调用 “OpenAI取消批处理作业 API” {{batch\_abc123}}。

```
from openai import OpenAI

client = OpenAI(
    base_url="https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1", 
    api_key="$AWS_BEARER_TOKEN_BEDROCK" # Replace with actual API key
)

job = client.batches.cancel(batch_id="batch_abc123") # Replace with actual ID

print(job)
```

------
#### [ HTTP request ]

要直接通过 HTTP 请求取消批处理作业，请执行以下操作：

1. 使用 POST 方法，并通过将 Amazon Bedrock 运行时端点添加为 `/openai/v1/batches/{{${batch_id}}}/cancel` 的前缀来指定 URL，格式如下：

   ```
   {{https://${bedrock-runtime-endpoint}}}/openai/v1/batches/{{batch_abc123}}/cancel
   ```

1. 在`Authorization`标题中指定您的 AWS 证书或 Amazon Bedrock API 密钥。

在运行以下示例之前，请先替换以下字段中的占位符：
+ 授权-{{$AWS\_BEARER\_TOKEN\_BEDROCK}} 替换为实际的 API 密钥。
+ batch\_abc123 – 在路径中，将此值替换为批处理作业的实际 ID。

以下示例在 ID 为的批处理作业中调用 `us-west-2` “OpenAI取消” 批处理 API {{batch\_abc123}}。

```
curl -X GET 'https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/batches/batch_abc123/cancel' \
    -H 'Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK'
```

------