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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Studio: truncate completion_mask / assistant_masks with pre-tokenized input_ids (#14884)
Daniel Han93c5b324970f
diff --git a/studio/backend/core/training/trainer.py b/studio/backend/core/training/trainer.pyindex 1af08085a11..3c2f83a6f45 100644--- a/studio/backend/core/training/trainer.py+++ b/studio/backend/core/training/trainer.py@@ -89,6 +89,7 @@ from utils.datasets.pretokenized import (PRETOKENIZED_FORMAT,has_custom_labels,prepare_pretokenized_dataset,+ resolve_completion_only_loss,)from utils.datasets.raw_text import prepare_raw_text_dataset, resolve_column_namesfrom utils.paths import (@@ -4955,12 +4956,23 @@ class UnslothTrainer:except Exception:vocab_size = Nonemax_seq = training_args.get("max_seq_length", 2048)+ # completion_mask is applied (so checked) only under completion_only_loss, which TRL resolves+ # once from the train split when unset and uses for eval too.+ completion_only = resolve_completion_only_loss(+ dataset["dataset"], config_args.get("completion_only_loss")+ )dataset["dataset"] = prepare_pretokenized_dataset(- dataset["dataset"], max_seq_length = max_seq, vocab_size = vocab_size+ dataset["dataset"],+ max_seq_length = max_seq,+ vocab_size = vocab_size,+ completion_only_loss = completion_only,)if eval_dataset is not None:eval_dataset = prepare_pretokenized_dataset(- eval_dataset, max_seq_length = max_seq, vocab_size = vocab_size+ eval_dataset,+ max_seq_length = max_seq,+ vocab_size = vocab_size,+ completion_only_loss = completion_only,)# Plain-text single-pass runs tokenize in the DataLoader workers instead of a blocking .map(); everythingdiff --git a/studio/backend/tests/test_pretokenized_dataset.py b/studio/backend/tests/test_pretokenized_dataset.pyindex 2e01c0ab624..c78006739c0 100644--- a/studio/backend/tests/test_pretokenized_dataset.py+++ b/studio/backend/tests/test_pretokenized_dataset.py@@ -143,6 +143,235 @@ def test_prepare_rejects_labels_of_another_length():prepare_pretokenized_dataset(ds, max_seq_length = 2048, vocab_size = 100)[email protected]("mask", ["completion_mask", "assistant_masks"])+def test_prepare_truncates_loss_masks_with_the_ids(mask):+ # TRL applies these masks to the labels: left at full length they fail on the first step.+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3, 4, 5, 6]], mask: [[0, 0, 1, 1, 1, 1]]})+ out = prepare_pretokenized_dataset(+ ds, max_seq_length = 4, vocab_size = 100, completion_only_loss = True+ )+ assert out[0]["input_ids"] == [1, 2, 3, 4]+ assert out[0][mask] == [0, 0, 1, 1]++[email protected]("mask", ["completion_mask", "assistant_masks"])+def test_prepare_rejects_loss_masks_of_another_length(mask):+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3]], mask: [[0, 1]]})+ with pytest.raises(ValueError, match = f"'{mask}' must have the same length"):+ prepare_pretokenized_dataset(+ ds, max_seq_length = 2048, vocab_size = 100, completion_only_loss = True+ )+++def test_prepare_rejects_a_row_without_its_loss_mask():+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3], [4, 5]], "completion_mask": [[0, 1, 1], None]})+ with pytest.raises(ValueError, match = "'completion_mask' must have the same length"):+ prepare_pretokenized_dataset(+ ds, max_seq_length = 2048, vocab_size = 100, completion_only_loss = True+ )+++def test_prepare_ignores_unused_masks_next_to_user_labels():+ # With labels the masks are not used, so a stale mask column keeps training as before.+ ds = Dataset.from_dict(+ {"input_ids": [[1, 2, 3]], "labels": [[-100, 2, 3]], "completion_mask": [[0, 1]]}+ )+ assert prepare_pretokenized_dataset(ds, max_seq_length = 2048, vocab_size = 100) is ds+++def test_prepare_leaves_unused_null_masks_next_to_labels_alone():+ ds = Dataset.from_dict(+ {+ "input_ids": [[1, 2, 3, 4, 5, 6]],+ "labels": [[1, 2, 3, 4, 5, 6]],+ "completion_mask": [None],+ }+ )+ out = prepare_pretokenized_dataset(ds, max_seq_length = 4, vocab_size = 100)+ assert out[0]["input_ids"] == [1, 2, 3, 4] and out[0]["labels"] == [1, 2, 3, 4]+ assert out[0]["completion_mask"] is None++[email protected]("streamed", [False, True])[email protected]("mask", ["assistant_masks", "completion_mask"])+def test_prepare_truncates_masks_next_to_labels_when_the_collator_applies_them(+ monkeypatch, mask, streamed+):+ # TRL < 1.7's collator applies these masks on top of the row's labels: a 6-token mask beside+ # 4-token labels fails the boolean index on the first step.+ import utils.datasets.pretokenized as pretokenized++ monkeypatch.setattr(pretokenized, "_collator_masks_user_labels", lambda: True, raising = False)+ ds = Dataset.from_dict(+ {+ "input_ids": [[1, 2, 3, 4, 5, 6]],+ "labels": [[-100, 2, 3, 4, 5, 6]],+ mask: [[0, 1, 1, 1, 1, 1]],+ }+ )+ if streamed:+ ds = ds.to_iterable_dataset()+ out = list(+ prepare_pretokenized_dataset(+ ds, max_seq_length = 4, vocab_size = 100, completion_only_loss = True+ )+ )+ assert out[0]["labels"] == [-100, 2, 3, 4] and out[0][mask] == [0, 1, 1, 1]+ bad = Dataset.from_dict({"input_ids": [[1, 2, 3]], "labels": [[1, 2, 3]], mask: [[0, 1]]})+ with pytest.raises(ValueError, match = f"'{mask}' must have the same length"):+ prepare_pretokenized_dataset(+ bad, max_seq_length = 2048, vocab_size = 100, completion_only_loss = True+ )+++def test_prepare_leaves_masks_next_to_labels_alone_when_the_collator_ignores_them(monkeypatch):+ # TRL 1.7+ trains on the labels as given and never reads the masks beside them.+ import utils.datasets.pretokenized as pretokenized++ monkeypatch.setattr(pretokenized, "_collator_masks_user_labels", lambda: False, raising = False)+ ds = Dataset.from_dict(+ {+ "input_ids": [[1, 2, 3, 4, 5, 6]],+ "labels": [[1, 2, 3, 4, 5, 6]],+ "assistant_masks": [[0, 1]],+ }+ )+ out = prepare_pretokenized_dataset(+ ds, max_seq_length = 4, vocab_size = 100, completion_only_loss = True+ )+ assert out[0]["labels"] == [1, 2, 3, 4] and out[0]["assistant_masks"] == [0, 1]+++def test_prepare_checks_streamed_loss_masks():+ ds = Dataset.from_dict(+ {"input_ids": [[1, 2, 3, 4, 5, 6]], "completion_mask": [[0, 1]]}+ ).to_iterable_dataset()+ out = prepare_pretokenized_dataset(+ ds, max_seq_length = 4, vocab_size = 100, completion_only_loss = True+ )+ with pytest.raises(ValueError, match = "'completion_mask' must have the same length"):+ list(out)++[email protected]("completion_only_loss", [None, False])[email protected]("streamed", [False, True])+def test_prepare_ignores_completion_masks_the_trainer_will_not_apply(+ completion_only_loss, streamed+):+ # Studio leaves completion_only_loss unset and TRL resolves it False for input_ids rows, so+ # TRL never reads completion_mask: a stale one must not reject or alter a dataset that trains.+ ds = Dataset.from_dict(+ {"input_ids": [[1, 2, 3, 4, 5, 6], [7, 8]], "completion_mask": [[0, 1], None]}+ )+ if streamed:+ ds = ds.to_iterable_dataset()+ out = prepare_pretokenized_dataset(+ ds, max_seq_length = 4, vocab_size = 100, completion_only_loss = completion_only_loss+ )+ rows = list(out)+ assert [r["input_ids"] for r in rows] == [[1, 2, 3, 4], [7, 8]]+ assert [r["completion_mask"] for r in rows] == [[0, 1], None]+++def test_prepare_still_checks_assistant_masks_without_completion_only_loss():+ # TRL applies assistant_masks on presence alone.+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3]], "assistant_masks": [[0, 1]]})+ with pytest.raises(ValueError, match = "'assistant_masks' must have the same length"):+ prepare_pretokenized_dataset(ds, max_seq_length = 2048, vocab_size = 100)+++def test_prepare_keeps_hidden_columns_hidden():+ # A labels column hidden by set_format(columns = ...) is not the user's labels, and the+ # truncation restores the format so it stays hidden.+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3, 4, 5, 6]], "labels": [[1, 2, 3, 4, 5, 6]]})+ ds.set_format(columns = ["input_ids"], output_all_columns = False)+ assert not has_custom_labels(ds)+ out = prepare_pretokenized_dataset(ds, max_seq_length = 4, vocab_size = 100)+ assert list(out[0]) == ["input_ids"]+ assert out[0]["input_ids"] == [1, 2, 3, 4]+++def test_prepare_checks_and_truncates_masks_hidden_by_the_format():+ # TRL 0.22-0.26 re-exposes every column via with_transform, and 1.7+ builds labels with+ # map() over dataset.column_names, which ignore set_format: a hidden mask is still applied.+ bad = Dataset.from_dict({"input_ids": [[1, 2, 3]], "assistant_masks": [[0, 1]]})+ bad.set_format(columns = ["input_ids"], output_all_columns = False)+ with pytest.raises(ValueError, match = "'assistant_masks' must have the same length"):+ prepare_pretokenized_dataset(bad, max_seq_length = 2048, vocab_size = 100)+ ok = Dataset.from_dict(+ {"input_ids": [[1, 2, 3, 4, 5, 6]], "assistant_masks": [[0, 1, 1, 1, 1, 1]]}+ )+ ok.set_format(columns = ["input_ids"], output_all_columns = False)+ out = prepare_pretokenized_dataset(ok, max_seq_length = 4, vocab_size = 100)+ assert list(out[0]) == ["input_ids"]+ assert out.data.column("assistant_masks").to_pylist() == [[0, 1, 1, 1]]+++def test_completion_only_loss_resolves_from_the_train_split():+ # TRL resolves an unset completion_only_loss once, from the train split, and applies it to+ # eval too: an input_ids eval split's completion_mask is then applied, so it is checked.+ src = (_BACKEND_ROOT / "core" / "training" / "trainer.py").read_text()+ assert 'resolve_completion_only_loss(\n dataset["dataset"]' in src+ from utils.datasets.pretokenized import resolve_completion_only_loss++ train = Dataset.from_dict({"prompt": ["a"], "completion": ["b"], "input_ids": [[1, 2]]})+ evals = Dataset.from_dict({"input_ids": [[1, 2, 3]], "completion_mask": [[0, 1]]})+ assert resolve_completion_only_loss(train) is True+ assert resolve_completion_only_loss(evals) is False+ assert resolve_completion_only_loss(evals, True) is True+ with pytest.raises(ValueError, match = "'completion_mask' must have the same length"):+ prepare_pretokenized_dataset(+ evals,+ max_seq_length = 2048,+ vocab_size = 100,+ completion_only_loss = resolve_completion_only_loss(train),+ )+++def test_prepare_checks_masks_the_format_still_outputs():+ ds = Dataset.from_dict({"input_ids": [[1, 2, 3]], "assistant_masks": [[0, 1]]})+ ds.set_format(columns = ["input_ids"], output_all_columns = True)+ with pytest.raises(ValueError, match = "'assistant_masks' must have the same length"):+ prepare_pretokenized_dataset(ds, max_seq_length = 2048, vocab_size = 100)++[email protected]("mask", [[None, None], [1, 0]])+def test_prepare_rejects_non_list_masks_with_the_mask_error(mask):+ # An all-null or scalar mask column has no list kernel in Arrow: still the mask error.+ ds = Dataset.from_dict({"input_ids": [[1, 2], [3]], "assistant_masks": mask})+ with pytest.raises(ValueError, match = "'assistant_masks' must have the same length"):+ prepare_pretokenized_dataset(ds, max_seq_length = 2048, vocab_size = 100)++[email protected]("fmt", [None, "numpy", "torch"])[email protected]("mask", [0, 1.0, True])+def test_prepare_rejects_streamed_scalar_masks_with_the_mask_error(mask, fmt, monkeypatch):+ # Streamed rows skip the Arrow type check: a scalar mask must not surface as len()'s TypeError.+ monkeypatch.setattr(+ "datasets.config.TORCHVISION_AVAILABLE", False+ ) # torchvision without VideoReader+ ds = Dataset.from_dict(+ {"input_ids": [[1, 2, 3]], "assistant_masks": [mask]}+ ).to_iterable_dataset()+ if fmt:+ ds = ds.with_format(fmt)+ out = prepare_pretokenized_dataset(ds, max_seq_length = 2, vocab_size = 100)+ with pytest.raises(ValueError, match = "'assistant_masks' must have the same length"):+ list(out)++[email protected]("fmt", ["numpy", "torch"])+def test_prepare_truncates_streamed_array_masks(fmt, monkeypatch):+ monkeypatch.setattr("datasets.config.TORCHVISION_AVAILABLE", False)+ ds = (+ Dataset.from_dict({"input_ids": [[1, 2, 3]], "assistant_masks": [[0, 1, 1]]})+ .to_iterable_dataset()+ .with_format(fmt)+ )+ rows = list(prepare_pretokenized_dataset(ds, max_seq_length = 2, vocab_size = 100))+ assert [list(map(int, r["assistant_masks"])) for r in rows] == [[0, 1]]++def test_only_user_labels_turn_off_response_masking():assert has_custom_labels(_pretokenized(with_labels = True))assert not has_custom_labels(_pretokenized(with_labels = False))diff --git a/studio/backend/utils/datasets/pretokenized.py b/studio/backend/utils/datasets/pretokenized.pyindex 5793a4f31b4..7bc79729983 100644--- a/studio/backend/utils/datasets/pretokenized.py+++ b/studio/backend/utils/datasets/pretokenized.py@@ -4,7 +4,53 @@"""Pre-tokenized text datasets: rows that already hold ``input_ids`` (optionally ``attention_mask`` and ``labels``). They train as-is, without a chat template; user ``labels`` are the objective, so response masking applies only to rows without them. Only datasets no other format matched are claimed, so every dataset that trained before keeps its route."""PRETOKENIZED_FORMAT = "pretokenized"-_TOKEN_COLUMNS = ("input_ids", "attention_mask", "labels", "token_type_ids")+_TOKEN_COLUMNS = (+ "input_ids",+ "attention_mask",+ "labels",+ "token_type_ids",+ "completion_mask",+ "assistant_masks",+)+# Per-token masks TRL applies to the labels when a row has none of its own: a missing value or a+# length other than input_ids' fails mid-training.+_MASK_COLUMNS = ("completion_mask", "assistant_masks")+++def _collator_masks_user_labels() -> bool:+ """TRL < 1.7's collator applies the masks on top of a row's own labels; 1.7+ uses the labels as they are."""+ try:+ import trl+ from packaging.version import Version+ return Version(trl.__version__) < Version("1.7.0")+ except Exception:+ return True+++def _checked_masks(columns, completion_only_loss = None) -> tuple:+ """Masks the trainer will apply, the only ones checked and truncated.++ TRL applies `assistant_masks` on presence but `completion_mask` only under+ `completion_only_loss`, which, left unset, it resolves from the dataset shape (prompt plus+ completion columns). Beside user labels the masks are applied only by TRL < 1.7's collator.+ """+ if "labels" in columns and not _collator_masks_user_labels():+ return ()+ if completion_only_loss is None:+ completion_only_loss = "prompt" in columns and "completion" in columns+ return tuple(+ c+ for c in _MASK_COLUMNS+ if c in columns and (completion_only_loss or c != "completion_mask")+ )+++def _mask_error(name):+ return ValueError(+ f"Pre-tokenized dataset: '{name}' must have the same length as 'input_ids' in every row."+ )++_SAMPLE_ROWS = 20@@ -34,27 +80,62 @@ def is_pretokenized_dataset(dataset) -> bool:def _column_names(dataset) -> list[str]:+ """Columns the trainer's rows expose: a map-style ``set_format(columns = ...)`` hides the rest."""names = getattr(dataset, "column_names", None)if names:+ fmt = getattr(dataset, "format", None)+ if (+ isinstance(fmt, dict)+ and fmt.get("columns") is not None+ and not fmt.get("output_all_columns")+ ):+ return [c for c in names if c in fmt["columns"]]return list(names)return list(next(iter(dataset)).keys())+def resolve_completion_only_loss(train_dataset, completion_only_loss = None) -> bool:+ """TRL resolves an unset `completion_only_loss` once, from the train split's first row, for every split."""+ if completion_only_loss is not None:+ return completion_only_loss+ names = _column_names(train_dataset)+ return "prompt" in names and "completion" in names++def has_custom_labels(dataset) -> bool:return "labels" in _column_names(dataset)-def _check_arrow_table(table, max_seq_length, vocab_size) -> bool:+def _check_arrow_table(+ table,+ max_seq_length,+ vocab_size,+ masks = (),+ labels = True,+) -> bool:+ import pyarrow as paimport pyarrow.compute as pcids = table.column("input_ids")lengths = pc.list_value_length(ids)- if "labels" in table.column_names:- labels = table.column("labels")- if not pc.all(pc.equal(lengths, pc.list_value_length(labels))).as_py():+ if labels and "labels" in table.column_names:+ if not pc.all(pc.equal(lengths, pc.list_value_length(table.column("labels")))).as_py():raise ValueError("Pre-tokenized dataset: 'labels' must have the same length as 'input_ids' in every row.")+ for name in masks:+ # An all-null or scalar column has no list kernel: reject it with the same error.+ kind = table.column(name).type+ if not (+ pa.types.is_list(kind)+ or pa.types.is_large_list(kind)+ or pa.types.is_fixed_size_list(kind)+ ):+ raise _mask_error(name)+ same = pc.equal(lengths, pc.list_value_length(table.column(name)))+ # A row without the mask compares as null: that row fails too.+ if pc.all(same, skip_nulls = False).as_py() is not True:+ raise _mask_error(name)if vocab_size:flat = pc.list_flatten(ids)bounds = pc.min_max(flat).as_py() if len(flat) else {"min": 0, "max": 0}@@ -74,20 +155,39 @@ def prepare_pretokenized_dataset(*,max_seq_length,vocab_size = None,+ completion_only_loss = None,):"""Unsloth's SFT preparation passes tokenized rows through untouched: an over-long row would reach the model whole and an id past the embedding table is a device-side assert mid-run. Idempotent."""- columns = [c for c in _TOKEN_COLUMNS if c in _column_names(dataset)]+ names = _column_names(dataset)+ completion_only_loss = resolve_completion_only_loss(dataset, completion_only_loss)+ # Masks are checked even when set_format hides them: TRL 0.22-0.26 re-exposes every column through+ # with_transform, and 1.7+ reads dataset.column_names and builds labels with map(), which sees them all.+ masks = _checked_masks(getattr(dataset, "column_names", None) or names, completion_only_loss)+ # A mask the trainer will not apply is left as it is (it may not even be a list).+ columns = [c for c in _TOKEN_COLUMNS if (c in names and c not in _MASK_COLUMNS) or c in masks]table = getattr(dataset, "data", None)needs_truncation = Trueif table is not None and hasattr(table, "column"):# Covers the whole backing table, rows a select() hid included: a bad id there is still a bad dataset.- needs_truncation = _check_arrow_table(table, max_seq_length, vocab_size)+ needs_truncation = _check_arrow_table(+ table, max_seq_length, vocab_size, masks, labels = "labels" in names+ )if not needs_truncation or not max_seq_length:return datasetif table is None:def _truncate(batch):+ # Streamed rows never reach _check_arrow_table: check the masks before slicing.+ for name in masks:+ for ids, mask in zip(batch["input_ids"], batch[name]):+ # A scalar (None, int, numpy 0-d) has no len(): the mask error, as on the Arrow path.+ try:+ bad = ids is None or len(mask) != len(ids)+ except TypeError:+ bad = True+ if bad:+ raise _mask_error(name)return {c: [v[:max_seq_length] if v is not None else v for v in batch[c]] for c in columns}@@ -107,4 +207,11 @@ def prepare_pretokenized_dataset(out = dataset.with_format("arrow").map(_truncate_arrow, batched = True, desc = "Truncating pre-tokenized rows")- return out.with_format(dataset.format["type"])+ # Restore the whole format: the column selection too, so hidden columns stay hidden.+ fmt = dataset.format+ return out.with_format(+ fmt["type"],+ columns = fmt["columns"],+ output_all_columns = fmt["output_all_columns"],+ **(fmt["format_kwargs"] or {}),+ )