akka optimize training runs branch
Submit a child run from a source snapshot
Synopsis
Submit a child run from a committed source snapshot of PARENT.
The parent run is unchanged. The child run has its own ID, metrics, cost, models and saved state. Children created from the same source snapshot are independent.
--snapshot selects the source snapshot. Use "training runs snapshots" to find one, then pass its ID or an unambiguous prefix.
--steps sets the child run’s budget of additional optimizer updates. The child stops at this budget, so an override document cannot set epochs or maxSteps.
--restore selects the snapshot artifact and state policy:
auto restore the training state where the snapshot holds it and the branch changes
nothing a trainingState branch cannot carry, and the weights otherwise. The
result names the mode chosen and why. This is the default.
weights load adapter weights; reset the optimizer, schedule, RNG, data position and
engine step.
trainingState restore adapter weights, optimizer, RNG, data position and engine step; replace
the saved schedule with one spanning the child budget at the child learning rate.
The child run inherits the parent run’s training project, base model, devices and grader. --overrides loads a configuration-change document. Omitted fields are inherited. Undeclared fields are rejected.
With --restore trainingState, only the learning rate may appear in --overrides. The service rejects every other field, even when its value equals the parent’s. This mode requires the same method and a snapshot that holds its training state. For reinforcement learning with a positive klBeta, it is unavailable when the producer started from inherited adapter weights.
A reinforcement child restored from weights with a positive klBeta measures the penalty against a frozen copy of the adapter it inherited. The deployment can do this only on one GPU, and only where its catalog admits it there. Otherwise, Optimize refuses the branch and says to set klBeta to 0.
To train a dpo child from a supervised run, restore from weights and set method to dpo and dataset to a preference dataset in --overrides. The child measures its rewards against the adapter it inherited and trains on one GPU. It trains at the dpo default learning rate unless --overrides sets one. It does not inherit the parent’s data or loss policy, memory settings, engine settings, weight precision or flex attention.
--dry-run asks the service to validate and resolve the request without creating a submission, retaining the source snapshot or claiming a device. The preview does not reserve the source.
A successful submission response means the operation is durable. Source retention and child-run creation happen during preparation. --wait follows preparation before it follows the child run.
The command generates a token for each invocation. Running the command again generates another one, which the service treats as a second run. Passing --submission-id with the token from an earlier attempt reaches whatever that attempt created, instead of starting a second run. It is for retrying an attempt whose outcome was never seen. "training runs branches PARENT --submission TOKEN" reads that attempt’s state back instead, and is the cheaper check.
akka optimize training runs branch PARENT --snapshot SNAPSHOT --steps N [flags]
Examples
# Preview a branch without submitting it
akka optimize training runs branch 7d496e82c3a15f04 \
--snapshot 3f2a9c71bd04 --steps 200 --overrides lower-lr.json --dry-run
# Submit it and follow the run it starts
akka optimize training runs branch 7d496e82c3a15f04 \
--snapshot 3f2a9c71bd04 --steps 200 --overrides lower-lr.json --wait
# Extract the new run's ID using jq
akka optimize training runs branch 7d496e82c3a15f04 \
--snapshot 3f2a9c71bd04 --steps 200 --force --jq .childRunId
Options
--config-name string Label for the child configuration in the training project score table
--description string Description for the child run
--dry-run Preview the resolved child run without submitting it
--exit-status Exit non-zero if preparation or the child run fails; requires --wait
-h, --help help for branch
-f, --overrides string Override document path, or '-' for standard input
--restore string Snapshot artifact to restore: auto, weights or trainingState (default "auto")
--snapshot string Source snapshot ID or unambiguous prefix
--steps int Additional optimizer updates allowed for the child run
--submission-id string Submission token to reuse after an uncertain response
--wait Wait for preparation and child-run completion
Options inherited from parent commands
--cache-file string location of cache file (default "~/.akka/cache.yaml")
--config string location of config file (default "~/.akka/config.yaml")
--context string configuration context to use
--disable-prompt Disable all interactive prompts when running akka commands. If input is required, defaults will be used, or an error will be raised.
This is equivalent to setting the environment variable AKKA_DISABLE_PROMPTS to true.
--force Skip the confirmation prompt
--jq string Filter the JSON output with a jq expression
--json string Output JSON with only these fields; --json= lists the fields a command offers
--no-color Print without color or a redrawn progress line, as NO_COLOR does
-o, --output string set output format to one of [text,json,json-compact,go-template=] (default "text")
--page-mode string the mode for paging, either paged, buffered or auto. (default "auto")
-q, --quiet set quiet output (helpful when used as part of a script)
--region string Region to use if the project has more than one region
--timeout duration client command timeout (default 10s)
--trainer-url string Trainer service URL (default TRAINER_URL, then AKKA_OPTIMIZE_URL, then a local dev-mode service, then http://localhost:9001)
--use-grpc-web use grpc-web when talking to Akka APIs. This is useful when behind corporate firewalls that decrypt traffic but don't support HTTP/2.
--verbose set verbose output
SEE ALSO
-
akka optimize training runs - Manage training runs, snapshots and child runs