Principle:Ollama Ollama ChatTemplate
| Knowledge Sources | |
|---|---|
| Domains | Chat Template, Model Configuration |
| Last Updated | 2025-02-15 00:00 GMT |
Overview
Chat Template Detection and Mapping is the principle of automatically identifying a model's expected prompt format by analyzing its bundled template metadata (typically HuggingFace Jinja2 templates) and mapping it to an equivalent template in the host system's native template language. This enables seamless multi-model support without requiring users to manually configure prompt formatting for each model.
Core Concepts
HuggingFace Chat Template Convention
HuggingFace established a convention where model repositories include a tokenizer_config.json file containing a chat_template field with a Jinja2 template string. This template defines how a list of messages (each with a role and content) should be formatted into the raw text prompt that the model expects. Different model families use vastly different formats: ChatML uses <|im_start|> tags, Llama uses [INST] markers, Mistral uses special tokens, and others use XML-like structures. The Jinja2 template is the authoritative specification of a model's expected format.
Template Fingerprinting
Since there are many possible Jinja2 template variations but a smaller set of fundamental prompt formats, template fingerprinting identifies which known format family a given Jinja2 template belongs to. This can be done through structural analysis (parsing the Jinja2 AST), hash-based matching (comparing normalized template strings against a known database), or output-based matching (rendering the template with canonical test inputs and comparing the output against known formats). Fingerprinting allows the system to map an arbitrary Jinja2 template to a pre-built native template without implementing a full Jinja2 interpreter.
Cross-Language Template Mapping
When the host system uses a different template engine than Jinja2 (e.g., Go's text/template), a mapping layer translates between the two. This is not a general-purpose Jinja2-to-Go transpiler but rather a curated index that maps known Jinja2 template fingerprints to hand-crafted equivalent templates in the target language. Each mapped template is validated to produce identical output for a comprehensive set of test cases covering edge cases like empty system prompts, tool calls, multi-turn conversations, and special token handling.
Template Index
A template index is a lookup table mapping template identifiers (names, hashes, or fingerprints) to their corresponding native template implementations. The index serves as the central registry for all supported prompt formats. When a model is loaded, its Jinja2 template is fingerprinted and looked up in the index. If a match is found, the corresponding native template is used. If no match is found, the system may fall back to a default template or attempt dynamic conversion.
Implementation Notes
In the Ollama codebase, chat template detection and mapping is implemented through a template index that maps known HuggingFace Jinja2 chat templates to equivalent Go text/template implementations. When a model is imported from a GGUF file containing a HuggingFace chat template, the system computes a fingerprint of the Jinja2 template and looks it up in the index. The index contains entries for all major model families including Llama, Mistral, ChatML, Phi, Gemma, Command-R, DeepSeek, and many others. Each entry maps a template name or hash to a Go template string that produces identical formatting output.