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

# 使用 OpenAI 聊天完成 API 調用模型
<a name="inference-chat-completions"></a>

您可以使用 [OpenAI 建立聊天完成 API](https://platform.openai.com/docs/api-reference/chat/create) 搭配 Amazon Bedrock 模型來執行模型推論。

您可以透過下列方式呼叫建立聊天完成 API：
+ 使用 Amazon Bedrock 執行時期端點提出 HTTP 請求。
+ 搭配 Amazon Bedrock 執行時期端點使用 OpenAI SDK 請求。

選取主題以進一步了解：

**Topics**
+ [OpenAI 聊天完成 API 支援的模型和區域](#inference-chat-completions-supported)
+ [使用聊天完成 API 的必要條件](#inference-chat-completions-prereq)
+ [建立聊天完成](#inference-chat-completions-create)
+ [在聊天完成時包含防護機制](#inference-chat-completions-guardrails)

## OpenAI 聊天完成 API 支援的模型和區域
<a name="inference-chat-completions-supported"></a>

您可以使用建立聊天完成 API 搭配 Amazon Bedrock 和支援這些OpenAI模型的 AWS 區域中支援的所有模型。如需支援模型和區域的詳細資訊，請參閱 [Amazon Bedrock 中支援的基礎模型](models-supported.md)。

## 使用聊天完成 API 的必要條件
<a name="inference-chat-completions-prereq"></a>

若要查看使用聊天完成 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，您可能只需要在設定用戶端時指定區域碼，而不是整個端點。
+ **安裝 OpenAI SDK** – 如需詳細資訊，請參閱 OpenAI 文件中的[程式庫](https://platform.openai.com/docs/libraries)。

------
#### [ 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，您可能只需要在設定用戶端時指定區域碼，而不是整個端點。

------

## 建立聊天完成
<a name="inference-chat-completions-create"></a>

如需建立聊天完成 API 的詳細資訊，請在 OpenAI 文件中參閱下列資源：
+ [請求內文參數](https://platform.openai.com/docs/api-reference/chat/create)
+ [回應內文參數](https://platform.openai.com/docs/api-reference/chat/object)

**注意**  
Amazon Bedrock 目前不支援其他 OpenAI 聊天完成 API 操作。

若要了解如何使用 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. 搭配用戶端使用 `chat.completions.create()` 方法，並在請求內文中最少指定 `model` 和 `messages`。

下列範例會呼叫 `us-west-2` 中的建立聊天完成 API。使用實際 API 金鑰取代 *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*。

```
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
)

completion = client.chat.completions.create(
    model="openai.gpt-oss-20b-1:0",
    messages=[
        {
            "role": "developer",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
)

print(completion.choices[0].message)
```

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

若要使用直接 HTTP 請求建立聊天完成，請執行下列操作：

1. 將 Amazon Bedrock 執行時期端點字首設定為 `/openai/v1/chat/completions` 來指定 URL，格式如下：

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

1. 在 `Authorization`標頭中指定您的 AWS 登入資料或 Amazon Bedrock API 金鑰。

1. 在請求內文中，在請求內文中至少指定 `model` 和 `messages`。

下列範例使用 curl 呼叫 `us-west-2` 中的建立聊天完成 API。使用實際 API 金鑰取代 *\$1AWS\$1BEARER\$1TOKEN\$1BEDROCK*：

```
curl -X POST https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
   -d '{
    "model": "openai.gpt-oss-20b-1:0",
    "messages": [
        {
            "role": "developer",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
}'
```

------

## 在聊天完成時包含防護機制
<a name="inference-chat-completions-guardrails"></a>

若要在模型輸入和回應中包含保護措施，請在執行模型調用時套用[防護機制](guardrails.md)，方法是在請求內文中包含下列[額外參數](https://github.com/openai/openai-python#undocumented-request-params)做為欄位：
+ `extra_headers` – 對應至包含下列欄位的物件，其會在請求中指定額外的標頭：
  + `X-Amzn-Bedrock-GuardrailIdentifier` (必要) – 防護機制的 ID。
  + `X-Amzn-Bedrock-GuardrailVersion` (必要) – 防護機制的版本。
  + `X-Amzn-Bedrock-Trace` (選用) – 是否啟用防護機制追蹤。
+ `extra_body` – 對應至物件。在該物件中，您可以包含 `amazon-bedrock-guardrailConfig` 欄位，該欄位會對應到包含下列欄位的物件：
  + `tagSuffix` (選用) – 包含此欄位以進行[輸入標記](guardrails-tagging.md)。

如需 Amazon Bedrock 防護機制中這些參數的詳細資訊，請參閱 [測試您的防護機制](guardrails-test.md)。

若要查看在 OpenAI 聊天完成時使用防護機制的範例，請選擇您偏好方法的索引標籤，然後遵循以下步驟：

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

```
import openai
from openai import OpenAIError

# Endpoint for Amazon Bedrock Runtime
bedrock_endpoint = "https://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"

# Model ID
model_id = "openai.gpt-oss-20b-1:0"

# Replace with actual values
bedrock_api_key = "$AWS_BEARER_TOKEN_BEDROCK"
guardrail_id = "GR12345"
guardrail_version = "DRAFT"

client = openai.OpenAI(
    api_key=bedrock_api_key,
    base_url=bedrock_endpoint,
)

try:
    response = client.chat.completions.create(
        model=model_id,
        # Specify guardrail information in the header
        extra_headers={
            "X-Amzn-Bedrock-GuardrailIdentifier": guardrail_id,
            "X-Amzn-Bedrock-GuardrailVersion": guardrail_version,
            "X-Amzn-Bedrock-Trace": "ENABLED",
        },
        # Additional guardrail information can be specified in the body
        extra_body={
            "amazon-bedrock-guardrailConfig": {
                "tagSuffix": "xyz"  # Used for input tagging
            }
        },
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "assistant", 
                "content": "Hello! How can I help you today?"
            },
            {
                "role": "user",
                "content": "What is the weather like today?"
            }
        ]
    )

    request_id = response._request_id
    print(f"Request ID: {request_id}")
    print(response)
    
except OpenAIError as e:
    print(f"An error occurred: {e}")
    if hasattr(e, 'response') and e.response is not None:
        request_id = e.response.headers.get("x-request-id")
        print(f"Request ID: {request_id}")
```

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

```
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.http.HttpResponseFor;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

// Endpoint for Amazon Bedrock Runtime
String bedrockEndpoint = "http://bedrock-runtime.us-west-2.amazonaws.com/openai/v1"

// Model ID
String modelId = "openai.gpt-oss-20b-1:0"

// Replace with actual values
String bedrockApiKey = "$AWS_BEARER_TOKEN_BEDROCK"
String guardrailId = "GR12345"
String guardrailVersion = "DRAFT"

OpenAIClient client = OpenAIOkHttpClient.builder()
        .apiKey(bedrockApiKey)
        .baseUrl(bedrockEndpoint)
        .build()

ChatCompletionCreateParams request = ChatCompletionCreateParams.builder()
        .addUserMessage("What is the temperature in Seattle?")
        .model(modelId)
        // Specify additional headers for the guardrail
        .putAdditionalHeader("X-Amzn-Bedrock-GuardrailIdentifier", guardrailId)
        .putAdditionalHeader("X-Amzn-Bedrock-GuardrailVersion", guardrailVersion)
        // Specify additional body parameters for the guardrail
        .putAdditionalBodyProperty(
                "amazon-bedrock-guardrailConfig",
                JsonValue.from(Map.of("tagSuffix", JsonValue.of("xyz"))) // Allows input tagging
        )
        .build();
        
HttpResponseFor<ChatCompletion> rawChatCompletionResponse =
        client.chat().completions().withRawResponse().create(request);

final ChatCompletion chatCompletion = rawChatCompletionResponse.parse();

System.out.println(chatCompletion);
```

------