How to Write a Chat Template for a Fine-Tuned Model and Test It

string   okmarkers  oktokens   okmask     oklabels   okstops    okpasses

cd chat-templates-part1source .venv/bin/activateexport TRANSFORMERS_NO_ADVISORY_WARNINGS=1

pip install "trl==1.17.1" "datasets==5.2.0" "accelerate==1.15.0" \    "transformers==5.22.1" "tokenizers==0.23.3" "huggingface-hub==2.4.0"

# families.py (add at the end)# Part 8: a 2-layer test model from the TRL team that uses Qwen3's tokenizer.TINY_MODEL = "trl-internal-testing/tiny-Qwen3ForCausalLM"

# check_trainer_versions.pyimport accelerateimport datasetsimport huggingface_hubimport tokenizersimport transformersimport trlprint(    transformers.__version__,    tokenizers.__version__,    huggingface_hub.__version__,    trl.__version__,    datasets.__version__,    accelerate.__version__,)

# fetch_support_models.pyfrom transformers import AutoConfigfrom families import FAMILIES, TINY_MODELfrom templatestudio.render import load_tokenizerfor model_id in (FAMILIES["qwen3"], TINY_MODEL):    tokenizer = load_tokenizer(model_id)    rows = AutoConfig.from_pretrained(model_id).vocab_size    print(f"{model_id:43} tokens {len(tokenizer)}  embedding rows {rows}")

python check_trainer_versions.pypython fetch_support_models.py

5.22.1 0.23.3 2.4.0 1.17.1 5.2.0 1.15.0Qwen/Qwen3-0.6B                             tokens 151669  embedding rows 151936trl-internal-testing/tiny-Qwen3ForCausalLM  tokens 151669  embedding rows 151936

# support_data.py# One training example for a support model, as messages and as the exact text# the fine-tuning data was formatted into. Every turn ends with <|end|>.SUPPORT_CONVERSATION = [    {"role": "system", "content": "You are a support agent."},    {"role": "user", "content": "Where is my order?"},    {"role": "assistant", "content": "Let me check."},    {"role": "user", "content": "It is order 1042."},    {"role": "assistant", "content": "Order 1042 ships today."},]SUPPORT_TEXT = (    "<|system|>\nYou are a support agent.<|end|>\n"    "<|user|>\nWhere is my order?<|end|>\n"    "<|assistant|>\nLet me check.<|end|>\n"    "<|user|>\nIt is order 1042.<|end|>\n"    "<|assistant|>\nOrder 1042 ships today.<|end|>\n")

# show_training_format.pyimport sysfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.render import visible_whitespacesys.stdout.reconfigure(encoding="utf-8")print(len(SUPPORT_CONVERSATION), "messages,", len(SUPPORT_TEXT), "characters")print(visible_whitespace(SUPPORT_TEXT), end="")

python show_training_format.py

5 messages, 192 characters<|system|>\nYou·are·a·support·agent.<|end|>\n<|user|>\nWhere·is·my·order?<|end|>\n<|assistant|>\nLet·me·check.<|end|>\n<|user|>\nIt·is·order·1042.<|end|>\n<|assistant|>\nOrder·1042·ships·today.<|end|>\n

# templatestudio/authoring.pyfrom __future__ import annotationsfrom collections.abc import Sequencefrom transformers import GenerationConfig, PreTrainedModel, PreTrainedTokenizerBasefrom templatestudio.jinja_env import render_template_stringfrom templatestudio.messages import Conversationfrom templatestudio.render import first_divergence, load_tokenizer, render_idsEND_OF_TURN = "<|end|>"MARKERS = ("<|system|>", "<|user|>", "<|assistant|>", END_OF_TURN)# Transcribed from the training format. The assistant's words and its <|end|># sit inside {% generation %}: the model writes them, so the loss covers them.# The role header comes from the prompt and the newline after <|end|> comes# from the template, so both stay outside.SUPPORT_TEMPLATE = (    "{% for message in messages %}"    "{{- '<|' + message['role'] + '|>\n' }}"    "{%- if message['role'] == 'assistant' %}"    "{% generation %}{{- message['content'] + '<|end|>' }}{% endgeneration %}"    "{{- '\n' }}"    "{%- else %}"    "{{- message['content'] + '<|end|>\n' }}"    "{%- endif %}"    "{%- endfor %}"    "{%- if add_generation_prompt %}{{- '<|assistant|>\n' }}{%- endif %}")def install_template(    tokenizer: PreTrainedTokenizerBase, template_source: str) -> PreTrainedTokenizerBase:    """Make template_source the tokenizer's chat template.    apply_chat_template uses it from now on, and save_pretrained writes it to    chat_template.jinja beside the tokenizer files.    """    tokenizer.chat_template = template_source    return tokenizer

