Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

8.6 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""Completion-only masking for CUDA and MLX: explicit dataset markers if requested, else template
detection with manual markers as fallback; gpt-oss must use detection, not markers"""

from .iterable import is_streaming_dataset
from .model_mappings import (
    MODEL_TO_TEMPLATE_MAPPER,
    TEMPLATE_TO_RESPONSES_MAPPER,
    is_gpt_oss_model_name,
)


def lookup_manual_markers(model_name):
    """Return (template_name, instruction_part, response_part) from the
    manual template table, with None parts when the model or template is
    not mapped."""
    template = MODEL_TO_TEMPLATE_MAPPER.get((model_name or "").lower())
    markers = TEMPLATE_TO_RESPONSES_MAPPER.get(template) if template else None
    if markers:
        return template, markers["instruction"], markers["response"]
    return template, None, None


def count_truncated_drops(rows, kept_rows, max_length):
    """Rows masking dropped (rows minus kept_rows) that had been truncated at max_length."""
    from collections import Counter

    kept = Counter(map(tuple, kept_rows))
    cut = 0
    for row in rows:
        key = tuple(row)
        if kept[key]:
            kept[key] -= 1
        elif len(row) >= max_length:
            cut += 1
    return cut


def truncated_drop_cause(cut, dropped, max_length):
    """Error text when dropped rows reached the context length, or None when none did."""
    if not cut:
        return None
    # Reaching the cap suggests truncation but does not prove it, so the template advice stays as the fallback.
    cause = (
        f"{cut} of them reach the context length ({max_length} tokens), so truncation most likely "
        f"cut off their response: raise the context length or shorten those rows."
    )
    if dropped > cut:
        cause += (
            f" For the other {dropped - cut}, this model's response template was not found, so "
            f"'Train on completions' should be turned off for this dataset."
        )
    else:
        cause += (
            " If they are not that long, this model's response template was not found, so "
            "'Train on completions' should be turned off for this dataset."
        )
    return cause


def _mask_tool_responses(trainer, start_id, end_id, turn_id):
    def mask(batch):
        all_labels = []
        for input_ids, labels in zip(batch["input_ids"], batch["labels"]):
            if start_id in input_ids:
                input_ids, labels = list(input_ids), list(labels)
                starts = [i for i, token in enumerate(input_ids) if token == start_id]
                for start, limit in zip(starts, starts[1:] + [len(input_ids)]):
                    span = input_ids[start + 1 : limit]
                    # An unanswered tool call has no closing marker; its span ends at the next turn.
                    if end_id in span:
                        stop = span.index(end_id) + 1
                    else:
                        stop = span.index(turn_id) if turn_id in span else len(span)
                    labels[start + 1 : start + 1 + stop] = [-100] * stop
            all_labels.append(labels)
        return {"labels": all_labels}

    for name in ("train_dataset", "eval_dataset"):
        dataset = getattr(trainer, name, None)
        columns = (
            next(iter(dataset), {})
            if is_streaming_dataset(dataset)
            else getattr(dataset, "column_names", None)
        )
        if "labels" in (columns or ()):
            setattr(trainer, name, dataset.map(mask, batched = True))
    return trainer


def apply_completion_masking(
    trainer,
    model_name,
    train_fn,
    num_proc = None,
    notify = None,
    detect_fn = None,
    dataset_template = None,
):
    """Only marker detection failures use the table fallback; masking errors propagate so a real failure stops the run instead of silently changing the objective."""
    if notify is None:
        notify = lambda level, message: None
    kwargs = {}
    if num_proc is not None:
        kwargs["num_proc"] = num_proc

    processor = getattr(trainer, "processing_class", None) or getattr(trainer, "tokenizer", None)
    if type(processor).__name__ == "TokenizerWrapper":
        wrapped = getattr(processor, "_tokenizer", None)
        if wrapped is not None:
            processor = wrapped
    inner = getattr(processor, "tokenizer", processor)

    # Gemma 4 puts tool results inside the model turn; MLX labels its batches inside train_fn, out of reach here.
    vocab = inner.get_added_vocab() if hasattr(inner, "get_added_vocab") else {}
    tool_response = (vocab.get("<|tool_response>"), vocab.get("<tool_response|>"))
    if None not in tool_response and type(trainer).__name__ != "MLXTrainer":
        mask_responses = train_fn

        def train_fn(trainer, **kwargs):
            return _mask_tool_responses(
                mask_responses(trainer, **kwargs), *tool_response, vocab.get("<|turn>")
            )

    if dataset_template is not None:
        markers = TEMPLATE_TO_RESPONSES_MAPPER.get(dataset_template)
        if not markers:
            raise ValueError(f"Unknown completion masking template: {dataset_template}")
        has_preset_markers = hasattr(inner, "_unsloth_input_part") and hasattr(
            inner, "_unsloth_output_part"
        )
        if has_preset_markers:
            previous_instruction = inner._unsloth_input_part
            previous_response = inner._unsloth_output_part
            inner._unsloth_input_part = markers["instruction"]
            inner._unsloth_output_part = markers["response"]
            try:
                trainer = train_fn(trainer, **kwargs)
            finally:
                inner._unsloth_input_part = previous_instruction
                inner._unsloth_output_part = previous_response
        else:
            trainer = train_fn(
                trainer,
                instruction_part = markers["instruction"],
                response_part = markers["response"],
                **kwargs,
            )
        notify(
            "info",
            f"Train on responses only configured with dataset template markers ({dataset_template})",
        )
        return trainer, True

    template, instruction_part, response_part = lookup_manual_markers(model_name)

    # gpt-oss goes auto-first: some checkpoints ship a channel-less template, so manual markers match nothing and zero tokens train.
    if is_gpt_oss_model_name(model_name) and not (instruction_part and response_part):
        markers = TEMPLATE_TO_RESPONSES_MAPPER.get("gpt-oss")
        if markers:
            template = "gpt-oss"
            instruction_part = markers["instruction"]
            response_part = markers["response"]
    if hasattr(inner, "_unsloth_input_part") and hasattr(inner, "_unsloth_output_part"):
        # Markers preset on the tokenizer; zoo reuses them on a bare call.
        trainer = train_fn(trainer, **kwargs)
        notify(
            "info",
            "Train on responses only configured via tokenizer preset markers",
        )
        return trainer, True
    auto_instruction = auto_response = None
    try:
        if detect_fn is None:
            # MLX train_fn needs unsloth_zoo.dataset_utils anyway, so torch import is fine.
            from unsloth_zoo.dataset_utils import get_chat_template_parts as detect_fn
        auto_instruction, auto_response = detect_fn(processor)
    except Exception as e:
        notify(
            "warning",
            f"Auto-detection of instruction/response markers failed ({e}); "
            f"falling back to the template table",
        )
    if auto_instruction and auto_response:
        trainer = train_fn(
            trainer,
            instruction_part = auto_instruction,
            response_part = auto_response,
            **kwargs,
        )
        notify(
            "info",
            "Train on responses only configured via chat template auto-detection",
        )
        return trainer, True

    if instruction_part and response_part:
        trainer = train_fn(
            trainer,
            instruction_part = instruction_part,
            response_part = response_part,
            **kwargs,
        )
        notify(
            "info",
            f"Train on responses only configured with template table markers ({template})",
        )
        return trainer, True

    notify(
        "warning",
        f"'Train on completions' could not be applied for {model_name}: no "
        f"auto-detected or mapped instruction/response markers. Training "
        f"will run on full sequences (prompts included).",
    )
    return trainer, False