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

# 使用聊天完成 API 進行推論
<a name="inference-chat-completions-mantle"></a>

OpenAI 聊天完成 API 會使用 Amazon Bedrock 模型產生對話回應。您可以在 `bedrock-mantle`和 `bedrock-runtime`端點上使用聊天完成 API。我們建議您盡可能使用`bedrock-mantle`端點。如需完整的 API 詳細資訊，請參閱[OpenAI聊天完成文件](https://developers.openai.com/api/reference/chat-completions/overview)。


| **端點** | **基本 URL** | **身分驗證** | 
| --- | --- | --- | 
| bedrock-mantle (建議) | https://bedrock-mantle.{region}.api.aws/v1/chat/completions | Amazon Bedrock API 金鑰或 AWS 登入資料 | 
| bedrock-runtime | https://bedrock-runtime.{region}.amazonaws.com/v1/chat/completions | AWS 登入資料 (SigV4) 或 Amazon Bedrock API 金鑰 | 

每個端點都有自己的每個模型字符配額。如需套用至每個端點流量之配額的詳細資訊，請參閱 [bedrock-mantle 端點的配額](quotas-mantle.md)和 [bedrock-runtime 端點的配額](quotas-runtime.md)。

## 使用 bedrock-mantle 端點完成聊天
<a name="inference-chat-completions-mantle-endpoint"></a>

`bedrock-mantle` 端點支援 Amazon Bedrock API 金鑰身分驗證和 OpenAI SDK。

### 列出可用的模型
<a name="inference-chat-completions-mantle-list-models"></a>

若要列出`bedrock-mantle`端點上可用的模型，請選擇您偏好方法的索引標籤，然後遵循下列步驟：

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

```
# List all available models using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

models = client.models.list()

for model in models.data:
    print(model.id)
```

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

```
# List all available models
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X GET $OPENAI_BASE_URL/models \
   -H "Authorization: Bearer $OPENAI_API_KEY"
```

------

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

選擇您偏好方法的索引標籤，然後遵循下列步驟：

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

使用環境變數設定OpenAI用戶端：

```
# Create a chat completion using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

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

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

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

向 提出 POST 請求`/v1/chat/completions`：

```
# Create a chat completion
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
}'
```

------

**串流**  
若要逐步接收回應，請選擇您偏好方法的標籤，然後遵循下列步驟：

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

```
# Stream chat completion responses incrementally using the OpenAI SDK
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

from openai import OpenAI

client = OpenAI()

stream = client.chat.completions.create(
    model="openai.gpt-oss-120b",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")
```

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

向 提出 POST 請求`/v1/chat/completions`，並將 `stream`設定為 `true`：

```
# Stream chat completion responses incrementally
# Requires OPENAI_API_KEY and OPENAI_BASE_URL environment variables

curl -X POST $OPENAI_BASE_URL/chat/completions \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $OPENAI_API_KEY" \
   -d '{
    "model": "openai.gpt-oss-120b",
    "messages": [
        {"role": "user", "content": "Tell me a story"}
    ],
    "stream": true
}'
```

------

## 使用底ock-runtime 端點完成聊天
<a name="inference-chat-completions-runtime-endpoint"></a>

`bedrock-runtime` 端點支援 AWS SigV4 身分驗證和 Amazon Bedrock API 金鑰身分驗證。

### 列出可用的模型
<a name="inference-chat-completions-runtime-list-models"></a>

若要列出`bedrock-runtime`端點上可用的模型，請選擇您偏好方法的索引標籤，然後遵循下列步驟：

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

```
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://bedrock-runtime.us-east-1.amazonaws.com/v1",
    api_key=os.environ.get("AWS_BEARER_TOKEN_BEDROCK")
)

models = client.models.list()
for model in models.data:
    print(model.id)
```

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

```
curl -X GET "https://bedrock-runtime.us-east-1.amazonaws.com/v1/models" \
  -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK"
```

------

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

選擇您偏好方法的索引標籤，然後遵循下列步驟：

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

設定OpenAI用戶端以指向`bedrock-runtime`端點：

```
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://bedrock-runtime.us-east-1.amazonaws.com/v1",
    api_key=os.environ.get("AWS_BEARER_TOKEN_BEDROCK")
)

response = client.chat.completions.create(
    model="us.anthropic.claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)
```

------
#### [ HTTP request (API key) ]

```
curl -X POST "https://bedrock-runtime.us-east-1.amazonaws.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AWS_BEARER_TOKEN_BEDROCK" \
  -d '{
    "model": "us.anthropic.claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

------
#### [ HTTP request (SigV4) ]

```
curl -X POST "https://bedrock-runtime.us-east-1.amazonaws.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  --aws-sigv4 "aws:amz:us-east-1:bedrock" \
  --user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  -d '{
    "model": "us.anthropic.claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

------

如需端點支援之模型、區域和進階功能的詳細資訊`bedrock-runtime`，請參閱 [聊天完成 API （舊版參考）](inference-chat-completions.md)。

## 在聊天完成時包含防護機制
<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);
```

------