# show_support_render.pyfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.authoring import SUPPORT_TEMPLATE, install_templatefrom templatestudio.jinja_env import render_template_stringfrom templatestudio.render import load_tokenizerserved = render_template_string(SUPPORT_TEMPLATE, SUPPORT_CONVERSATION)print("identical to the training text:", served == SUPPORT_TEXT)prompt = render_template_string(    SUPPORT_TEMPLATE, SUPPORT_CONVERSATION[:4], add_generation_prompt=True)print("generation prompt ends with:", repr(prompt[-28:]))tokenizer = install_template(load_tokenizer(FAMILIES["qwen3"]), SUPPORT_TEMPLATE)installed = tokenizer.apply_chat_template(SUPPORT_CONVERSATION, tokenize=False)print("installed on the tokenizer, same text:", installed == SUPPORT_TEXT)

python show_support_render.py

identical to the training text: Truegeneration prompt ends with: ' 1042.<|end|>\n<|assistant|>\n'installed on the tokenizer, same text: True

# templatestudio/authoring.py (add at the end)def check_string_roundtrip(    template_source: str, conversation: Conversation, trained_text: str) -> list[str]:    """Compare the template's render with the exact text the model trained on."""    served = render_template_string(template_source, conversation)    at = first_divergence(served, trained_text)    if at is None:        return []    return [        f"text differs at character {at}: trained "        f"{trained_text[at:at + 12]!r}, served {served[at:at + 12]!r}"    ]

# broken_templates.py# Copies of SUPPORT_TEMPLATE with one mistake each, for the failing cases.from templatestudio.authoring import SUPPORT_TEMPLATE# The serving copy someone edited: one extra newline after every role header.DRIFTED = SUPPORT_TEMPLATE.replace("'|>\n'", "'|>\n\n'")

# show_string_check.pyfrom broken_templates import DRIFTEDfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.authoring import SUPPORT_TEMPLATE, check_string_roundtripfor name, template in [("authored", SUPPORT_TEMPLATE), ("drifted", DRIFTED)]:    problems = check_string_roundtrip(template, SUPPORT_CONVERSATION, SUPPORT_TEXT)    print(f"{name}:", "ok" if not problems else "")    for problem in problems:        print("   ", problem)

python show_string_check.py

authored: okdrifted:     text differs at character 11: trained 'You are a su', served '\nYou are a s'

# templatestudio/authoring.py (add at the end)def check_marker_tokens(    tokenizer: PreTrainedTokenizerBase, markers: Sequence[str] = MARKERS) -> list[str]:    """Report every marker that is not exactly one token in the vocabulary."""    problems = []    for marker in markers:        ids = tokenizer.encode(marker, add_special_tokens=False)        if len(ids) != 1:            pieces = tokenizer.convert_ids_to_tokens(ids)            problems.append(f"{marker!r} is {len(ids)} tokens: {pieces}")    return problemsdef add_markers(    tokenizer: PreTrainedTokenizerBase, markers: Sequence[str] = MARKERS) -> int:    """Add the markers as special tokens, so each encodes to one ID."""    return tokenizer.add_tokens(list(markers), special_tokens=True)def authored_tokenizer(model_id: str) -> PreTrainedTokenizerBase:    """Load a base tokenizer, add the markers, and install the template."""    tokenizer = load_tokenizer(model_id)    add_markers(tokenizer)    return install_template(tokenizer, SUPPORT_TEMPLATE)

# show_marker_split.pyfrom families import FAMILIESfrom templatestudio.authoring import (    SUPPORT_TEMPLATE,    add_markers,    authored_tokenizer,    check_marker_tokens,)from templatestudio.render import load_tokenizertokenizer = load_tokenizer(FAMILIES["qwen3"])for problem in check_marker_tokens(tokenizer):    print(problem)print("added", add_markers(tokenizer), "tokens")print("after:", check_marker_tokens(tokenizer) or "every marker is one token")print("ids:", tokenizer.convert_tokens_to_ids(["<|system|>", "<|end|>"]))authored = authored_tokenizer(FAMILIES["qwen3"])print("authored_tokenizer:", check_marker_tokens(authored) or "markers ok", end=", ")print("template", "ok" if authored.chat_template == SUPPORT_TEMPLATE else "missing")

python show_marker_split.py

'<|system|>' is 5 tokens: ['<', '|', 'system', '|', '>']'<|user|>' is 5 tokens: ['<', '|', 'user', '|', '>']'<|assistant|>' is 5 tokens: ['<', '|', 'assistant', '|', '>']'<|end|>' is 5 tokens: ['<', '|', 'end', '|', '>']added 4 tokensafter: every marker is one tokenids: [151669, 151672]authored_tokenizer: markers ok, template ok

# templatestudio/authoring.py (add at the end)def ensure_embedding_rows(    model: PreTrainedModel, tokenizer: PreTrainedTokenizerBase) -> int:    """Grow the embedding matrix only if a token ID would fall outside it.    Returns the number of rows. Never shrinks: some models ship spare rows.    """    rows = model.get_input_embeddings().weight.shape[0]    if len(tokenizer) > rows:        model.resize_token_embeddings(len(tokenizer))        rows = len(tokenizer)    return rows

