本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 處理自訂聊天範本和權杖化工具
自訂聊天範本和權杖化工具是正確格式化對話輸入和管理匯入模型中權杖產生的重要元件。自訂模型匯入支援使用自訂聊天範本匯入模型，這些範本定義多迴轉對話的結構和字符化方式。
## 使用自訂聊天範本匯入模型
使用自訂聊天範本匯入模型時，請務必遵循主要自訂模型匯入文件中概述的最佳實務，包括以安全張量格式引入模型權重，並提供所有必要的組態檔案。
### 聊天範本格式需求
如果您的模型使用自訂聊天範本，且您想要將該範本與 Amazon Bedrock 搭配使用，您必須以下列其中一種格式包含聊天範本檔案：
+ **`chat_template.jinja`** — 以 Jinja2-based範本檔案，定義訊息的格式。
+ **`chat_template.json`** — 包含聊天範本做為字串值的 JSON 檔案。
+ **`tokenizer_config.json` 使用內嵌聊天範本** — 或者，您可以將聊天範本直接包含在`tokenizer_config.json`檔案中做為`chat_template`欄位。如需範例，請參閱 Hugging Face 上的 [Hermes-2-Pro Tokenizer\$1config.json](https://huggingface.co/NousResearch/Hermes-2-Pro-Llama-3-8B/blob/main/tokenizer_config.json#L2059)。
自訂模型匯入會自動處理這些檔案，並在匯入過程中將其包含在正確的目錄中。
#### 聊天範本優先順序
如果您提供多個聊天範本來源，Amazon Bedrock 會套用下列優先順序規則：
1. 以**個別聊天範本檔案為優先**：如果您在 中同時包含個別聊天範本檔案 (`chat_template.jinja` 或 `chat_template.json`) 和 `chat_template` 欄位`tokenizer_config.json`，則會使用個別檔案，並`tokenizer_config.json`忽略 中的內嵌範本。
1. **內嵌範本做為後援**：如果您未提供單獨的聊天範本檔案，`tokenizer_config.json`Amazon Bedrock 將在存在時使用來自 的 `chat_template` 欄位。
**警告**
**選擇一個方法：**為了避免混淆並確保可預測的行為，我們強烈建議僅使用下列其中一種方法：
**選項 1：**提供單獨的聊天範本檔案 (`chat_template.jinja` 或 `chat_template.json`)，而不在您的 中包含 `chat_template` 欄位`tokenizer_config.json`。
**選項 2：**直接在 中包含 `chat_template` 欄位`tokenizer_config.json`，不提供個別的範本檔案。
如果您有自訂工具範本或複雜的聊天範本組態，建議您使用選項 2 （在 中嵌入範本`tokenizer_config.json`)，因為它可讓您在單一組態檔案中定義多個具名範本 （例如「預設」和「tool\$1use」)。
**注意**
聊天範本檔案必須遵循 Hugging Face 格式和命名慣例。確保您的範本與程式Transformers庫相容。
#### 聊天範本格式範例
以下是兩種支援的聊天範本格式範例：
------
#### [ Jinja Format (chat\$1template.jinja) ]
Jinja2-based聊天範本的簡化範例：
```
{% for message in messages %}
{% if loop.first and message['role'] != 'system' %}
<|im_start|>system
You are a helpful assistant.<|im_end|>
{% endif %}
<|im_start|>{{ message['role'] }}
{{ message['content'] }}<|im_end|>
{% endfor %}
{% if add_generation_prompt %}
<|im_start|>assistant
{% endif %}
```
如需完整範例，請參閱 Hugging Face 上的[GPT-OSS聊天範本](https://huggingface.co/openai/gpt-oss-20b/blob/main/chat_template.jinja)。
------
#### [ JSON Format (chat\$1template.json) ]
具有願景支援的 JSON 型聊天範本的簡化範例：
```
{
"chat_template": "{% for message in messages %}{% if loop.first and message['role'] != 'system' %}<|im_start|>system\nYou are a helpful assistant.<|im_end|>\n{% endif %}<|im_start|>{{ message['role'] }}\n{% if message['content'] is string %}{{ message['content'] }}<|im_end|>\n{% else %}{% for content in message['content'] %}{% if content['type'] == 'image' %}<|vision_start|><|image_pad|><|vision_end|>{% elif 'text' in content %}{{ content['text'] }}{% endif %}{% endfor %}<|im_end|>\n{% endif %}{% endfor %}{% if add_generation_prompt %}<|im_start|>assistant\n{% endif %}"
}
```
如需多模式支援的完整範例，請參閱 Hugging Face 上的[Qwen2-VL聊天範本](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct/blob/main/chat_template.json)。
------
**重要**
確保您的聊天範本檔案遵循上述範例中顯示的確切命名慣例 (`chat_template.jinja` 或 `chat_template.json`) 和格式。格式不正確的範本可能會導致匯入或推論失敗。
## 使用自訂聊天範本調用模型
使用自訂聊天範本匯入模型後，您有兩個選項可以使用正確格式的對話輸入叫用模型：
### 搭配訊息使用 OpenAI ChatCompletion API
如果您以訊息結構描述格式提供輸入，您應該使用 **OpenAI ChatCompletion API**。當您將此 API 格式用於具有上傳聊天範本 (`chat_template.jinja` 或 `chat_template.json`) 的模型時，Amazon Bedrock 將使用聊天範本自動將您的輸入訊息轉換為正確的格式。
這是建議的方法，因為它提供最無縫的整合，並允許 Amazon Bedrock 自動處理聊天範本應用程式。
**範例：搭配自訂聊天範本使用 OpenAI ChatCompletion API**
```
import json
import boto3
# Initialize Bedrock Runtime client
client = boto3.client('bedrock-runtime', region_name='us-east-1')
# Define the model ARN for your imported model with custom chat template
model_id = 'arn:aws:bedrock:us-east-1:123456789012:imported-model/your-model-id'
# Prepare the request payload using messages format
payload = {
"messages": [
{
"role": "system",
"content": "You are a helpful assistant."
},
{
"role": "user",
"content": "Hello, how are you?"
}
],
"max_tokens": 150,
"temperature": 0.7
}
# Invoke the model
response = client.invoke_model(
modelId=model_id,
body=json.dumps(payload),
accept='application/json',
contentType='application/json'
)
# Parse and display the response
response_body = json.loads(response['body'].read())
print(json.dumps(response_body, indent=2))
```
在此範例中，Amazon Bedrock 會自動將自訂聊天範本套用至訊息陣列，並將其轉換為適合您模型的格式。
### 手動權杖化方法
或者，如果您偏好完全控制聊天範本應用程式和字符化程序，您可以手動將聊天範本套用至您的對話，然後使用**完成 API** （而非 ChatCompletion) 搭配預先格式化的文字。
當您需要自訂範本應用程式邏輯或處理特殊字符化需求時，此方法非常有用。
#### 步驟 1：在本機套用聊天範本
使用下列程式碼片段載入您的自訂聊天範本，並將其套用至本機的對話：
```
from transformers import AutoTokenizer
# Configuration paths - update these with your actual paths
TOKENIZER_PATH = "" # Path to tokenizer directory
# Load tokenizer with updated chat template
tokenizer = AutoTokenizer.from_pretrained(TOKENIZER_PATH)
# Test chat template with sample conversation
chat_history = [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello, how are you?"},
]
# Apply chat template and display formatted output to make sure chat template works as expected
formatted_chat = tokenizer.apply_chat_template(chat_history, tokenize=False)
print(formatted_chat)
```
此程式碼示範如何：
1. 從模型檔案載入您的字符器組態
1. 將自訂聊天範本新增至字符器組態
1. 將聊天範本套用至對話歷史記錄
1. 產生可傳送至模型的格式化文字
#### 步驟 2：使用完成 API 叫用
在本機套用聊天範本之後，請將格式化的文字與完成 API 搭配使用：
```
import json
import boto3
# Initialize Bedrock Runtime client
client = boto3.client('bedrock-runtime', region_name='us-east-1')
# Define the model ARN for your imported model
model_id = 'arn:aws:bedrock:us-east-1:123456789012:imported-model/your-model-id'
# Use the formatted_chat output from Step 1 as the prompt
payload = {
"prompt": formatted_chat,
"max_tokens": 150,
"temperature": 0.7
}
# Invoke the model using Completion format (not ChatCompletion)
response = client.invoke_model(
modelId=model_id,
body=json.dumps(payload),
accept='application/json',
contentType='application/json'
)
# Parse and display the response
response_body = json.loads(response['body'].read())
print(json.dumps(response_body, indent=2))
```
**警告**
**一律使用 `max_tokens` 參數：**使用 完成 API 搭配自訂模型匯入時，一律使用 `max_tokens` 參數以確保 OpenAI 完成結構描述相容性。這可避免任何翻譯混淆，並確保不同 SDK 實作的行為一致。請勿使用模型特定的參數名稱，例如 `max_gen_len`或類似變體。
**重要**
使用手動字符化方法時，您必須使用**完成 API** 格式 （使用 `prompt` 欄位），而非 ChatCompletion API 格式 （使用 `messages` 欄位）。ChatCompletion API 預期收到原始訊息，並會嘗試再次套用聊天範本，導致格式不正確。
### 最佳實務
+ **盡可能使用 ChatCompletion API** — 具有訊息格式的 OpenAI ChatCompletion API 可提供最無縫的體驗，並允許 Amazon Bedrock 自動處理聊天範本應用程式。
+ **驗證您的聊天範本** — 在匯入模型之前，請使用程式Transformers庫在本機測試您的聊天範本，以確保它產生預期的輸出格式。
+ **包含所有特殊字符** — 確保您的聊天範本包含模型預期的所有必要特殊字符 （例如beginning-of-sequence、end-of-sequence和角色標記）。
+ **使用多轉對話進行測試** — 驗證您的聊天範本是否使用交替使用者和助理訊息正確處理多轉對話。
+ **考慮視覺支援** — 如果您的模型支援多模態輸入，請確保您的聊天範本包含處理影像和影片內容標記的邏輯。
**警告**
格式不正確的聊天範本可能會導致模型效能不佳、意外輸出或推論失敗。在部署到生產環境之前，請務必徹底測試您的聊天範本。