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.

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.py
index 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_names
from utils.paths import (
@@ -4955,12 +4956,23 @@ class UnslothTrainer:
except Exception:
vocab_size = None
max_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(); everything
diff --git a/studio/backend/tests/test_pretokenized_dataset.py b/studio/backend/tests/test_pretokenized_dataset.py
index 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.py
index 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 pa
import pyarrow.compute as pc
ids = 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 = True
if 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 dataset
if 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 {}),
+ )