# show_embedding_rows.pyfrom transformers import AutoModelForCausalLMfrom families import FAMILIES, TINY_MODELfrom templatestudio.authoring import authored_tokenizer, ensure_embedding_rowstokenizer = authored_tokenizer(FAMILIES["qwen3"])model = AutoModelForCausalLM.from_pretrained(TINY_MODEL)print("tokens:", len(tokenizer))print("rows before:", model.get_input_embeddings().weight.shape[0])print("rows after ensure_embedding_rows:", ensure_embedding_rows(model, tokenizer))model.resize_token_embeddings(len(tokenizer))rows = model.get_input_embeddings().weight.shape[0]print("rows after resize_token_embeddings:", rows)

python show_embedding_rows.py

tokens: 151673rows before: 151936rows after ensure_embedding_rows: 151936rows after resize_token_embeddings: 151673

# trainer_batch.pyfrom datasets import Dataset, disable_progress_barsfrom transformers import AutoModelForCausalLM, PreTrainedTokenizerBasefrom transformers.utils import logging as transformers_loggingfrom trl import SFTConfig, SFTTrainerfrom families import TINY_MODELfrom templatestudio.authoring import END_OF_TURN, ensure_embedding_rowsdisable_progress_bars()transformers_logging.disable_progress_bar()def build_trainer(    tokenizer: PreTrainedTokenizerBase, conversations: list[list[dict]]) -> SFTTrainer:    """Build an SFTTrainer the way a fine-tune would, without training."""    model = AutoModelForCausalLM.from_pretrained(TINY_MODEL)    ensure_embedding_rows(model, tokenizer)    config = SFTConfig(        output_dir="trainer-out",        assistant_only_loss=True,        eos_token=END_OF_TURN,        use_cpu=True,        bf16=False,        report_to="none",    )    dataset = Dataset.from_list([{"messages": c} for c in conversations])    return SFTTrainer(        model=model, args=config, train_dataset=dataset, processing_class=tokenizer    )

# show_trainer_row.pyfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import authored_tokenizerfrom trainer_batch import build_trainertokenizer = authored_tokenizer(FAMILIES["qwen3"])trainer = build_trainer(tokenizer, [SUPPORT_CONVERSATION])row = trainer.train_dataset[0]print("columns:", trainer.train_dataset.column_names)print("embedding rows:", trainer.model.get_input_embeddings().weight.shape[0])print("input_ids:", len(row["input_ids"]), "ids")trained = [t for t in row["labels"] if t != -100]print("trained ids:", len(trained))print("trained text:", repr(tokenizer.decode(trained)))

python show_trainer_row.py

columns: ['messages', 'input_ids', 'labels']embedding rows: 151936input_ids: 53 idstrained ids: 15trained text: 'Let me check.<|end|>Order 1042 ships today.<|end|>'

# templatestudio/authoring.py (add at the end)def check_token_roundtrip(    tokenizer: PreTrainedTokenizerBase,    conversation: Conversation,    trained_ids: Sequence[int],) -> list[str]:    """Compare the served template's token IDs with the IDs the trainer used:    the whole conversation, then the generation prompt before each answer."""    served = render_ids(tokenizer, conversation, add_generation_prompt=False)    trained = [int(i) for i in trained_ids]    at = first_divergence(served, trained)    if at is not None:        window = slice(max(at - 2, 0), at + 3)        return [            f"tokens differ at position {at} "            f"(served {len(served)} ids, trained {len(trained)})",            f"served:  {tokenizer.convert_ids_to_tokens(served[window])}",            f"trained: {tokenizer.convert_ids_to_tokens(trained[window])}",        ]    problems = []    for k, message in enumerate(conversation):        if message["role"] != "assistant":            continue        prompt = render_ids(tokenizer, conversation[:k], add_generation_prompt=True)        at = first_divergence(prompt, trained[: len(prompt)])        if at is not None:            problems.append(                f"generation prompt before message {k} differs at position {at}: "                f"{tokenizer.convert_ids_to_tokens(prompt[at:at + 2])}"            )    return problems

# broken_templates.py (add at the end)# The generation prompt writes one more newline than the trained turns have.GEN_PROMPT_DRIFT = SUPPORT_TEMPLATE.replace(    "{{- '<|assistant|>\n' }}{%- endif %}",    "{{- '<|assistant|>\n\n' }}{%- endif %}",)

# show_token_check.pyimport sysfrom broken_templates import GEN_PROMPT_DRIFTfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.authoring import (    SUPPORT_TEMPLATE,    authored_tokenizer,    check_string_roundtrip,    check_token_roundtrip,    install_template,)from templatestudio.render import load_tokenizerfrom trainer_batch import build_trainersys.stdout.reconfigure(encoding="utf-8")tokenizer = authored_tokenizer(FAMILIES["qwen3"])trained_ids = build_trainer(tokenizer, [SUPPORT_CONVERSATION]).train_dataset[0][    "input_ids"]# The serving side loads the base tokenizer and installs the template only.served = install_template(load_tokenizer(FAMILIES["qwen3"]), SUPPORT_TEMPLATE)# A tokenizer with the markers, but a template whose generation prompt drifted.drifted = install_template(authored_tokenizer(FAMILIES["qwen3"]), GEN_PROMPT_DRIFT)cases = [("authored", tokenizer), ("template only", served), ("prompt drift", drifted)]for name, tok in cases:    text = check_string_roundtrip(tok.chat_template, SUPPORT_CONVERSATION, SUPPORT_TEXT)    tokens = check_token_roundtrip(tok, SUPPORT_CONVERSATION, trained_ids)    print(f"{name}: string", "ok" if not text else "differs")    print(f"{name}: tokens", "ok" if not tokens else "")    for line in tokens:        print("   ", line)

