## Summary
SFT data becomes a list of named sources, in the same shape as the
pretraining sources of #4567. This gives SFT, pretraining and RL one way
to name and mix data. It replaces the earlier attempt in #3756.
```toml
[data]
seq_len = 4096
batch_size = 32
[[data.source]]
name = "chat" # required; keys progress/<name>/*
dataset = "org/sft-release"
subset = "chat" # also: split (default "train"), revision
weight = 3 # set on every source or on none
[[data.source]]
name = "reasoning"
dataset = "org/sft-release"
subset = "reasoning"
weight = 1
columns.messages = "conversation" # overrides single fields of data.columns
renderer.reasoning_effort = "high" # chat-template kwargs for this source's rows
```
- **Weights.** The rules are the same as in pretraining. A source's
share of the samples is its weight over the sum of the weights. Without
weights, a source's share is its share of all rows, so one epoch reads
every row once.
- **Order.** The sources take turns by due time (weighted fair queuing),
as in pretraining. Every stretch of samples holds the mixture. Each
source reads its rows in passes, each pass in its own seeded order.
- **Sharding and resume.** Every data rank walks the same draws and
keeps every `data_world_size`-th one. The dataloader state is the draw
count per source. A resume is exact, also on another number of GPUs. A
single-source checkpoint from `main` resumes on the same rows, and its
old progress counters fold into the source.
- **Per-source columns and renderer kwargs.** A source can override
single fields of `data.columns`. It can also set chat-template kwargs
for its rows, over `[renderer]` and under a row's `columns.renderer`
values.
- **Fake data.** `[data.fake]` replaces the sources with synthetic
tokens, as `[data.fake]` does in the RL trainer. It needs no renderer
and loads no dataset.
- **Metrics.** Each source logs `progress/<name>/num_samples` (draws
over all ranks) and `progress/<name>/epoch` (passes over its rows). With
several sources, each source also logs
`progress/<name>/ratio_{samples,tokens}`.
- **One source base.** Pretraining and SFT sources inherit `name` and
`weight` from `BaseSourceConfig` and check them with one `check_sources`
helper, so the rules for names and weights stay the same in both.
- **Validation.** `[val.data]` takes sources in the same shape. It
rejects `val.data.fake`.
- **Migration of checked-in configs.** All checked-in SFT configs,
examples, the docs and the model-factory skill reference use the new
shape.
## Breaking
- **Data config fields.** `data.name`, `data.revision`, `data.subsets`,
`data.splits`, `data.probabilities`, `data.stopping_strategy` and
`data.type` are removed. Migration: put each `(dataset, subset, split)`
in one `[[data.source]]` table with a `name`, and replace
`probabilities` with `weight`. For example, `name = "X"` plus `splits =
["math"]` becomes `[[data.source]] name = "math"`, `dataset = "X"`,
`split = "math"`.
- **Fake data config.** `[data] type = "fake"` becomes `[data.fake]`,
and `--data.type fake` becomes `--data.fake`.
- **Stopping strategy.** `stopping_strategy` has no replacement. Sources
repeat until `max_steps`, as in pretraining.
- **Metric names.** `progress/<subset>/ratio_{samples,tokens}` is now
keyed by source name.
- **Pretraining source names.** A pretraining source `name` can no
longer contain `/`, as for SFT sources: a slash nests the
`progress/<name>/*` metric keys. Migration: rename the source, e.g.
`web/en` to `web-en`.
- **Fake tokens.** Fake data has other token values. Sample `k` is now
drawn from a generator seeded by `(seed, k)`.
## Verification
All runs use Qwen3-0.6B, `seq_len = 1024` and `batch_size = 4`, on 1 GPU
unless noted.
| Run | Result |
|---|---|
| Single source (CI `reverse-text-sft/start.toml`): this branch vs
`main`, 20 steps | Identical `progress/num_tokens`, `num_samples` and
`epoch` at every step. The step-1 loss matches exactly; later losses
differ only in the third decimal (bf16). |
| Reverse-Text-SFT + R1-reverse-wikipedia at weights 3:1, 20 steps | The
realized sample ratio is 0.75. |
| The same mixture: 20 steps without a stop vs 10 steps, resume, 10
steps | Identical per-source samples and tokens at every step. |
| Natural shares, 2 GPUs × 2 dataloader workers, 10 steps | 1:1 split
(both datasets have 1000 rows), 0.21 passes over each source. |
| A `main` checkpoint at step 20, resumed on this branch to step 25 |
The same stream as a run of this branch resumed from step 20. Only the
source's progress keys are logged. |
| `configs/debug/fake/sft.toml` with `[data.fake]` | Trains 5 steps. No
dataset download or load. |
Unit tests: `tests/unit/train/sft`, `tests/unit/train/pretrain`,
`tests/unit/test_configs.py` and `tests/unit/train/test_val.py` pass
(474 passed; 32 skipped because quack's cross-entropy kernel does not
support this GPU).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Refactors the SFT data schema and sampling/resume path used by all
supervised runs; breaking config changes require migration, though
behavior is covered by new tests and CI configs.
>
> **Overview**
> **SFT data config** is aligned with pretraining: training uses one or
more `[[data.source]]` entries (named HF `dataset` / `subset` / `split`,
optional `weight`, per-source `columns` and `renderer` kwargs) instead
of `data.name`, subsets/splits, and `probabilities`. Synthetic runs
switch from `data.type = "fake"` to `[data.fake]`.
>
> **Loading and sampling** no longer interleave HF subsets in one
stream. Each source is an `HFSource` or `FakeSource`; `SFTDataset` mixes
them with weighted fair queuing, tracks per-source **draw counts** for
exact resume/sharding across ranks, and logs `progress/<name>/*`
metrics. Pretraining and SFT share `BaseSourceConfig` / `check_sources`;
source `name` values cannot contain `/`.
>
> Checked-in configs, docs, and unit tests are updated for the new
schema. **Breaking:** old `data.*` fields, `--data.type fake`,
interleave `stopping_strategy`, subset-keyed progress metrics, and
legacy fake-token sequencing all change as described in the PR.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
46e0a8d89b23b8c422b7a908921cc379c462248d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>