Skip to content

Which trainer do I need?

Foundry ships nine trainers. You need one or two of them — which ones depends entirely on what you're building and what you already have. Start from your goal:

I want a model that generates text (causal LM)

You need a teacher — a bigger causal LM the student learns from.

Situation Use
Short run, one GPU, prototyping TorchDistillTrainer — teachers run live every step
Multiple epochs and/or multiple GPUs CachedDistillTrainer — teachers run once, logits cached to disk, later epochs are free

Both accept several teachers at once with relative weights (TeacherRegistry).

I want an embedding model (search / retrieval / similarity)

What you have Use
A strong embedding teacher (bge, e5, …) and raw text EmbeddingDistillTrainer — copy the teacher's sentence vectors into a smaller model
{anchor, positive} pairs — or the ability to synthesize them ContrastiveTrainer — InfoNCE, the e5/bge training recipe
Both Distil first, then contrastive fine-tune the result

No pairs and no teacher? Synthetic data manufactures pairs from raw passages — or from nothing in the target language, via translation.

Measure the result with retrieval evaluation (nDCG / Recall vs e5, LaBSE, …).

I want an encoder base for classification / NER

This is a two-step build: make a base, then add a head (next section).

What you have Use
Only raw text — no teacher MLMTrainer — masked-LM pretraining from scratch
A teacher encoder, limited raw text EncoderDistillTrainer — copy the teacher's per-token states; much more data-efficient than MLM from scratch
A teacher and in-domain text, student shares the teacher's vocab DistilMLMTrainer — distillation + MLM in one loss (the DistilBERT recipe)

I have a base — I want a task model

Task Use
Classification (topic, sentiment, langID, moderation) SequenceClassificationTrainer
NER / token tagging TokenClassificationTrainer

build_encoder_with_head("./my-base", num_labels, task) attaches a fresh head in one line. Set freeze_backbone=True to train only the head — many heads can then share one frozen encoder. Compare bases head-to-head with the evaluation harness.

I want the model smaller / cheaper to serve

Goal Use
int8/int4 weights prepare_qat + export_quantized — wrap the model before training with any trainer above, export packed weights after
Swappable task adapters instead of full fine-tunes Skill packs — detachable LoRA adapters with PEFT round-trip
A bigger model from the one you have Growth — SOLAR-style depth up-scaling

Python, YAML recipes, or the CLI?

Three layers drive the same machinery — pick by how repeatable the run needs to be:

Layer When
Python API (everything above) Exploring, notebooks, custom loops — the full feature set
YAML recipes + foundry run A run you'll repeat or hand to someone else: the whole pipeline in one reviewable file
CLI foundry doctor (check your install), foundry plan (preview a recipe's stages and cost)

If in doubt, start with the Python API — recipes cover the common paths, not every option.

Still unsure?