dataset-curation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dataset Curation

数据集整理

This skill assumes

finetuning-method-selection

already routed here — the next step is preparing data, not choosing a method. What follows: format selection by target method, the template/packing mechanics behind the most common silent training failures, rules for mixing in synthetic data without collapse, and the dataset card that closes out Phase 2 before a run starts.

Input: raw examples (demonstrations, preference judgments, or task prompts) plus a routing decision from

finetuning-method-selection

. Output format: a formatted, packed, validated JSONL dataset plus a completed dataset card — the Phase 2 artifact

/finetune

checks before launching training.

本技能假定已通过

finetuning-method-selection

路由至此——下一步是准备数据，而非选择方法。后续内容包括：根据目标方法选择格式、最常见隐性训练失败背后的模板/打包机制、避免模型性能退化的合成数据混合规则，以及训练启动前完成第二阶段所需的数据集卡片。

输入： 原始示例（演示样本、偏好判断或任务提示），加上来自

finetuning-method-selection

的路由决策。 输出格式： 经过格式化、打包、验证的JSONL数据集，以及完整的数据集卡片——这是启动训练前

/finetune

检查的第二阶段产物。

Format Selection

格式选择

Method	Shape	Rows
SFT, single-turn	Instruct ( `instruction` / `response` or `prompt` / `completion` )	~1,000+ floor
SFT, multi-turn	Conversation / ChatML `messages` list	~1,000+ floor
DPO / ORPO	Preference pair ( `prompt` , `chosen` , `rejected` )	Method-dependent, see `preference-optimization`
KTO	Unpaired ( `prompt` , `completion` , `label` )	Method-dependent, see `preference-optimization`
GRPO / RLVR	Prompt-only ( `prompt` + verifier metadata)	Method-dependent, see `grpo-rlvr-training`

~1,000+ rows is the recommended floor for SFT, not a target. Below it, a handful of low-quality or duplicate examples can dominate the gradient; above it, quality over quantity — a smaller verified, deduplicated set beats a larger noisy one.

The ChatML shape, for orientation; the other four formats plus a ShareGPT conversion note live in

references/formats-and-templates.md

json

{"messages": [
  {"role": "user", "content": "..."},
  {"role": "assistant", "content": "..."}
]}

方法	数据结构	行数
SFT（单轮）	指令格式（ `instruction` / `response` 或 `prompt` / `completion` ）	最低约1000条
SFT（多轮）	对话 / ChatML `messages` 列表	最低约1000条
DPO / ORPO	偏好对（ `prompt` , `chosen` , `rejected` ）	取决于具体方法，详见 `preference-optimization`
KTO	无配对格式（ `prompt` , `completion` , `label` ）	取决于具体方法，详见 `preference-optimization`
GRPO / RLVR	仅提示格式（ `prompt` + 验证器元数据）	取决于具体方法，详见 `grpo-rlvr-training`

SFT的推荐最低行数为约1000条，而非目标值。低于该数量时，少量低质量或重复样本可能主导梯度更新；高于该数量时，质量优先于数量——经过验证、去重的小型数据集效果优于嘈杂的大型数据集。

以下为ChatML格式示例供参考；其余四种格式及ShareGPT转换说明可查看

references/formats-and-templates.md

：

json

{"messages": [
  {"role": "user", "content": "..."},
  {"role": "assistant", "content": "..."}
]}

Chat Templates and Loss Masking

聊天模板与损失掩码

Apply the target model's chat template before any concatenation or packing, never after — packing raw text and templating the packed blob afterward corrupts turn boundaries, landing role markers in the wrong place relative to each example.

Train on assistant responses only. Mask the loss (
```
-100
```
in the labels tensor) over system/user turns and the template's own role markers — only assistant-turn content tokens contribute to loss.
Template/tokenizer mismatches are a top silent failure mode. A model trained against one chat template but served or evaluated with a different one degrades without erroring. Verify the same template string used in training is applied at inference and eval time.
Keep the dataset in
messages
shape and let the trainer template and mask it (
```
assistant_only_loss=True
```
in current TRL) — pre-rendering to a flat text field destroys the turn boundaries masking needs. Full code sketch:
```
references/formats-and-templates.md
```
. Sanity-check before training — decode only unmasked positions; expect only assistant text:
python
```
keep = batch["labels"][0] != -100
print(tokenizer.decode(batch["input_ids"][0][keep]))
```

