Base models
A training run starts from a base model. Each deployment supports a fixed set of base models. Select a model to prepare it for training, evaluation, or serving.
Allowed and selected models
An allowed model is available for training or serving in this deployment. The deployment’s hardware and engines must support it. You cannot add models to this list.
A selected model is an allowed model that you have prepared for training, evaluation, or serving. Selecting a model registers it. If the deployment uses a shared cache, selection also downloads the weights in advance. Initially, no models are selected.
List the selected models:
akka training base-models list
To include every allowed model, add --all:
akka training base-models list --all
The repository identifies each model and is the value that other base model commands accept. The output also shows the pinned commit, parameter count, context length, and measured training methods. STATUS shows the model’s selection state. A selected and prepared model is ready. A selected model whose weights have not arrived is preparing. A selected model that could not be registered is failed, and selecting it again retries. An allowed model that nobody has selected is not-selected.
The allowed list contains models admitted for training or serving. If the list does not contain a model that you need, ask your operator to add it to the deployment.
To see the measurements for a model, get it. Under Measured training envelopes, the output lists
the measured training method, precision, GPU count and sequence length. It also shows the memory
of each GPU and the host memory of the node. The methods are sft, grpo, gspo and dpo.
For example:
akka training base-models get Qwen/Qwen3-8B
google/gemma-4-26B-A4B-it trains in the shipped H200 catalog. Its default adapter covers
attention and the shared MLP, and leaves the experts and the router frozen.
Some models have serving measurements alone, such as google/gemma-4-31B-it in the shipped H200
catalog. In a strict catalog, you can serve them from an endpoint, evaluate them, or use them as a
distillation teacher, but you cannot train them. An advisory catalog permits training with an
unmeasured warning where the engine supports the model. It also admits a model that no training or
serving envelope holds.
base-models get shows a mixture-of-experts checkpoint’s active parameters beside its total.
This is the number of parameters one token passes through. When this deployment refuses training,
it shows Allowed for: serving only and Training refusal with the reason. An advisory model that
can train with a warning is not labelled serving only. The API keeps servingOnly for this verdict
and exposes the reason as trainingRefusal. Under Serving this deployment admits, it lists the
devices and context lengths measured for serving.
Measured training envelopes
Training envelopes are advisory by default. They record measurements, rather than every configuration you can request. A model can use an unmeasured device count, model size, method, precision, engine or sequence length if the engine supports it. Exceeding a measured token limit per pass or active parameter limit is also advisory. Optimize admits the run with a warning that it may run out of device memory.
The dry run, start response and training runs get show the warning. The run keeps it even if the
catalog changes. A run within a measured envelope has no envelope warning.
To list every measured envelope of the deployment, and whether the catalog is advisory or strict, run:
akka training base-models envelopes
Each row is a device profile and GPU count, with the methods, precisions and engines measured
there, the largest model and active parameter count, the longest sequence and the most tokens one
pass carries. -o json gives strictEnvelopes and measurements. training capacity shows the
mode alone, on a Training envelopes line.
An operator can set trainer.base-model-catalog.strict-envelopes = true in the applied catalog
to refuse unmeasured runs.
Endpoints, evaluations and distillation teachers outside the device’s serving and training measurements also carry warnings in their start and read responses in advisory mode. In strict mode, a model with serving measurements alone is refused on a device or at a context outside its serving envelope. A model with serving measurements alone keeps its measured context. Without a holding envelope, the deployment’s configured context applies. An explicit larger distillation context is honoured in advisory mode.
A training envelope on the serving device also counts as evidence, up to its measured sequence
length. Serving beyond that length warns in advisory mode. A deployment that sets
trainer.serving.ray.max-model-len = 0 serves at the model’s own context, which is compared with
the measurements. The warning does not shorten the served context.
Engine, host memory, device layout and deployment capacity limits apply in either mode.
A serving replica uses one GPU. A dpo run always uses TRL on one GPU, even in an advisory catalog.
See Measured training envelopes for the limits
and warning display.
Find compatible models
Before you ask an operator to allow a model, check whether the deployment can train it. The candidates command lists repositories from a Hugging Face account and evaluates each model against the deployment’s engines and hardware:
akka training base-models candidates --author google --match 'gemma-4-*'
--match filters repository names by using a glob pattern. In the pattern, * matches any sequence of characters. Omit --match to list all repositories from the account.
In the output, VERDICT is admissible if the deployment can train the model. Otherwise, the column explains why the model is not supported. Possible reasons include an unsupported architecture, a model that is too large for the hardware, or a model that Optimize cannot adapt.
The command reads data from Hugging Face but does not modify the deployment. It does not allow or select any models.
To generate catalog entries for the admissible models, an operator can add --catalog:
akka training base-models candidates --author google --match 'gemma-4-E4B*' --catalog
Before you apply the catalog, list dpo in a device envelope only after a dpo run has been measured on that device at the envelope’s maximum sequence length. A dpo run needs much more device memory than a supervised run at the same length, so a supervised run that fits an envelope does not show that a dpo run fits it.
Select a model
akka training base-models select Qwen/Qwen3-8B
The command returns immediately while preparation continues in the background. Add --wait to wait until the model is ready. The wait ends after 30 minutes. To wait longer, use --timeout.
While the model is being prepared, you can start a run or evaluation, or create an endpoint. Optimize accepts the request and starts the work when the model is ready. In a script, use --wait to prepare the model before the script continues.
To check the preparation progress, run base-models get.
Model statuses
base-models get reports two statuses. Status shows whether the deployment configuration permits you to use the model.
| Status | Meaning |
|---|---|
|
Optimize is still reading the repository. |
|
The training engines and hardware support the model. |
|
The training engines or hardware do not support the model. |
|
Optimize could not read the repository. |
|
The model was removed from the allowed list. |
Selection shows the model’s preparation progress. It appears only after you select the model.
| Selection | Meaning |
|---|---|
|
Optimize is registering the model. This usually takes seconds. |
|
Optimize is downloading the weights. This can take several minutes for a large model. |
|
The model is ready for training, evaluation, and serving. |
READY means that you can use the model. It does not indicate whether the weights were downloaded, because the model is usable either way. Weights shows the cache state after the selection reaches READY:
| Weights | Meaning |
|---|---|
|
The weights are downloaded and ready for use. |
|
This deployment does not download weights in advance. The first run that needs them downloads them before it starts, and takes longer to begin. |
|
The download did not finish. The first run that needs the weights downloads them before it starts. |
base-models select --wait reports the same information when it returns, so a script does not need to read the entry again.
Deselect a model
akka training base-models deselect Qwen/Qwen3-8B
The model remains allowed, and you can select it again. Optimize retains its registration because models trained from it still refer to it.
Deselecting does not stop an endpoint that is already serving the model. To stop one, see Endpoints.