python show_token_check.py

authored: string okauthored: tokens oktemplate only: string oktemplate only: tokens     tokens differ at position 0 (served 78 ids, trained 53)    served:  ['<', '|', 'system']    trained: [None, 'Ċ', 'You']prompt drift: string okprompt drift: tokens     generation prompt before message 2 differs at position 20: ['ĊĊ']    generation prompt before message 4 differs at position 41: ['ĊĊ']

# templatestudio/authoring.py (add at the end)def check_assistant_mask(    tokenizer: PreTrainedTokenizerBase,    conversation: Conversation,    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check that each masked span is one assistant turn plus end_of_turn."""    encoded = tokenizer.apply_chat_template(        conversation, return_assistant_tokens_mask=True    )    ids, mask = encoded["input_ids"], encoded["assistant_masks"]    spans: list[list[int]] = []    current: list[int] = []    for token_id, flag in zip(ids, mask):        if flag:            current.append(token_id)        elif current:            spans.append(current)            current = []    if current:        spans.append(current)    turns = [m["content"] for m in conversation if m["role"] == "assistant"]    if not turns:        return ["the conversation has no assistant turn to mask"]    if not spans:        return ["the mask is all zeros: the template has no {% generation %}"]    if len(spans) != len(turns):        return [f"{len(spans)} masked spans for {len(turns)} assistant turns"]    problems = []    for i, (span, content) in enumerate(zip(spans, turns)):        expected = tokenizer.encode(content + end_of_turn, add_special_tokens=False)        if span != expected:            problems.append(                f"span {i} is {tokenizer.decode(span)!r}, "                f"not {content + end_of_turn!r}"            )    return problems

# broken_templates.py (add at the end)# <|end|> moved out of the generation block: the model never learns to stop.END_OUTSIDE = SUPPORT_TEMPLATE.replace(    "message['content'] + '<|end|>' }}{% endgeneration %}",    "message['content'] }}{% endgeneration %}{{- '<|end|>' }}",)

# show_mask_check.pyfrom broken_templates import END_OUTSIDEfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import (    SUPPORT_TEMPLATE,    authored_tokenizer,    check_assistant_mask,    install_template,)from templatestudio.render import load_tokenizercases = {    "authored": authored_tokenizer(FAMILIES["qwen3"]),    "markers not added": install_template(        load_tokenizer(FAMILIES["qwen3"]), SUPPORT_TEMPLATE    ),    "end outside": install_template(        authored_tokenizer(FAMILIES["qwen3"]), END_OUTSIDE    ),}for name, tokenizer in cases.items():    problems = check_assistant_mask(tokenizer, SUPPORT_CONVERSATION)    print(f"{name}:", "ok" if not problems else "")    for problem in problems:        print("   ", problem)

python show_mask_check.py

authored: okmarkers not added:     span 0 is 'Let me check.<|end|>\n', not 'Let me check.<|end|>'    span 1 is 'Order 1042 ships today.<|end|>\n', not 'Order 1042 ships today.<|end|>'end outside:     span 0 is 'Let me check.', not 'Let me check.<|end|>'    span 1 is 'Order 1042 ships today.', not 'Order 1042 ships today.<|end|>'

# templatestudio/authoring.py (add at the end)def check_trained_spans(    tokenizer: PreTrainedTokenizerBase,    labels: Sequence[int],    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check one row of real labels: every trained run ends on end_of_turn."""    end_id = tokenizer.convert_tokens_to_ids(end_of_turn)    problems = []    for i, label in enumerate(labels):        trained = label != -100        last_of_run = trained and (i + 1 == len(labels) or labels[i + 1] == -100)        if last_of_run and label != end_id:            text = tokenizer.decode([label])            problems.append(f"trained span ends at position {i} on {text!r}")    if all(label == -100 for label in labels):        problems.append("no position is trained")    return problems

# show_label_check.pyfrom broken_templates import END_OUTSIDEfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import (    SUPPORT_TEMPLATE,    authored_tokenizer,    check_trained_spans,    install_template,)from trainer_batch import build_trainerfor name, template in [("authored", SUPPORT_TEMPLATE), ("end outside", END_OUTSIDE)]:    tokenizer = install_template(authored_tokenizer(FAMILIES["qwen3"]), template)    trainer = build_trainer(tokenizer, [SUPPORT_CONVERSATION])    labels = trainer.train_dataset[0]["labels"]    problems = check_trained_spans(tokenizer, labels)    print(f"{name}:", "ok" if not problems else "")    for problem in problems:        print("   ", problem)

python show_label_check.py

authored: okend outside:     trained span ends at position 24 on '.'    trained span ends at position 50 on '.'

