本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 OpenAI 批次 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 請求。
+ 搭配 Amazon Bedrock 執行時期端點使用 OpenAI SDK 請求。

選取主題以進一步了解：

**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>

您可以使用OpenAI建立批次 API 搭配 Amazon Bedrock 和支援這些OpenAI模型的 AWS 區域中支援的所有模型。如需支援模型和區域的詳細資訊，請參閱 [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](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)如果您使用 AWS SDK，您可能只需要在設定用戶端時指定區域碼，而不是整個端點。
+ **模型存取** – 請求存取支援此功能的 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](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt)如果您使用 AWS SDK，您可能只需要在設定用戶端時指定區域碼，而不是整個端點。
+ **模型存取** – 請求存取支援此功能的 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 特定欄位和值：

**請求標頭**
+ X-Amzn-Bedrock-RoleArn (必要) – 批次推論服務角色的 Amazon Resource Name (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 為 {{batch\_abc123}} 的批次任務上呼叫 `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
)

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 為 {{batch\_abc123}} 的批次任務上呼叫 `us-west-2` 中的 OpenAI 擷取批次任務 API。

```
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 為 {{batch\_abc123}} 的批次任務上呼叫 `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
)

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 為 {{batch\_abc123}} 的批次任務上呼叫 `us-west-2` 中的 OpenAI 取消批次任務 API。

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

------