BroadRouter
Começar

Chat template (template de chat)

Atualizado em

Chat template é a regra de formatação, geralmente escrita em Jinja e distribuída com o tokenizer do modelo, que converte uma lista de mensagens de chat com papéis na sequência única de tokens que o modelo espera, incluindo os tokens especiais de controle. Usar o template errado pode piorar muito as respostas do modelo.

Também chamado de: template de chat, template Jinja de chat, chat_template, Jinja chat template, tokenizer chat template

Um modelo de chat nunca vê uma lista de mensagens. Ele vê uma única sequência longa de tokens. O chat template decide como essa sequência fica.

Como funciona

O guia do Hugging Face resume o ponto principal: todos os modelos de linguagem causais “continue a sequence of tokens” (tradução: continuam uma sequência de tokens), e os dicionários de papel e conteúdo que você passa “get converted to a token sequence, often with control tokens” (tradução: são convertidos em uma sequência de tokens, muitas vezes com tokens de controle). Modelos diferentes usam formatos diferentes, “even if they were fine-tuned from the same base model” (tradução: mesmo que tenham passado por fine-tuning a partir do mesmo modelo base).

O mesmo chat curto, renderizado por dois templates do guia:

Mistral-7B-Instruct:
<s>[INST] Hello, how are you? [/INST]I'm doing great. How can I help you today?</s>

Zephyr-7B:
<|user|>
Hello, how are you?</s>
<|assistant|>
I'm doing great. How can I help you today?</s>

No Transformers, você renderiza um chat com tokenizer.apply_chat_template(messages, add_generation_prompt=True). A flag add_generation_prompt adiciona os tokens que abrem um turno do assistente; sem eles, avisa o guia, o modelo pode continuar a mensagem do usuário em vez de responder.

Templates também podem carregar recursos do modelo. A card do Gemma 4 do Google diz que o thinking é ativado colocando um token <|think|> no início do system prompt, e que “many libraries like Transformers and llama.cpp handle the complexities of the chat template for you.” (tradução: muitas bibliotecas, como Transformers e llama.cpp, cuidam das complexidades do chat template para você.)

Por que isso importa

  • Qualidade. O guia diz que “with the wrong control tokens, these models would have drastically worse performance.” (tradução: com os tokens de controle errados, esses modelos teriam um desempenho drasticamente pior.)
  • Self-hosting. Os motores de serving precisam de um template para aceitar requisições de chat. A documentação do vLLM diz que, sem um, “all chat requests will error” (tradução: todas as requisições de chat vão dar erro), e aceita --chat-template para fornecê-lo. Veja vLLM.
  • Contagem de tokens. Tokens de controle contam como tokens de entrada. Nosso post sobre contar tokens antes de enviar explica por que as contagens locais e as cobradas diferem.
  • Tokens especiais em dobro. O guia avisa que adicionar <bos> ou <eos> de novo depois de aplicar o template “is often incorrect or duplicated, hurting model performance” (tradução: muitas vezes é incorreto ou duplicado, o que prejudica o desempenho do modelo).
  • O system prompt faz parte disso. Onde a mensagem de sistema entra, e se o modelo tem mesmo um papel de sistema, é o template que decide.

Na BroadNet Inference

A API da BroadNet é um endpoint de chat completions compatível com a OpenAI, então você envia messages e a BroadNet aplica o template; você não envia texto de template puro. A BroadNet relata que serve o Gemma 4 VL 26B com um “BroadNet conversational chat template”, um template ajustado para o fluxo conversacional dela. Se você comparar o Gemma da BroadNet com os mesmos pesos rodando localmente, as respostas podem diferir, então teste com os seus próprios prompts. A BroadNet não publica detalhes de template dos outros modelos. O post sobre a frota de GPUs e o serving lista as outras escolhas de serving do Gemma.

Perguntas frequentes

Preciso aplicar um chat template quando chamo uma API?

Não. Com uma API de chat completions, você envia uma lista de mensagens e o provedor aplica o template do lado dele. Você só lida com templates quando roda um modelo localmente ou chama um endpoint de completion de texto puro.

Por que minhas contagens de tokens são diferentes das do provedor?

O template adiciona tokens de controle em volta de cada mensagem. Se você conta só o texto das mensagens, eles ficam de fora, então o prompt cobrado costuma ser um pouco maior.

O que o add_generation_prompt faz?

Ele acrescenta os tokens que abrem um turno do assistente, para que o modelo responda em vez de continuar a sua mensagem. A documentação do Hugging Face mostra isso como um <|im_start|>assistant no final em templates no estilo ChatML.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity