---

name: training-and-distillation description: "Train or fine-tune ColBERT models, prepare and validate triples, use scored distillation examples, and plan GPU/resource settings. Use when tasks mention ColBERT Trainer, fine-tuning checkpoints, training triples, distillation scores, nway/bsize/accumsteps choices, or training-file validation." disable-model-invocation: true metadata: disco-role: operating license: MIT

ColBERT Training And Distillation

Use this sub-skill when the user needs to configure or troubleshoot ColBERT training. It covers the Trainer API, JSONL examples/triples, scored distillation examples, resource planning, and safe helper scripts. Do not use it for post-training indexing/search, evaluation benchmarks, or tokenizer internals.

Route Tasks

• For a runnable training starting point, read references/training-workflows.md and generate a script with scripts/training_template.py.
• For API details, checkpoint precedence, data shapes, and config fields, use references/api-reference.md.
• For validation before GPU work, run scripts/validate_training_files.py against triples, queries, and collection files.
• For launch, data, scored-example, OOM, and dependency failures, use references/troubleshooting.md.
• For indexing or searching a trained checkpoint, switch to the indexing-and-search sub-skill.
• For ranking metrics, LoTTE/MS MARCO evaluation, qrels, and dataset conventions outside training, switch to the data-and-evaluation sub-skill.
• For tokenization behavior, max lengths, dimensions, and model architecture details, switch to the modeling-and-tokenization sub-skill.

Core API

The verified public training entry point is:

from colbert import Trainer
from colbert.infra import ColBERTConfig, Run, RunConfig

with Run().context(RunConfig(nranks=1, experiment="my-training-run")):
    config = ColBERTConfig(bsize=32, nway=2, accumsteps=1)
    trainer = Trainer(triples="triples.train.jsonl", queries="queries.train.tsv", collection="collection.tsv", config=config)
    trainer.train(checkpoint="bert-base-uncased")
    checkpoint_path = trainer.best_checkpoint_path()

Important behavior: Trainer.train(checkpoint=...) is the checkpoint source used by training. If ColBERTConfig(checkpoint=...) is also set, the explicit train(checkpoint=...) argument wins.

Bundled Helpers

• scripts/validate_training_files.py checks JSONL triples/examples plus query and collection TSV files for parseability, ID references, duplicate IDs, scored-example shape, and likely nway mismatches before launching training.
• scripts/training_template.py emits a safe argparse-based ColBERT training script template and warns about resource choices such as bsize % nranks, large nway, and GPU expectations.

Training Scope

Basic ColBERTv1-style training usually uses unscored [qid, positive_pid, negative_pid] JSONL examples with nway=2. Advanced ColBERTv2-style training often uses many-way examples such as 64-way scored JSONL, use_ib_negatives=True, distillation_alpha, doc_maxlen=180, dim=128, and a source checkpoint such as colbert-ir/colbertv1.9.

Practical training requires CUDA/GPU resources. CPU-only environments are useful for imports, file validation, and template generation, but real fine-tuning, distillation scoring, and distributed training are GPU-heavy.