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

Mode	Initial state	Child schedule
`weights` (default)	Adapter weights, with a fresh optimizer, random-number generators, data position, and engine counter.	Starts fresh over the child budget.
`trainingState`	The adapter, optimizer, random-number generators, data position, and engine counter from the snapshot.	Replaced by a linear schedule over the child budget at the child’s learning rate.

weights (default)

Adapter weights, with a fresh optimizer, random-number generators, data position, and engine counter.

Starts fresh over the child budget.

trainingState

The adapter, optimizer, random-number generators, data position, and engine counter from the snapshot.

Replaced by a linear schedule over the child budget at the child’s learning rate.

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. 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. The trainer does not apply the branch schedule again.

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, the trainer 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.