# templatestudio/authoring.py (add at the end)def check_stop_alignment(    tokenizer: PreTrainedTokenizerBase,    generation_config: GenerationConfig,    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check that generation stops on end_of_turn."""    ids = tokenizer.encode(end_of_turn, add_special_tokens=False)    if len(ids) != 1:        return [f"{end_of_turn!r} is {len(ids)} tokens, so it cannot be a stop ID"]    end_id = ids[0]    stops = generation_config.eos_token_id    stops = [stops] if isinstance(stops, int) else list(stops or [])    problems = []    if end_id not in stops:        problems.append(            f"{end_of_turn!r} (id {end_id}) is not in eos_token_id {stops}"        )    return problems

# show_stop_check.pyfrom transformers import GenerationConfigfrom families import FAMILIES, TINY_MODELfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import authored_tokenizer, check_stop_alignmentfrom trainer_batch import build_trainertokenizer = authored_tokenizer(FAMILIES["qwen3"])shipped = GenerationConfig.from_pretrained(TINY_MODEL)print("shipped eos_token_id:", shipped.eos_token_id)for problem in check_stop_alignment(tokenizer, shipped) or ["ok"]:    print("shipped:", problem)trainer = build_trainer(tokenizer, [SUPPORT_CONVERSATION])after = trainer.model.generation_configprint("after SFTTrainer eos_token_id:", after.eos_token_id)for problem in check_stop_alignment(tokenizer, after) or ["ok"]:    print("after:", problem)

python show_stop_check.py

shipped eos_token_id: [151645, 151643]shipped: '<|end|>' (id 151672) is not in eos_token_id [151645, 151643]after SFTTrainer eos_token_id: [151672, 151645, 151643]after: ok

# show_pad_trap.pyfrom transformers import DataCollatorForLanguageModelingfrom trl.trainer.sft_trainer import DataCollatorForLanguageModeling as TRLCollatorfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import authored_tokenizer, check_trained_spansfrom trainer_batch import build_trainertokenizer = authored_tokenizer(FAMILIES["qwen3"])row = build_trainer(tokenizer, [SUPPORT_CONVERSATION]).train_dataset[0]tokenizer.pad_token = "<|end|>"full = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)batch = full([{"input_ids": row["input_ids"]}])print("transformers collator:")for problem in check_trained_spans(tokenizer, batch["labels"][0].tolist()):    print("   ", problem)trl_batch = TRLCollator(pad_token_id=tokenizer.pad_token_id)([row])labels = trl_batch["labels"][0].tolist()print("TRL collator:", check_trained_spans(tokenizer, labels) or "ok")

python show_pad_trap.py

transformers collator:    trained span ends at position 7 on '.'    trained span ends at position 16 on '?'    trained span ends at position 24 on '.'    trained span ends at position 37 on '.'    trained span ends at position 50 on '.'    trained span ends at position 52 on '\n'TRL collator: ok

# templatestudio/authoring.py (replace check_stop_alignment)def check_stop_alignment(    tokenizer: PreTrainedTokenizerBase,    generation_config: GenerationConfig,    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check that generation stops on end_of_turn, and that padding cannot    mask it out of the loss."""    ids = tokenizer.encode(end_of_turn, add_special_tokens=False)    if len(ids) != 1:        return [f"{end_of_turn!r} is {len(ids)} tokens, so it cannot be a stop ID"]    end_id = ids[0]    stops = generation_config.eos_token_id    stops = [stops] if isinstance(stops, int) else list(stops or [])    problems = []    if end_id not in stops:        problems.append(            f"{end_of_turn!r} (id {end_id}) is not in eos_token_id {stops}"        )    if tokenizer.pad_token_id == end_id:        problems.append(            f"pad_token is {end_of_turn!r}: a pad-ID collator masks it from the loss"        )    return problems

# show_pad_stop_check.pyfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import authored_tokenizer, check_stop_alignmentfrom trainer_batch import build_trainertokenizer = authored_tokenizer(FAMILIES["qwen3"])config = build_trainer(tokenizer, [SUPPORT_CONVERSATION]).model.generation_configprint("pad <|endoftext|>:", check_stop_alignment(tokenizer, config) or "ok")tokenizer.pad_token = "<|end|>"for problem in check_stop_alignment(tokenizer, config):    print("pad <|end|>:", problem)

python show_pad_stop_check.py

pad <|endoftext|>: okpad <|end|>: pad_token is '<|end|>': a pad-ID collator masks it from the loss

# templatestudio/authoring.py (add at the end)def check_authored_model(    tokenizer: PreTrainedTokenizerBase,    generation_config: GenerationConfig,    conversation: Conversation,    trained_text: str,    trained_row: dict[str, list[int]],) -> dict[str, list[str]]:    """Run every check against one saved model. Empty lists mean it passes."""    template = tokenizer.chat_template    return {        "string": check_string_roundtrip(template, conversation, trained_text),        "markers": check_marker_tokens(tokenizer),        "tokens": check_token_roundtrip(            tokenizer, conversation, trained_row["input_ids"]        ),        "mask": check_assistant_mask(tokenizer, conversation),        "labels": check_trained_spans(tokenizer, trained_row["labels"]),        "stops": check_stop_alignment(tokenizer, generation_config),    }