务必在任何拼接或打包操作之前应用目标模型的聊天模板，绝不可以在之后——先打包原始文本再为打包后的内容应用模板会破坏对话轮次边界，导致角色标记出现在每个样本的错误位置。

仅基于助手回复进行训练。 对系统/用户轮次以及模板自身的角色标记进行损失掩码（标签张量中设为
```
-100
```
）——只有助手轮次的内容 token 会参与损失计算。
模板与分词器不匹配是最主要的隐性失败模式。 使用某一聊天模板训练的模型，若在部署或评估时使用不同模板，性能会下降但不会报错。请确保训练时使用的模板字符串在推理和评估阶段保持一致。
保持数据集为
messages
结构，由训练器自动应用模板并添加掩码（当前TRL框架中设置
```
assistant_only_loss=True
```
）——预先渲染为纯文本字段会破坏掩码所需的对话轮次边界。完整代码示例可查看
```
references/formats-and-templates.md
```
。训练前请进行 sanity 检查——仅解码未掩码的位置，确认输出仅包含助手文本：
python
```
keep = batch["labels"][0] != -100
print(tokenizer.decode(batch["input_ids"][0][keep]))
```

Packing

序列打包

Without packing, 40–70% of compute is spent on padding — variable-length examples batched at a fixed sequence length waste the gap between each example's length and the batch's max. Packing concatenates multiple examples into one sequence up to the max length, cutting most of that waste.

Packing changes batch semantics. A packed sequence can contain several original examples, so "steps per epoch" and any LR schedule keyed to example count shift once packing is on — recompute schedule milestones against packed-sequence count.
MANDATORY: decode and manually inspect 5–10 packed sequences before scaling to a full run. Confirm example boundaries land where expected, template markers are intact per sub-example, and the loss mask is still assistant-only within each packed sequence. Not optional — packing bugs are silent (the loss curve looks normal) and only surface in eval quality, hours later:
python
```
for seq in packed_dataset.select(range(10)):
    print(tokenizer.decode(seq["input_ids"]))
```

不使用打包的话，40%-70%的计算资源会浪费在填充上——将可变长度的样本按固定序列长度批量处理时，每个样本长度与批量最大长度之间的差值会造成资源浪费。打包操作会将多个样本拼接成一个不超过最大长度的序列，大幅减少此类浪费。

打包会改变批量语义。 一个打包后的序列可能包含多个原始样本，因此开启打包后，“每轮步数”以及所有基于样本数量的学习率调度都会发生变化——需要根据打包后的序列数量重新计算调度里程碑。
强制要求：在全面启动训练前，解码并手动检查5-10个打包后的序列。 确认样本边界符合预期、每个子样本的模板标记完整，且每个打包序列内的损失掩码仍仅针对助手轮次。这一步必不可少——打包相关的错误是隐性的（损失曲线看起来正常），只会在数小时后的评估环节中暴露性能问题：
python
```
for seq in packed_dataset.select(range(10)):
    print(tokenizer.decode(seq["input_ids"]))
```

Synthetic Data Rules

合成数据规则

