# Escrevendo um modelo de chat Um chat template é um template [Jinja](https://jinja.palletsprojects.com/en/stable/templates/) armazenado no atributo `~PreTrainedTokenizer.chat_template` do tokenizer. O Jinja é uma linguagem de templates que permite escrever código e sintaxe semelhantes aos do Python. ```jinja {%- for message in messages %} {{- '<|' + message['role'] + '|>\n' }} {{- message['content'] + eos_token }} {%- endfor %} {%- if add_generation_prompt %} {{- '<|assistant|>\n' }} {%- endif %} ``` Se você observar isso por um tempo, deve perceber que é muito parecido com Python, embora tenha uma sintaxe estranha de `{%-`. O template itera sobre uma lista de mensagens e, para cada mensagem, imprime o papel e o conteúdo da mensagem, seguido por um token de fim de sequência. Se `add_generation_prompt=True`, ele adiciona o cabeçalho inicial de uma mensagem do assistente ao final da conversa. Carregue o template escrito como uma string e atribua-o ao atributo `chat_template` do tokenizer. Uma vez definido, o template é usado sempre que você chama [apply_chat_template()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template). Ele também é salvo com o tokenizer sempre que [save_pretrained()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) ou [push_to_hub()](/docs/transformers/main/pt/main_classes/model#transformers.utils.PushToHubMixin.push_to_hub) é chamado. O template é salvo no arquivo `chat_template.jinja` no diretório do tokenizer. Você pode editar esse arquivo diretamente para alterar o template, o que muitas vezes é mais fácil do que manipular uma string de template. Consulte [Armazenar e carregar templates de chat](#storing-and-loading-chat-templates) abaixo para as outras formas em disco que o Transformers suporta. ## Dicas para escrever templates A maneira mais fácil de começar a escrever templates Jinja é consultar templates existentes. Use `print(tokenizer.chat_template)` em qualquer modelo de chat para ver o template que ele está usando. Tente começar com modelos simples que não chamam ferramentas nem suportam RAG, pois modelos de uso de ferramentas podem ter templates muito complexos. Por fim, consulte a [documentação do Jinja](https://jinja.palletsprojects.com/en/stable/templates/#synopsis) para mais detalhes sobre formatação e sintaxe. Há algumas dicas e armadilhas específicas que você pode encontrar ao escrever templates de chat, e esta seção abordará alguns deles em mais detalhes. ### Escrevendo modelos de chat multimodais Para modelos multimodais, o atributo `chat_template` é definido no **processor**, e não no tokenizer. A chave `content` de uma mensagem é frequentemente uma lista de dicionários de conteúdo, em vez de apenas uma única string. Você pode querer verificar o tipo de cada item de conteúdo na lista e tratá-lo de acordo. Em geral, o template não deve acessar diretamente dados de imagem ou vídeo. Normalmente, isso é tratado pelo processador após a renderização do template ser concluída. Em vez disso, seu template deve emitir um único token especial, como `<|image|>` ou `<|video|>`, quando encontrar conteúdo de imagem ou vídeo. O processador expandirá o único token especial em uma sequência de tokens de imagem ou vídeo posteriormente. Os tokens exatos a serem emitidos dependem do modelo com o qual você está trabalhando. Recomendamos fortemente carregar um processador multimodal existente para ver como ele trata os dados. O modelo de exemplo abaixo trata conteúdo misto de imagem e texto. ```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 %} ``` Este template multimodal é muito semelhante ao template mais simples acima, mas ele verifica listas de `content` e itera sobre elas para renderizar tokens `<|image|>` onde necessário. Isso permite que as imagens sejam inseridas "no fluxo" do texto do usuário. Nem todos os modelos funcionam assim — alguns, por exemplo, podem mover todas as imagens para o final da mensagem do usuário. O modelo de chat deve sempre corresponder ao formato com o qual o modelo foi treinado. ### Removendo espaços em branco O Jinja imprime qualquer espaço em branco antes ou depois de um bloco de texto. Isso pode ser um problema para modelos de chat, pois adicionar espaços em branco extras que não estavam presentes durante o treinamento do modelo pode prejudicar o desempenho. Para remover os espaços em branco, adicione `-` à sintaxe de linha do Jinja. Isso permite que você escreva seu modelo com indentação e quebras de linha no estilo Python, sem imprimir acidentalmente uma indentação na saída renderizada. O modelo de exemplo abaixo não usa `-`, resultando em espaços em branco extras na saída. ```jinja {% for message in messages %} {{ message['role'] + message['content'] }} {% endfor %} ``` Recomendamos fortemente o uso de `-` para garantir que apenas o conteúdo pretendido seja exibido. ```jinja {%- for message in messages %} {{- message['role'] + message['content'] }} {%- endfor %} ``` ### Variáveis e chamáveis especiais As únicas constantes em um template são a variável `messages` e o booleano `add_generation_prompt`. No entanto, você tem acesso a **quaisquer outros argumentos de palavra-chave que forem passados** ao método [apply_chat_template()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template). Isso oferece flexibilidade e permite o suporte a casos de uso que talvez não tenhamos considerado ao projetar a especificação. A variável adicional mais comum é `tools`, que contém uma lista de ferramentas em formato de esquema JSON. Embora você possa usar qualquer nome de variável que desejar, recomendamos fortemente seguir a convenção e usar `tools` para esse fim. Isso torna os modelos mais compatíveis com a API padrão. Você também tem acesso a quaisquer tokens contidos em `tokenizer.special_tokens_map`, que frequentemente inclui tokens especiais como `bos_token` e `eos_token`. Acesse-os diretamente pelo nome, como `{{- bos_token }}`. Há duas funções chamáveis disponíveis para você. Para chamá-las, use `{{- function_name(argument) }}`. - `raise_exception(msg)` levanta uma `TemplateException`. Isso é útil para depuração ou para alertar os usuários sobre o uso incorreto de modelos. - `strftime_now(format_str)` recupera a data e a hora atuais em um formato específico, o que é frequentemente necessário em mensagens de sistema. É equivalente a [datetime.now().strftime(format_str)](https://docs.python.org/3/library/datetime.html#datetime.datetime.now) em Python. ### Compatibilidade com Jinja não em Python O Jinja é implementado em várias linguagens e, em geral, possui a mesma sintaxe. Escrever um modelo em Python permite o uso de métodos do Python, como [lower](https://docs.python.org/3/library/stdtypes.html#str.lower) em strings ou [items](https://docs.python.org/3/library/stdtypes.html#dict.items) em dicts. No entanto, isso não funcionará se o modelo for usado em uma implementação que não seja em Python, por exemplo, ao fazer o deploy com Javascript ou Rust. Faça as alterações abaixo para garantir compatibilidade em todas as implementações do Jinja. - Substitua os métodos Python por filtros Jinja. Por exemplo, substitua `string.lower()` por `string|lower` ou `dict.items()` por `dict|dictitems`. A maioria das alterações segue o mesmo padrão, exceto `string.strip()`, que é substituído por `string|trim`. Consulte a lista de [filtros integrados](https://jinja.palletsprojects.com/en/3.1.x/templates/#builtin-filters) para obter a lista completa de filtros. - Substitua `True`, `False` e `None` (específicos do Python) por `true`, `false` e `none`, respectivamente. - Renderizar diretamente um dict ou uma list pode retornar resultados diferentes em outras implementações. Por exemplo, entradas de string podem mudar de aspas simples para aspas duplas. Para evitar isso, adicione o filtro [tojson](https://jinja.palletsprojects.com/en/3.1.x/templates/#jinja-filters.tojson) para manter a consistência. ### Modelos grandes Modelos mais recentes ou modelos com recursos como [tool-calling](./chat_extras) e RAG exigem templates maiores, que podem ter mais de 100 linhas. Pode ser mais fácil escrever templates maiores em um arquivo separado. Os números de linha no arquivo separado correspondem exatamente aos números de linha nos erros de análise ou execução do template, o que facilita a depuração de possíveis problemas. Escreva o template em um arquivo separado e extraia-o para o chat template. ```py open("template.jinja", "w").write(tokenizer.chat_template) ``` Você também pode carregar um modelo editado de volta no tokenizer. ```py tokenizer.chat_template = open("template.jinja").read() ``` ## Armazenar e carregar modelos de chat Os modelos de chat são armazenados em disco em vários formatos diferentes. Os checkpoints modernos salvam os modelos como arquivos `.jinja` independentes, enquanto os checkpoints antigos os incorporam na configuração do tokenizer ou do processor. ### Formatos de armazenamento Os modelos podem ser armazenados em qualquer um dos seguintes formatos. - `chat_template.jinja` (recomendado). Um arquivo Jinja independente na raiz do repositório, contendo um único chat template. É isso que o [save_pretrained()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) grava por padrão. Armazenar o template em um arquivo próprio facilita inspecioná-lo, editá-lo e comparar diferenças. Tanto tokenizers quanto processors carregam o `chat_template.jinja` da mesma forma. - `additional_chat_templates/.jinja`. Um diretório de arquivos Jinja independentes usado quando um modelo é distribuído com vários templates nomeados (por exemplo, um template `default` e um template `tool_use` separado). O template `default` continua em `chat_template.jinja` na raiz do repositório, mas todos os outros templates nomeados ficam em `additional_chat_templates/.jinja`, em que o nome do arquivo (sem a extensão) é o nome do template. > [!WARNING] > Os formatos legados abaixo são mantidos apenas para carregamento com compatibilidade reversa. Não escreva modelos de chat em nenhum deles. - campo `chat_template` em `tokenizer_config.json`. Um formato legado somente para carregamento, usado antes dos arquivos `.jinja` independentes. O template é incorporado como uma string JSON em `tokenizer_config.json`. Quando um modelo possui múltiplos templates nomeados, o campo é uma lista de dicts `{"name": ..., "template": ...}` em vez de uma única string. Repositórios existentes que usam esse formato continuam a ser carregados, mas [save_pretrained()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.save_pretrained) grava o formato moderno `.jinja` em vez disso. - `chat_template.json`. Um formato legado somente para carregamento, usado por checkpoints de processadores multimodais mais antigos. Um arquivo JSON no formato `{"chat_template": "