# save_support_model.pyimport jsonfrom pathlib import Pathfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATIONfrom templatestudio.authoring import authored_tokenizerfrom trainer_batch import build_trainertokenizer = authored_tokenizer(FAMILIES["qwen3"])trainer = build_trainer(tokenizer, [SUPPORT_CONVERSATION])row = trainer.train_dataset[0]out = Path("support-model")trainer.model.save_pretrained(out)tokenizer.save_pretrained(out)Path(out, "trained_row.json").write_text(    json.dumps({"input_ids": row["input_ids"], "labels": row["labels"]}))for path in sorted(out.iterdir()):    print(path.name)

# check_support_model.pyimport jsonfrom pathlib import Pathfrom transformers import GenerationConfigfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.authoring import check_authored_modelfrom templatestudio.render import load_tokenizermodel_dir = Path("support-model")tokenizer = load_tokenizer(str(model_dir))config = GenerationConfig.from_pretrained(model_dir)row = json.loads(Path(model_dir, "trained_row.json").read_text())report = check_authored_model(tokenizer, config, SUPPORT_CONVERSATION, SUPPORT_TEXT, row)for name, problems in report.items():    print(f"{name:8} {'ok' if not problems else problems}")print("passes" if not any(report.values()) else "FAILS")

python save_support_model.pypython check_support_model.py

chat_template.jinjaconfig.jsongeneration_config.jsonmodel.safetensorstokenizer.jsontokenizer_config.jsontrained_row.jsonstring   okmarkers  oktokens   okmask     oklabels   okstops    okpasses

# show_template_only_copy.pyimport jsonfrom pathlib import Pathfrom transformers import GenerationConfigfrom families import FAMILIESfrom support_data import SUPPORT_CONVERSATION, SUPPORT_TEXTfrom templatestudio.authoring import check_authored_model, install_templatefrom templatestudio.render import load_tokenizer# Someone copies the template and the weights, but loads the base tokenizer.model_dir = Path("support-model")template = Path(model_dir, "chat_template.jinja").read_text(encoding="utf-8")tokenizer = install_template(load_tokenizer(FAMILIES["qwen3"]), template)config = GenerationConfig.from_pretrained(model_dir)row = json.loads(Path(model_dir, "trained_row.json").read_text())report = check_authored_model(tokenizer, config, SUPPORT_CONVERSATION, SUPPORT_TEXT, row)for name, problems in report.items():    print(f"{name:8} {'ok' if not problems else len(problems)}", end="")    print("" if not problems else f" problem(s): {problems[0][:52]}")

python show_template_only_copy.py

