# 编写聊天模板 聊天模板是存储在分词器 `~PreTrainedTokenizer.chat_template` 属性中的 [Jinja](https://jinja.palletsprojects.com/en/stable/templates/) 模板。Jinja 是一种模板语言，允许你编写类似 Python 的代码和语法。 ```jinja {%- for message in messages %} {{- '<|' + message['role'] + '|>\n' }} {{- message['content'] + eos_token }} {%- endfor %} {%- if add_generation_prompt %} {{- '<|assistant|>\n' }} {%- endif %} ``` 如果你仔细研究一下，就会发现它其实非常像 Python，只是带有一些奇怪的 `{%-` 语法。该模板会遍历一个消息列表，对于每条消息，它会打印该消息的角色和内容，随后是一个序列结束标记。如果 `add_generation_prompt=True`，它会在对话末尾添加一条助手消息的起始头部。 将已写入的模板作为字符串加载，并将其赋值给分词器的 `chat_template` 属性。设置完成后，每次调用 [apply_chat_template()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template) 时都会使用该模板。此外，当调用 [save_pretrained()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 或 [push_to_hub()](/docs/transformers/main/zh/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) 时，该模板也会随分词器一起保存。模板会保存在分词器目录下的 `chat_template.jinja` 文件中。您可以直接编辑此文件来修改模板，这通常比操作模板字符串更简单。有关 Transformers 支持的其他磁盘存储格式，请参阅下文中的 [存储和加载聊天模板](#storing-and-loading-chat-templates)。 ## 模板编写技巧 开始编写 Jinja 模板最简单的方法是参考现有的模板。对任意聊天模型使用 `print(tokenizer.chat_template)` 即可查看其使用的模板。建议从不调用任何工具或不支持 RAG 的简单模型入手，因为工具调用模型的模板可能非常复杂。最后，请查阅 [Jinja 文档](https://jinja.palletsprojects.com/en/stable/templates/#synopsis) 以了解有关格式和语法的更多详细信息。 不过，在编写聊天模板时，你可能会遇到一些特定的技巧和陷阱，本节将更详细地介绍其中的一些内容。 ### 编写多模态聊天模板 对于多模态模板，`chat_template` 属性设置在 **processor** 上，而不是 tokenizer 上。消息的 `content` 键通常是一个内容字典列表，而不仅仅是单个字符串。您可能需要检查列表中每个内容项的类型，并相应地进行处理。 通常，模板不应直接访问图像或视频数据。这通常由处理器在模板渲染完成后处理。相反，当模板遇到图像或视频内容时，应输出一个特殊的标记，例如 `<|image|>` 或 `<|video|>`。处理器随后会将这个单一的特殊标记扩展为一系列图像或视频标记。具体应输出哪些标记取决于你正在使用的模型。我们强烈建议加载一个现有的多模态处理器，以查看其如何处理数据。 下面的示例模板处理混合的图像和文本内容。 ```jinja {%- for message in messages %} {%- if loop.index0 == 0 %} {{- bos_token }} {%- endif %} {{- '<|start_header_id|>' + message['role'] + '<|end_header_id|>\n\n' }} {%- if message['content'] is string %} {{- message['content'] }} {%- else %} {%- for content in message['content'] %} {%- if content['type'] == 'image' %} {{- '<|image|>' }} {%- elif content['type'] == 'text' %} {{- content['text'] }} {%- endif %} {%- endfor %} {%- endif %} {{- '<|eot_id|>' }} {%- endfor %} {%- if add_generation_prompt %} {{- '<|start_header_id|>assistant<|end_header_id|>\n\n' }} {%- endif %} ``` 这个多模态模板与上面更简单的模板非常相似，但它会检查 `content` 列表，并对其进行迭代，在需要的位置渲染 `<|image|>` 标记。这使得图像可以“融入”用户文本的流程中。 并非所有模型都采用这种方式——例如，某些模型可能会将所有图像移至用户消息的末尾。聊天模板始终应与模型训练时所使用的格式保持一致。 ### 修剪空白 Jinja 会输出文本块前后存在的任何空白字符。对于聊天模板而言，这可能是一个问题，因为添加模型训练时不存在的额外空白字符可能会损害性能。要去除这些空白字符，请在 Jinja 行语法中添加 `-`。这样，您就可以使用符合 Python 风格的缩进和换行来编写模板，而不会在渲染后的输出中意外地打印出缩进。 下面的示例模板未使用 `-`，导致输出中会打印出多余的空白。 ```jinja {% for message in messages %} {{ message['role'] + message['content'] }} {% endfor %} ``` 我们强烈建议使用 `-` 以确保仅打印预期的内容。 ```jinja {%- for message in messages %} {{- message['role'] + message['content'] }} {%- endfor %} ``` ### 特殊变量和可调用对象 模板中唯一的常量是 `messages` 变量和 `add_generation_prompt` 布尔值。不过，你可以访问传递给 [apply_chat_template()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template) 方法的**任何其他关键字参数**。 这提供了灵活性，并支持我们在设计规范时可能未曾想到的使用场景。最常见的附加变量是 `tools`，它包含一个以 JSON schema 格式表示的工具列表。虽然您可以使用任意变量名，但我们强烈建议遵循惯例，将此用途的变量命名为 `tools`。这使模板与标准 API 具有更好的兼容性。 您还可以访问 `tokenizer.special_tokens_map` 中包含的任何 token，其中通常包括 `bos_token` 和 `eos_token` 等特殊 token。您可以像 `{{- bos_token }}` 这样直接通过名称访问它们。 有两个可供调用的函数。要调用它们，请使用 `{{- function_name(argument) }}`。 - `raise_exception(msg)` 会引发一个 `TemplateException`。这在调试或提醒用户模板使用有误时非常有用。 - `strftime_now(format_str)` 以特定格式获取当前日期和时间，这在系统消息中经常需要。它等同于 Python 中的 [datetime.now().strftime(format_str)](https://docs.python.org/3/library/datetime.html#datetime.datetime.now)。 ### 与非 Python Jinja 的兼容性 Jinja 已用多种语言实现，且语法基本一致。在 Python 中编写模板时，您可以对字符串使用 [lower](https://docs.python.org/3/library/stdtypes.html#str.lower) 等 Python 方法，或对字典使用 [items](https://docs.python.org/3/library/stdtypes.html#dict.items)。但如果模板在非 Python 实现中使用（例如使用 Javascript 或 Rust 进行部署时），这些方法将不可用。 进行以下更改，以确保在所有 Jinja 实现中保持兼容性。 - 用 Jinja 过滤器替换 Python 方法。例如，将 `string.lower()` 替换为 `string|lower`，或将 `dict.items()` 替换为 `dict|dictitems`。除 `string.strip()` 外，大多数更改都遵循相同的模式，`string.strip()` 应替换为 `string|trim`。完整的过滤器列表请参阅 [内置过滤器](https://jinja.palletsprojects.com/en/3.1.x/templates/#builtin-filters)。 - 将 `True`、`False` 和 `None`（这些是 Python 特有的）分别替换为 `true`、`false` 和 `none`。 - 直接渲染 dict 或 list 在其他实现中可能会返回不同的结果。例如，字符串项可能从单引号变为双引号。为避免这种情况，请添加 [tojson](https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.tojson) 过滤器以保持一致性。 ### 大型模板 较新的模型或具备 [tool-calling](./chat_extras) 和 RAG 等功能的模型需要更大的模板，其长度可能超过 100 行。在单独的文件中编写较大的模板可能更为方便。单独文件中的行号与模板解析或执行错误中的行号完全对应，从而更便于调试潜在问题。 将模板写入单独的文件，并将其提取到聊天模板中。 ```py open("template.jinja", "w").write(tokenizer.chat_template) ``` 您也可以将编辑后的模板重新加载到分词器中。 ```py tokenizer.chat_template = open("template.jinja").read() ``` ## 存储和加载聊天模板 Chat 模板以多种不同的格式存储在磁盘上。现代检查点将模板保存为独立的 `.jinja` 文件，而较早的检查点则将其嵌入到分词器或处理器配置中。 ### 存储格式 模板可以存储为以下任意一种格式。 - `chat_template.jinja`（推荐）。位于仓库根目录的独立 Jinja 文件，包含单个聊天模板。[save_pretrained()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 默认写入此文件。将模板存储在独立文件中便于检查、编辑和对比。tokenizer 和 processor 以相同方式加载 `chat_template.jinja`。 - `additional_chat_templates/.jinja`。一个包含独立 Jinja 文件的目录，用于模型附带多个命名模板的情况（例如，一个 `default` 模板和一个单独的 `tool_use` 模板）。`default` 模板仍然放在仓库根目录的 `chat_template.jinja` 中，但其他所有命名模板都放在 `additional_chat_templates/.jinja` 中，其中文件名的主干部分即为模板名称。 > [!WARNING] > 以下旧格式仅保留用于向后兼容的加载。请勿将聊天模板写入其中任何一种格式。 - `tokenizer_config.json` 中的 `chat_template` 字段。这是一种仅用于加载的旧版格式，在独立的 `.jinja` 文件出现之前使用。该模板以 JSON 字符串的形式嵌入在 `tokenizer_config.json` 中。当模型包含多个命名模板时，该字段是一个由 `{"name": ..., "template": ...}` 字典组成的列表，而不是单个字符串。使用此格式的现有仓库仍可正常加载，但 [save_pretrained()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) 会写入现代的 `.jinja` 格式。 - `chat_template.json`。一种仅用于加载的旧版格式，由较早的多模态处理器检查点使用。它是一个 JSON 文件，形式为 `{"chat_template": "