---

name: data-and-datasets description: "Build and validate torchtune dataset configs, message transforms, packing, prompt templates, multimodal rows, and collators." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

data-and-datasets

Use this sub-skill when a torchtune task is about dataset shape, Message conversion, input masking, local or Hugging Face data sources, sample packing, prompt templates, multimodal text+image rows, or batch collation.

Route Tasks

• Choose instruct_dataset or InputOutputToMessages for single-turn input/output SFT rows.
• Choose chat_dataset, ShareGPTToMessages, or OpenAIToMessages for multi-turn conversations.
• Choose preference_dataset or ChosenRejectedToMessages for DPO/reward data with chosen and rejected conversations.
• Choose text_completion_dataset for free-form pretraining-style corpora with a text column.
• Choose torchtune.datasets.multimodal builders for text+image SFT rows, and keep image handling in the dataset/model transform boundary.
• Choose PackedDataset only when the tokenizer or model transform has max_seq_len and the recipe expects packed SFT/text-completion batches.

Standard Workflow

1. Identify the raw row shape and source: Hugging Face dataset name, local json/jsonl/csv/text, or remote file URL.
2. Map raw columns to the expected torchtune keys with column_map, conversation_column, or builder-specific arguments.
3. Convert rows to Message lists before tokenization; validate role order and non-empty content early.
4. Pair the dataset builder with the correct tokenizer or model transform from models-and-modules.
5. Decide masking with masking_strategy where exposed, or legacy train_on_input when using builder config fields.
6. Decide packing and collation after verifying tokenized sample keys match the target recipe in post-training-recipes.
7. Use cli-and-config for tune cp, tune cat, tune validate, registry names, and launch syntax; do not import recipes as a Python package.

References

• Data formats explains row shapes, YAML fragments, packing, prompt templates, collators, and local/HF source assumptions.
• API reference lists the practical torchtune data and dataset signatures agents usually need.
• Troubleshooting maps common data failures to fixes.
• JSONL validator checks message, input-output, chat, and preference rows without training or downloads.

Quick Validation

From this sub-skill directory, run the bundled validator on a local JSONL sample before wiring it into a recipe:

python scripts/validate_messages_jsonl.py data/sample.jsonl --shape auto

For multimodal rows with local image paths:

python scripts/validate_messages_jsonl.py data/sample.jsonl --shape conversations --image-key image --image-root data --check-image-paths

The validator is intentionally lightweight: it parses JSONL, checks required columns, checks message role/content structure, optionally checks local image paths, and never imports torch, starts training, or downloads datasets.