Branches
A branch starts another training segment without changing its source run. Use a branch to try a different learning rate, method, or other compatible configuration. The child is a new run with its own identity, budget, metrics, cost, and outputs. The parent remains unchanged, and children from the same snapshot are independent.
The child inherits the parent’s training project, base model, devices, and grader. An override document contains only the configuration fields that change. Omitted fields retain the parent’s resolved values.
Submit a branch
Validate and submit a branch, then list the branches of a run:
echo '{"hyperparams":{"optimizer": {"learningRate": 0.00005}}}' > lower-lr.json
akka training runs branch RUN_ID --snapshot SNAPSHOT_ID --steps 200 \
--restore trainingState --overrides lower-lr.json --dry-run
akka training runs branch RUN_ID --snapshot SNAPSHOT_ID --steps 200 \
--restore trainingState --overrides lower-lr.json --wait --exit-status
akka training runs branches RUN_ID
--snapshot specifies a committed snapshot of the parent from training runs snapshots. --steps sets the child’s budget of additional optimizer updates. It replaces the inherited update budget, so an override cannot set epochs or maxSteps.
Restore modes
--restore selects one of the following modes:
| Mode | Initial state | Child schedule |
|---|---|---|
|
|
As the mode it chose. |
|
Adapter weights, with a fresh optimizer, random-number generators, data position, and engine counter. |
Starts fresh over the child budget. |
|
The adapter, optimizer, random-number generators, data position, and engine counter from the snapshot. |
Replaced by a new schedule of the run’s own scheduler kind and warmup over the child budget, at the child’s learning rate. A reinforcement child under verl runs a constant schedule with no warmup. |
With auto, a branch keeps its optimizer state wherever an explicit trainingState would be accepted, and restores only the weights otherwise. The dry run, the submission and the Restore line of training runs get name the mode chosen and why, for example chosen by auto: optimizer.weightDecay cannot be overridden when restoreMode is trainingState. The child keeps the mode chosen when it was accepted. A trainingState or weights request is used as written: Optimize refuses a trainingState branch it cannot restore, and weights always starts a fresh optimizer.
training runs sweep takes auto too. Each point chooses its mode on its own, so one sweep can keep the optimizer for a point that changes only the learning rate and start a fresh one for the others. The listing shows each point’s mode.
With trainingState, the override document can contain only the learning rate. Optimize refuses every other field, including one that repeats the parent’s value. The method, dataset, precision, sequence length, and adapter shape remain fixed. A trainingState child continues its parent’s epochs, so it neither saves nor evaluates at epoch boundaries, regardless of its inherited saveEachEpoch and validateEachEpoch values. training runs get --settings reports this on its Epochs line, and the run API sets origin.skipsEpochSavesAndReadings. A weights branch permits broader compatible changes, including a change from supervised to reinforcement training, or from supervised training to dpo. Both modes check the base-model revision and adapter compatibility before starting a job.
If you later resume either child, it restores its own saved schedule. Optimize does not apply the branch schedule again.
Preference training from a supervised run
To train a dpo child from a supervised run’s adapter, branch from one of the run’s snapshots with weights, or with auto, which chooses weights for a change of method. The override document sets method to dpo and dataset to a preference dataset, and can set preference and hyperparams:
method: dpo
dataset: triage/preferences
preference:
beta: 0.1
The child measures its rewards against a frozen copy of the adapter it inherited, not against the base model. The document can set preference.fusedLoss to false to compute the loss with TRL’s own. A dpo child of a dpo run inherits the parent’s fusedLoss unless the document sets it. See Direct preference optimization.
The child trains on one GPU, whatever its parent claimed. It trains at the dpo default learning rate, 0.000005, unless the document sets hyperparams.optimizer.learningRate. It keeps the parent’s adapter shape and the rest of its supervised hyperparameters, except training.validateEachEpoch, training.validationBatchSize and training.tokensPerGpu, which it drops. It does not inherit the parent’s data or loss group, its memory settings, its engine settings or model.weightPrecision. A branch cannot set a data group, so the child has no validation dataset and reports no validation accuracy. A parent that trained with flex_attention gives a child that trains with sdpa.
A dpo run that started from the base model can also branch to dpo with trainingState. Optimize refuses trainingState for a dpo run that started from an inherited adapter, since the restored child would measure against the base model. Use weights for that branch.
Override documents
An override document contains one JSON or YAML object. The CLI rejects unknown fields, explicit nulls, aliases, merge keys, and additional YAML documents. It preserves and validates an explicit zero.
Acceptance and preparation
A successful submission means that the request is durable. During preparation, Optimize retains the source snapshot and creates the child run. It can therefore accept the request before the child exists. --wait follows the preparation and then the child. Without it, read the preparation state before using the child:
akka training runs branches RUN_ID --submission SUBMISSION_TOKEN
Every invocation generates a new submission token, which the service treats as a new child. After an uncertain outcome, such as a lost connection, pass --submission-id with the original token. This reaches the child created by that attempt instead of starting another one. The CLI prints the recovery command. A retried submission uses its stored dataset resolution even if the reference has since changed. A dry run reserves no resources.
Lineage
A child records its immediate parent, exact source snapshot, and starting step in the parent. Model provenance distinguishes this input from the child’s output checkpoints. You can therefore read nested branches without confusing the update counts of different generations.
Compare a source with its branches
A comparison evaluates the source snapshot and selected branch models with one pinned dataset, grader, and completion-token limit. It registers the source as a candidate if necessary. For more information, see Comparisons.