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

# 处理自定义聊天模板和分词器
<a name="custom-chat-templates-tokenizers"></a>

自定义聊天模板和分词器是在导入的模型中正确格式化对话输入和管理代币生成的必不可少的组件。Custom Model Import 支持导入带有自定义聊天模板的模型，这些模板定义了多回合对话的结构和标记化方式。

## 使用自定义聊天模板导入模型
<a name="import-chat-template"></a>

使用自定义聊天模板导入模型时，请确保遵循自定义模型导入主文档中概述的最佳实践，包括以安全的张量格式引入模型权重以及提供所有必要的配置文件。

### 聊天模板格式要求
<a name="chat-template-format-requirements"></a>

如果您的模特使用自定义聊天模板，并且您想在 Amazon Bedrock 中使用该模板，则必须包含以下格式之一的聊天模板文件：
+ **`chat_template.jinja`**— 基于 Jinja2 的模板文件，用于定义消息的格式设置。
+ **`chat_template.json`**— 包含聊天模板作为字符串值的 JSON 文件。
+ **`tokenizer_config.json`带有嵌入式聊天模板** — 或者，您可以将聊天模板作为`chat_template`字段直接包含在`tokenizer_config.json`文件中。例如，请参阅 Hugging Face 上的 [Hermes-2-Pro tok](https://huggingface.co/NousResearch/Hermes-2-Pro-Llama-3-8B/blob/main/tokenizer_config.json#L2059) enizer\$1config.json。

Custom Model Import 将自动处理这些文件，并在导入过程中将它们包含在正确的目录中。

#### 聊天模板优先级
<a name="chat-template-precedence"></a>

如果您提供多个聊天模板来源，Amazon Bedrock 将应用以下优先规则：

1. **优先使用单独的聊天模板文件** — 如果您同时包含单独的聊天模板文件（`chat_template.jinja`或`chat_template.json`）和字`chat_template`段`tokenizer_config.json`，则将使用单独的文件，而其中嵌入的模板`tokenizer_config.json`将被忽略。

1. **嵌入式模板作为备**用 — 如果您不提供单独的聊天模板文件，Amazon Bedrock 将使用您的`chat_template`字段（`tokenizer_config.json`如果有）。

**警告**  
**选择一种方法：**为避免混淆并确保行为可预测，我们强烈建议仅使用以下方法之一：  
**选项 1：**提供单独的聊天模板文件（`chat_template.jinja`或`chat_template.json`），但不包含`chat_template`字段`tokenizer_config.json`。
**选项 2：**将该`chat_template`字段直接包含在您的中`tokenizer_config.json`，并且不要提供单独的模板文件。
如果您有自定义工具模板或复杂的聊天模板配置，我们建议您使用选项 2（将模板嵌入其中`tokenizer_config.json`），因为它允许您在单个配置文件中定义多个命名模板（例如 “default” 和 “tool\$1use”）。

**注意**  
聊天模板文件必须遵守 Hugging Face 格式和命名约定。确保您的模板与Transformers库兼容。

#### 聊天模板格式示例
<a name="chat-template-examples"></a>

以下是两种支持的聊天模板格式的示例：

------
#### [ Jinja Format (chat\$1template.jinja) ]

基于 Jinja2 的聊天模板的简化示例：

```
{% 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`）和格式。模板格式不正确可能会导致导入失败或推断失败。

## 使用自定义聊天模板调用模型
<a name="invoke-custom-chat-templates"></a>

导入带有自定义聊天模板的模型后，您可以通过两种方式使用格式正确的对话输入来调用模型：

### 在消息中使用 OpenAI ChatCompletion API
<a name="chatcompletion-api-approach"></a>

如果您以消息架构格式提供输入，则应使用 **OpenAI API ChatCompletion **。当您将此 API 格式与已上传的聊天模板（`chat_template.jinja`或`chat_template.json`）的模型一起使用时，Amazon Bedrock 会使用聊天模板自动将您的输入消息转换为正确的格式。

这是推荐的方法，因为它提供了最无缝的集成，并允许 Amazon Bedrock 自动处理聊天模板应用程序。

**示例：将 OpenA ChatCompletion I 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 会自动将您的自定义聊天模板应用于消息数组，将其转换为适合您模型的格式。

### 手动标记化方法
<a name="manual-tokenization-approach"></a>

或者，如果您希望完全控制聊天模板应用程序和标记化过程，则可以手动将聊天模板应用于对话，然后使用带有预格式化文本的**完成 API**（不是 ChatCompletion）。

当您需要自定义模板应用程序逻辑或处理专门的标记化要求时，这种方法非常有用。

#### 第 1 步：在本地应用聊天模板
<a name="apply-chat-template-locally"></a>

使用以下代码片段加载您的自定义聊天模板并将其应用于本地对话：

```
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 进行调用
<a name="invoke-with-completion-api"></a>

在本地应用聊天模板后，使用带有 Completion 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 需要原始消息，并将尝试再次应用聊天模板，从而导致格式不正确。

### 最佳实践
<a name="chat-template-best-practices"></a>
+ **尽可能使用 ChatCompletion API** — 带有消息格式的 OpenAI ChatCompletion API 可提供最无缝的体验，并允许 Amazon Bedrock 自动处理聊天模板应用程序。
+ **验证您的聊天模板**-在导入模型之前，请使用Transformers库在本地测试聊天模板，以确保其生成预期的输出格式。
+ **包括所有特殊标记** — 确保您的聊天模板包含模特期望的所有必要特殊标记（例如 beginning-of-sequence end-of-sequence、和角色标记）。
+ **使用多回合对话进行测试** — 验证您的聊天模板是否正确处理多回合对话以及交替使用用户和助手消息。
+ **考虑视觉支持** — 如果您的模型支持多模态输入，请确保您的聊天模板包含用于处理图像和视频内容标记的逻辑。

**警告**  
格式不正确的聊天模板可能会导致模型性能不佳、输出意外或推理失败。在部署到生产环境之前，请务必对聊天模板进行全面测试。