← All notes

Answer: A chat template turns a list of {role, content} messages into the exact token sequence a chat model was trained on, including control tokens.

from transformers import AutoTokenizer
tok = AutoTokenizer.from_pretrained("HuggingFaceH4/zephyr-7b-beta")

messages = [
    {"role": "system", "content": "You are a helpful science assistant."},
    {"role": "user", "content": "Why is the sky blue?"},
]
text = tok.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
ids = tok.apply_chat_template(messages, add_generation_prompt=True, return_tensors="pt")

Key points

• Messages are dictionaries with role and content keys; common roles are system, user and assistant.
• add_generation_prompt=True appends the marker for the assistant's turn so the model answers rather than continuing the user message.
• Two models fine-tuned from the same base can still use different templates.

Pipelines

from transformers import pipeline
chat = pipeline("text-generation", model="HuggingFaceH4/zephyr-7b-beta")
chat(messages, max_new_tokens=128)

Claims

• id: C1 claim: Chats are converted to token sequences, often with control tokens. source: S1 evidence: "to a chat model get converted to a token sequence, often with control tokens like"
• id: C2 claim: apply_chat_template input is a list of dictionaries with role and content keys. source: S1 evidence: "The input to apply_chat_template should be structured as a list of dictionaries with role"
• id: C3 claim: Chat models accept a list of messages as input. source: S2 evidence: "Chat models accept a list of messages (the chat history) as the input."
• id: C4 claim: You can include a system message to direct behavior. source: S2 evidence: "You can also optionally include a system message to give the model directions"

Sources

• [S1] Chat templates · Hugging Face. Hugging Face docs. https://huggingface.co/docs/transformers/chat_templating . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-04.
• [S2] Chat basics · Hugging Face. Hugging Face docs. https://huggingface.co/docs/transformers/conversations . License: Apache-2.0 (huggingface docs repos). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_gr0g8me5,
  author = {{iinventedlight}},
  title = {{Chat templates in Hugging Face Transformers}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/hf-chat-templates/},
  note = {Permanent ID iil:note:gr0g8me5. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/hf-chat-templates.md.