Keep ≥25% real data as a collapse guard. Training on a growing share of model-generated data without a real-data floor drives measurable quality collapse over successive generations — 25% real is the minimum that holds the line. General-domain replay rows count toward this floor — "real" means "not generated for this task from this student," not "human-authored." An all-synthetic-by-construction dataset can meet the ≥25% floor through replay alone (see
```
references/synthetic-data.md
```
's Replay-Mix Construction recipe); state which rows count as "real" in the dataset card rather than leaving the floor structurally unmeetable.
Magpie and rejection sampling are the workhorses. Magpie extracts prompts from the model's own template prior; rejection sampling generates several candidates per prompt and keeps only the ones a filter passes. Both beat naive single-shot generation.
Targeted, student-aware generation beats static generation by 1.3–2x sample efficiency — aiming at the student's actual failure modes hits a quality bar with fewer filtered examples.
Typical accept rates after filtering run 10–30%. Plan volume accordingly — a 10,000-row target at 15% accept needs ~65,000+ raw generations.
Generation-method ranking, filter funnel, replay- mix construction, and distillation pattern:
```
references/synthetic-data.md
```
.

保留≥25%的真实数据以防止性能退化。 在没有真实数据下限的情况下，使用占比越来越高的模型生成数据进行训练，会导致模型性能在多代训练后出现可测量的退化——25%的真实数据是维持性能的最低要求。通用领域的重放样本可计入该下限——“真实”指的是“并非由当前待训练模型（student）为该任务生成的数据”，而非“人工撰写的数据”。一个完全由合成数据构成的数据集可仅通过重放样本达到≥25%的下限（详见
```
references/synthetic-data.md
```
中的重放混合构建方案）；请在数据集卡片中说明哪些样本属于“真实”数据，避免从结构上无法达到下限要求。
Magpie方法和拒绝采样是核心工具。 Magpie从模型自身的历史模板中提取提示词；拒绝采样会为每个提示词生成多个候选样本，仅保留通过过滤器的样本。这两种方法的效果均优于简单的单次生成。
针对待训练模型（student）的定向生成，样本效率比静态生成高1.3-2倍——针对模型实际的失效模式生成数据，只需更少的过滤后样本即可达到质量标准。
过滤后的典型通过率为10%-30%。 请据此规划生成量——若目标为10000条样本，通过率为15%，则需要约65000+条原始生成数据。
生成方法排名、过滤器流程、重放混合构建以及师生蒸馏模式可查看：
```
references/synthetic-data.md
```
。

The Dataset Card

数据集卡片

Every dataset that reaches training gets a card — the required Phase 2 artifact

/finetune

checks before launching. The card is not free-form documentation; it MUST carry these fields:

Provenance — where every row came from (real source(s), synthetic method(s), or both), traceable to
```
trace-to-training-data
```
output.
Counts — total rows, and rows per split (train/eval/held-out) if split.
Synthetic/real ratio — the measured ratio, checked against the ≥25% real floor above.
Dedup method — exact-match, semantic (embedding threshold), or both; see the filter funnel in
```
references/synthetic-data.md
```
.
Template used — the exact chat template string/identifier, kept consistent through inference and eval — this is what ties an
```
eval-harness-first
```
run back to the checkpoint.
Packing config — whether packing was used, max sequence length, and confirmation the 5–10-sequence manual inspection above was done.

A dataset missing any of these six fields isn't ready for

/finetune

— the card is a gate, not a summary written after the fact.

所有进入训练环节的数据集都需要配套数据集卡片——这是启动训练前

/finetune

检查要求的第二阶段产物。数据集卡片并非自由格式的文档，必须包含以下字段：

来源 —— 每条样本的来源（真实数据源、合成方法，或两者皆有），可追溯至
```
trace-to-training-data
```
的输出。
数量统计 —— 总样本数，若数据集已拆分，则需包含各拆分集（训练/评估/保留集）的样本数。
合成/真实数据比例 —— 实际测量的比例，需符合上述≥25%真实数据的下限要求。
去重方法 —— 精确匹配去重、语义去重（基于嵌入阈值），或两者结合；详见
```
references/synthetic-data.md
```
中的过滤器流程。
使用的模板 —— 确切的聊天模板字符串/标识符，需在推理和评估阶段保持一致——这是将
```
eval-harness-first
```
运行结果与训练 checkpoint 关联的关键。
打包配置 —— 是否使用打包、最大序列长度，以及确认已完成上述5-10个序列的手动检查。

缺少上述任意六个字段的数据集均不满足

/finetune

的要求——数据集卡片是准入门槛，而非事后撰写的总结。

Phase 2 Exit Checklist

第二阶段退出检查清单

Before handing off to

/finetune

, confirm:

Format matches the method (table above).
Template applied before concatenation.
Loss masked to assistant turns only.
5–10 packed sequences decoded and read.
≥25% real data in the final mix.
Dataset card complete — all six fields.

在移交至

/finetune

之前，请确认：

数据格式与所选方法匹配（见上方表格）。
已在拼接前应用模板。
损失掩码仅针对助手轮次。
已解码并查看5-10个打包后的序列。
最终数据集中真实数据占比≥25%。
数据集卡片完整——包含所有六个字段。

References

参考资料

```
references/formats-and-templates.md
```
— JSONL examples per format, current-TRL masking code, and the ShareGPT conversion note.
```
references/synthetic-data.md
```
— generation-method ranking, filter funnel, replay-mix construction, and teacher→student distillation pattern.

Related skills:

finetuning-method-selection

routes here;

lora-qlora-recipes

vision-sft

, and

preference-optimization

consume the datasets this skill produces;

trace-to-training-data

is the provenance source for graded-trajectory datasets;

eval-harness-first

grades the resulting checkpoint.

```
references/formats-and-templates.md
```
— 各格式的JSONL示例、当前TRL框架的掩码代码，以及ShareGPT转换说明。
```
references/synthetic-data.md
```
— 生成方法排名、过滤器流程、重放混合构建，以及师生蒸馏模式。