The Chat Templates Handbook

Your model passed every benchmark, then quietly got worse in production - and nothing in your logs says why. The culprit is almost always the same invisible layer: the chat template, the code that turns your list of messages into the exact tokens the model was trained on. Get it wrong and the model still answers. It just answers worse, silently, with no error to chase. This book is about that layer, and how to make it correct, portable, tested, and safe. Why chat templates matter more than ever Every instruct model on Hugging Face ships a Jinja chat template, and apply_chat_template() is the universal entry point behind LangChain, vLLM, SGLang, llama.cpp, and Ollama. As models gained tools, reasoning, and vision, that template grew from ten lines into a hundred-line program that breaks in new ways - and renders differently across engines. The role-tagged message list is the one stable contract underneath every modern LLM API. This book teaches you to render it correctly, everywhere. What you will learn

• Render conversations the way the model was actually trained, with apply_chat_template()
• Read and write Jinja chat templates, including the whitespace control that silently breaks tokenization
• Handle tool-calling, reasoning (thinking), and multimodal templates - and parse what the model emits back
• Author and ship a correct template for your own fine-tuned model, so it never drifts from the weights
• Debug broken templates and lock their behavior with golden-token tests in CI
• Find and fix cross-engine differences between Transformers, vLLM, and llama.cpp
• Defend against malicious templates - a real, documented inference-time attack surface

• Part I - Foundations: the gap between messages and tokens, the message model, just enough Jinja, and template anatomy across Llama, Qwen, and Gemma.
• Part II - The Hard Parts: tool-calling, reasoning, and multimodal templates, and authoring your own.
• Part III - Production: cross-engine rendering, debugging, security, and a complete template toolkit you can drop into CI.

• AI and backend engineers who ship LLM features and have used apply_chat_template()
• ML engineers fine-tuning open models who now own a chat template
• Platform and ML-infrastructure teams serving open models across multiple engines