CLI commands for training

akka optimize is the command-line interface for Akka Optimize. Use akka optimize commands to operate Optimize. The training pages use these commands to explain each operation.

akka optimize is a command group of the akka CLI. To install the akka CLI, see Install the Akka CLI. Before you use akka optimize commands with Optimize in a remote Akka environment, log in.

Connect to Optimize

The AKKA_OPTIMIZE_URL environment variable specifies the address of your Akka project’s route. akka optimize uses this address to contact Optimize services, including trainer for training and registry for the artifact registry. Set it once for a deployed project. akka route get <route> shows the route’s hostname.

Set the address and confirm that Optimize responds:

export AKKA_OPTIMIZE_URL=https://optimize.example.akka.services
akka optimize status

To reach one service at another address, set that service’s own variable, such as TRAINER_URL or REGISTRY_URL. A service’s own variable takes precedence over AKKA_OPTIMIZE_URL for that service only. The --trainer-url flag on any command takes precedence over both for the trainer. To use the route for every service, unset them:

unset TRAINER_URL REGISTRY_URL

status lists each service that the CLI contacts, whether the service responds, and the address that the CLI used. This section requires only the trainer and the registry. A service your project’s route does not map appears with an error at the route’s address. training info reports the trainer’s backend. It exits with a non-zero status when the service does not respond or has not finished starting, so a script can use it to wait for the trainer.

A 503 response from the trainer’s address can mean that the service is restarting after a deployment. Retry the request after a minute.

The artifact registry holds datasets and scoring bundles. akka optimize reaches the registry at AKKA_OPTIMIZE_URL too, or at REGISTRY_URL where you set it.

Authenticate

To log in to a remote Akka environment, see Login to a remote env.

akka optimize uses the login of the akka CLI. After you run akka auth login, akka optimize gets the refresh token from the current akka context. On the first request that requires authentication, it exchanges the refresh token for an access token. You do not need any other workstation configuration.

To use the login of a different akka context, name that context with the --context flag or the AKKA_CONTEXT environment variable. The flag takes precedence over the variable. akka optimize exchanges the token at the API host that the named context specifies, so one shell can reach a service on a different platform from the current context. If the configuration file has no context with that name, or the named context holds no login, akka optimize refuses the command and lists the contexts that the file contains.

export AKKA_CONTEXT=staging
akka optimize training runs list

For a job that must use different credentials from the user who is signed in, set one of the following environment variables. akka optimize uses the first variable that is set:

Variable Description

AKKA_ACCESS_TOKEN

An access token, used as it is.

AKKA_TOKEN

A refresh token. akka optimize exchanges it for an access token and caches the result until shortly before it expires.

AKKA_OAUTH_TOKEN

An OAuth token. Requires AKKA_OAUTH_TOKEN_AUDIENCE.

AKKA_OAUTH_TOKEN_FILE

A file that holds an OAuth token.

A denied request returns 403. The response identifies the refused action, such as optimize.training.runs.create.

Conventions

The flags, output formats, and behavior that akka optimize commands share with the other akka commands are in CLI conventions.

Command groups

The following table lists the command groups:

Group Manages

registry datasets

Training and evaluation datasets in the artifact registry: register, list, inspect versions, read objects, and move aliases. See Datasets.

training datasets

Analysis of a registered dataset under a base model, before a run claims a GPU. See Analyze a dataset.

training base-models

Base models allowed by the deployment: list, inspect, select, and deselect. See Base models.

training endpoints

Model inference endpoints: create and delete endpoints; list, inspect, or detach their models; send an input; and forward a local address. See Endpoints.

training projects

Training projects, their evaluation settings, and history. See Training projects.

training runs

Training runs: start, wait, pause, resume, cancel, and branch. Also metrics, hyperparameters, snapshots, TensorBoard, and the Grafana dashboard.

training snapshots

One committed snapshot, and its registration as a candidate model.

training evaluations

Evaluations of a model against a dataset: start, wait, report, and predictions.

training distillations

Generate a teacher model’s answers to decisions in a chat dataset. Create, wait, pause, resume, cancel, and view rejected outputs. See Distillations.

training comparisons

A source snapshot evaluated with its branches under one pinned contract.

training pipelines

Ordered train and evaluate stages in one submission.

registry models

Models in the artifact registry: the versions that training produced, base models, and the aliases that mark a candidate or a champion. See Evaluation.

registry bundles

Scoring bundles in the artifact registry. See Scoring bundles.

registry images

Images that dataset examples reference, uploaded on their own. registry datasets register uploads the images an example references, so you need this group only to upload images ahead of time.

The other akka optimize groups, such as rulesets, use-cases, spend, and eval, are described where their tasks are. The CLI command map lists each command group and the section that describes it.

Every command answers --help with its flags and examples.