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 workload, 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-optimize training runs branch RUN_ID --snapshot SNAPSHOT_ID --steps 200 \
  --restore trainingState --overrides lower-lr.json --dry-run
akka-optimize training runs branch RUN_ID --snapshot SNAPSHOT_ID --steps 200 \
  --restore trainingState --overrides lower-lr.json --wait --exit-status
akka-optimize 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 horizon, so an override can’t 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. The trainer rejects every other field, including one that repeats the parent’s value. The method, dataset, precision, sequence length, and adapter shape remain fixed. 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 doesn’t 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-optimize 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 name has since moved. 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.