string   okmarkers  4 problem(s): '<|system|>' is 5 tokens: ['<', '|', 'system', '|', tokens   3 problem(s): tokens differ at position 0 (served 78 ids, trained mask     2 problem(s): span 0 is 'Let me check.<|end|>\n', not 'Let me checlabels   2 problem(s): trained span ends at position 25 on ''stops    1 problem(s): '<|end|>' is 5 tokens, so it cannot be a stop ID

chat-templates-part1/├── support-model/             (written by step 13)├── trainer-out/               (created by SFTTrainer, empty)├── templatestudio/│   ├── __init__.py│   ├── messages.py            (unchanged since Part 7)│   ├── render.py              (unchanged since Part 6)│   ├── jinja_env.py           (Part 3, unchanged)│   ├── authoring.py           (new)│   └── ... multimodal.py, tools.py, reasoning.py, anatomy.py if built├── families.py                (TINY_MODEL appended)├── support_data.py            (new)├── broken_templates.py        (new)├── trainer_batch.py           (new)├── check_trainer_versions.py  (new)├── fetch_support_models.py    (new)├── show_training_format.py    (new)├── show_support_render.py     (new)├── show_string_check.py       (new)├── show_marker_split.py       (new)├── show_embedding_rows.py     (new)├── show_trainer_row.py        (new)├── show_token_check.py        (new)├── show_mask_check.py         (new)├── show_label_check.py        (new)├── show_stop_check.py         (new)├── show_pad_trap.py           (new)├── show_pad_stop_check.py     (new)├── save_support_model.py      (new)├── check_support_model.py     (new)├── show_template_only_copy.py (new)└── ... the scripts from Parts 1 to 7

# templatestudio/authoring.pyfrom __future__ import annotationsfrom collections.abc import Sequencefrom transformers import GenerationConfig, PreTrainedModel, PreTrainedTokenizerBasefrom templatestudio.jinja_env import render_template_stringfrom templatestudio.messages import Conversationfrom templatestudio.render import first_divergence, load_tokenizer, render_idsEND_OF_TURN = "<|end|>"MARKERS = ("<|system|>", "<|user|>", "<|assistant|>", END_OF_TURN)# Transcribed from the training format. The assistant's words and its <|end|># sit inside {% generation %}: the model writes them, so the loss covers them.# The role header comes from the prompt and the newline after <|end|> comes# from the template, so both stay outside.SUPPORT_TEMPLATE = (    "{% for message in messages %}"    "{{- '<|' + message['role'] + '|>\n' }}"    "{%- if message['role'] == 'assistant' %}"    "{% generation %}{{- message['content'] + '<|end|>' }}{% endgeneration %}"    "{{- '\n' }}"    "{%- else %}"    "{{- message['content'] + '<|end|>\n' }}"    "{%- endif %}"    "{%- endfor %}"    "{%- if add_generation_prompt %}{{- '<|assistant|>\n' }}{%- endif %}")def install_template(    tokenizer: PreTrainedTokenizerBase, template_source: str) -> PreTrainedTokenizerBase:    """Make template_source the tokenizer's chat template.    apply_chat_template uses it from now on, and save_pretrained writes it to    chat_template.jinja beside the tokenizer files.    """    tokenizer.chat_template = template_source    return tokenizerdef check_string_roundtrip(    template_source: str, conversation: Conversation, trained_text: str) -> list[str]:    """Compare the template's render with the exact text the model trained on."""    served = render_template_string(template_source, conversation)    at = first_divergence(served, trained_text)    if at is None:        return []    return [        f"text differs at character {at}: trained "        f"{trained_text[at:at + 12]!r}, served {served[at:at + 12]!r}"    ]def check_marker_tokens(    tokenizer: PreTrainedTokenizerBase, markers: Sequence[str] = MARKERS) -> list[str]:    """Report every marker that is not exactly one token in the vocabulary."""    problems = []    for marker in markers:        ids = tokenizer.encode(marker, add_special_tokens=False)        if len(ids) != 1:            pieces = tokenizer.convert_ids_to_tokens(ids)            problems.append(f"{marker!r} is {len(ids)} tokens: {pieces}")    return problemsdef add_markers(    tokenizer: PreTrainedTokenizerBase, markers: Sequence[str] = MARKERS) -> int:    """Add the markers as special tokens, so each encodes to one ID."""    return tokenizer.add_tokens(list(markers), special_tokens=True)def authored_tokenizer(model_id: str) -> PreTrainedTokenizerBase:    """Load a base tokenizer, add the markers, and install the template."""    tokenizer = load_tokenizer(model_id)    add_markers(tokenizer)    return install_template(tokenizer, SUPPORT_TEMPLATE)def ensure_embedding_rows(    model: PreTrainedModel, tokenizer: PreTrainedTokenizerBase) -> int:    """Grow the embedding matrix only if a token ID would fall outside it.    Returns the number of rows. Never shrinks: some models ship spare rows.    """    rows = model.get_input_embeddings().weight.shape[0]    if len(tokenizer) > rows:        model.resize_token_embeddings(len(tokenizer))        rows = len(tokenizer)    return rowsdef check_token_roundtrip(    tokenizer: PreTrainedTokenizerBase,    conversation: Conversation,    trained_ids: Sequence[int],) -> list[str]:    """Compare the served template's token IDs with the IDs the trainer used:    the whole conversation, then the generation prompt before each answer."""    served = render_ids(tokenizer, conversation, add_generation_prompt=False)    trained = [int(i) for i in trained_ids]    at = first_divergence(served, trained)    if at is not None:        window = slice(max(at - 2, 0), at + 3)        return [            f"tokens differ at position {at} "            f"(served {len(served)} ids, trained {len(trained)})",            f"served:  {tokenizer.convert_ids_to_tokens(served[window])}",            f"trained: {tokenizer.convert_ids_to_tokens(trained[window])}",        ]    problems = []    for k, message in enumerate(conversation):        if message["role"] != "assistant":            continue        prompt = render_ids(tokenizer, conversation[:k], add_generation_prompt=True)        at = first_divergence(prompt, trained[: len(prompt)])        if at is not None:            problems.append(                f"generation prompt before message {k} differs at position {at}: "                f"{tokenizer.convert_ids_to_tokens(prompt[at:at + 2])}"            )    return problemsdef check_assistant_mask(    tokenizer: PreTrainedTokenizerBase,    conversation: Conversation,    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check that each masked span is one assistant turn plus end_of_turn."""    encoded = tokenizer.apply_chat_template(        conversation, return_assistant_tokens_mask=True    )    ids, mask = encoded["input_ids"], encoded["assistant_masks"]    spans: list[list[int]] = []    current: list[int] = []    for token_id, flag in zip(ids, mask):        if flag:            current.append(token_id)        elif current:            spans.append(current)            current = []    if current:        spans.append(current)    turns = [m["content"] for m in conversation if m["role"] == "assistant"]    if not turns:        return ["the conversation has no assistant turn to mask"]    if not spans:        return ["the mask is all zeros: the template has no {% generation %}"]    if len(spans) != len(turns):        return [f"{len(spans)} masked spans for {len(turns)} assistant turns"]    problems = []    for i, (span, content) in enumerate(zip(spans, turns)):        expected = tokenizer.encode(content + end_of_turn, add_special_tokens=False)        if span != expected:            problems.append(                f"span {i} is {tokenizer.decode(span)!r}, "                f"not {content + end_of_turn!r}"            )    return problemsdef check_trained_spans(    tokenizer: PreTrainedTokenizerBase,    labels: Sequence[int],    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check one row of real labels: every trained run ends on end_of_turn."""    end_id = tokenizer.convert_tokens_to_ids(end_of_turn)    problems = []    for i, label in enumerate(labels):        trained = label != -100        last_of_run = trained and (i + 1 == len(labels) or labels[i + 1] == -100)        if last_of_run and label != end_id:            text = tokenizer.decode([label])            problems.append(f"trained span ends at position {i} on {text!r}")    if all(label == -100 for label in labels):        problems.append("no position is trained")    return problemsdef check_stop_alignment(    tokenizer: PreTrainedTokenizerBase,    generation_config: GenerationConfig,    end_of_turn: str = END_OF_TURN,) -> list[str]:    """Check that generation stops on end_of_turn, and that padding cannot    mask it out of the loss."""    ids = tokenizer.encode(end_of_turn, add_special_tokens=False)    if len(ids) != 1:        return [f"{end_of_turn!r} is {len(ids)} tokens, so it cannot be a stop ID"]    end_id = ids[0]    stops = generation_config.eos_token_id    stops = [stops] if isinstance(stops, int) else list(stops or [])    problems = []    if end_id not in stops:        problems.append(            f"{end_of_turn!r} (id {end_id}) is not in eos_token_id {stops}"        )    if tokenizer.pad_token_id == end_id:        problems.append(            f"pad_token is {end_of_turn!r}: a pad-ID collator masks it from the loss"        )    return problemsdef check_authored_model(    tokenizer: PreTrainedTokenizerBase,    generation_config: GenerationConfig,    conversation: Conversation,    trained_text: str,    trained_row: dict[str, list[int]],) -> dict[str, list[str]]:    """Run every check against one saved model. Empty lists mean it passes."""    template = tokenizer.chat_template    return {        "string": check_string_roundtrip(template, conversation, trained_text),        "markers": check_marker_tokens(tokenizer),        "tokens": check_token_roundtrip(            tokenizer, conversation, trained_row["input_ids"]        ),        "mask": check_assistant_mask(tokenizer, conversation),        "labels": check_trained_spans(tokenizer, trained_row["labels"]),        "stops": check_stop_alignment(tokenizer, generation_config),    }

# support_data.py# One training example for a support model, as messages and as the exact text# the fine-tuning data was formatted into. Every turn ends with <|end|>.SUPPORT_CONVERSATION = [    {"role": "system", "content": "You are a support agent."},    {"role": "user", "content": "Where is my order?"},    {"role": "assistant", "content": "Let me check."},    {"role": "user", "content": "It is order 1042."},    {"role": "assistant", "content": "Order 1042 ships today."},]SUPPORT_TEXT = (    "<|system|>\nYou are a support agent.<|end|>\n"    "<|user|>\nWhere is my order?<|end|>\n"    "<|assistant|>\nLet me check.<|end|>\n"    "<|user|>\nIt is order 1042.<|end|>\n"    "<|assistant|>\nOrder 1042 ships today.<|end|>\n")

# trainer_batch.pyfrom datasets import Dataset, disable_progress_barsfrom transformers import AutoModelForCausalLM, PreTrainedTokenizerBasefrom transformers.utils import logging as transformers_loggingfrom trl import SFTConfig, SFTTrainerfrom families import TINY_MODELfrom templatestudio.authoring import END_OF_TURN, ensure_embedding_rowsdisable_progress_bars()transformers_logging.disable_progress_bar()def build_trainer(    tokenizer: PreTrainedTokenizerBase, conversations: list[list[dict]]) -> SFTTrainer:    """Build an SFTTrainer the way a fine-tune would, without training."""    model = AutoModelForCausalLM.from_pretrained(TINY_MODEL)    ensure_embedding_rows(model, tokenizer)    config = SFTConfig(        output_dir="trainer-out",        assistant_only_loss=True,        eos_token=END_OF_TURN,        use_cpu=True,        bf16=False,        report_to="none",    )    dataset = Dataset.from_list([{"messages": c} for c in conversations])    return SFTTrainer(        model=model, args=config, train_dataset=dataset, processing_class=tokenizer    )

# broken_templates.py# Copies of SUPPORT_TEMPLATE with one mistake each, for the failing cases.from templatestudio.authoring import SUPPORT_TEMPLATE# The serving copy someone edited: one extra newline after every role header.DRIFTED = SUPPORT_TEMPLATE.replace("'|>\n'", "'|>\n\n'")# The generation prompt writes one more newline than the trained turns have.GEN_PROMPT_DRIFT = SUPPORT_TEMPLATE.replace(    "{{- '<|assistant|>\n' }}{%- endif %}",    "{{- '<|assistant|>\n\n' }}{%- endif %}",)# <|end|> moved out of the generation block: the model never learns to stop.END_OUTSIDE = SUPPORT_TEMPLATE.replace(    "message['content'] + '<|end|>' }}{% endgeneration %}",    "message['content'] }}{% endgeneration %}{{- '<|end|>' }}",)

# Part 8: a 2-layer test model from the TRL team that uses Qwen3's tokenizer.TINY_MODEL = "trl-internal-testing/tiny-Qwen3ForCausalLM"