Model versions

The Model versions screen lets you register the versions of a model with their weights digest and licence, request their approval, roll a version out as a canary or at 100 percent, and roll back. Portal path: /llm/versions. It is used by the tenant administrators who publish model versions; approvals are decided by a tenant_admin or a security_officer in the Approvals inbox. The screen is built in portal/src/screens/kit-data.tsx (ModelVersions, modelVersionsCfg, modelRollbackCfg, Rollout).

What the screen shows

The section Model with the selector Choose a model, filled from GET /v1/models (display name and id). Without model: "No model registered. Register a model in the models registry to manage its versions." and the link Open the models registry.
Once a model is chosen, two tabs: Versions and Rollout state.

Versions tab: the table Versions (GET /v1/models/{model_id}/versions, oldest first), a refresh button and New version.

Column	Content
Version	Version label, for example `1.2.0`.
Status	`draft`, `pending_approval`, `canary`, `active`, `superseded` or `rolled_back`.
Licence (SPDX)	SPDX expression of the licence.
Weights digest	Column bound to `weights.digest`.
Created	Creation date.

When empty: "No version. Register a version with its weights digest and licence." A click on a row opens a drawer with the full record.

Rollout state tab: the section Rollout state with the JSON of GET /v1/models/{model_id}/rollout (active_version, canary_version, canary_percent and the history of publications, canaries and rollbacks), then the panel Roll back ("Aborts the canary or restores the previous version.") with a Reason field and Run.

Actions

Button or action	What it does	API call	Roles
Choose a model	Selects the model whose versions are shown.	`GET /v1/models`	LLM readers
New version	Drawer with Version (required), Licence (SPDX) (for example `Apache-2.0`), Weights (JSON `source`, `digest`, `size_bytes`, required) and Capabilities; Create registers the version as `draft`.	`POST /v1/models/{model_id}/versions`	portal: `tenant_admin`; server: `tenant_admin`, `platform_admin`
Request approval (row menu)	Opens an approval request for a `draft` version (status `pending_approval`) and shows the answer with its `approval_id`.	`POST /v1/models/{model_id}/versions/{version}/approval`	portal: `tenant_admin`; server: `tenant_admin`, `platform_admin`
Roll out (row menu)	Form with Canary percent (default 10, from 1 to 100) and Reason (both required). 100 publishes the version as `active`; less starts a canary on that share of the traffic.	`POST /v1/models/{model_id}/versions/{version}/rollout`	portal: `tenant_admin`; server: `tenant_admin`, `platform_admin`
Row click	Drawer with the record of the version.	none	LLM readers
Refresh button	Reads the versions again.	`GET /v1/models/{model_id}/versions`	LLM readers
Run (Roll back)	After the confirmation "Roll back? This sensitive action is recorded in the audit log.", aborts the running canary or restores the previous active version.	`POST /v1/models/{model_id}/rollback`	portal: `tenant_admin`; server: `tenant_admin`, `platform_admin`

Roles

Reading (GET /v1/models/{model_id}/versions, GET /v1/models/{model_id}/rollout): the READ roles of services/control-plane/src/eai/domains/llm/lifecycle.py: tenant_admin, platform_admin, security_officer, finops, developer, auditor, viewer.
Writing (versions, approval request, rollout, rollback): ADMIN of the same file, tenant_admin and platform_admin. The portal shows the buttons only to ROLES.modelWriters of portal/src/lib/kit.ts, that is tenant_admin; other roles see "Requires one of these roles" instead of the Roll back form.
Approval: the request is decided by tenant_admin or security_officer; its requester cannot decide it.
Every route needs a tenant (tenant_required otherwise).

Typical tasks

Publish a first version

Choose the model. Select it in Choose a model. Expected result: the tabs Versions and Rollout state. If it fails: "No model registered" means you must register the model first in the Models registry.
Register the version. Click New version, type Version and Licence (SPDX), and fill Weights, so that the published weights can be verified later:
```
{"source": "https://<models-host>/llama/1.0.0", "digest": "sha256:<64-hex>", "size_bytes": 16000000000}
```
<64-hex>: the SHA-256 of the weights, 64 lowercase hexadecimal characters. The source starts with https://, oci://, hf://, s3:// or registry://. Expected result: toast Created, a row with Status draft. If it fails: "The model version is invalid: <fields>." names the wrong fields.
Request the approval. Row menu > Request approval. Expected result: the answer shows pending_approval and an approval_id. If it fails: "The model version is in state <status>, this transition is not allowed." means the version is not draft.
Have it approved. A tenant_admin or security_officer other than you approves it in the Approvals inbox. Expected result: the approval is approved. If it fails: an approval can only be requested on a draft version; when it is rejected, register a new version.
Publish. Row menu > Roll out, Canary percent 100, a Reason, then Roll out. Expected result: Status active, and Rollout state shows it as active_version. If it fails: "Version <version> has no granted approval: it cannot be published."

Run a canary, then roll back

Start the canary. On an approved version, Roll out with Canary percent 10 and a Reason, so that one caller in ten gets the new version (the same caller always gets the same version). Expected result: Status canary, Rollout state shows canary_version and canary_percent 10. If it fails: "Model <model_id> has no active version: a canary needs a baseline, publish at 100 percent first."
Roll back if needed. In Rollout state, type a Reason in Roll back, click Run and confirm. Expected result: the canary version becomes rolled_back and the active version keeps all the traffic. If it fails: "Model <model_id> has no previous version to roll back to."

Troubleshooting

Symptom	Cause	Fix
"The model version is invalid: `<fields>`." (`model_version_invalid`, 422)	Wrong `version`, licence, `weights.source`, `weights.digest` or `weights.size_bytes`.	Fix the fields named: digest `sha256:` plus 64 hexadecimal characters, size above 0, licence SPDX.
"Version `<version>` of model `<model_id>` already exists." (`model_version_exists`, 409)	Duplicate version label.	Use a new Version.
"The model version is in state `<status>`, this transition is not allowed." (`model_version_state`, 409)	Approval requested on a version that is not `draft`, or rollout of the already active version.	Check Status before the action.
"Version `<version>` has no granted approval: it cannot be published." (`model_version_not_approved`, 403)	No approved approval for this version.	Request the approval and have it decided.
"Model `<model_id>` has no active version: a canary needs a baseline, publish at 100 percent first." (`model_rollout_no_baseline`, 409)	Canary without active version.	Publish a first version at 100.
"Model `<model_id>` has no previous version to roll back to." (`model_rollback_unavailable`, 409)	Nothing to roll back.	No action needed, or publish another version.
"Parameter `canary_percent` is invalid." (`parameter_invalid`, 422)	Canary percent outside 1 to 100.	Type an integer from 1 to 100.
Weights digest column empty	The list returns the digest in the flat field `weights_digest`, while the column reads `weights.digest`.	Open the row drawer to read `weights_digest`.
"Requires one of these roles" instead of Roll back, no New version button	Your role is not `tenant_admin`.	Ask a tenant administrator.

What the screen shows​

Actions​

Roles​

Typical tasks​

Publish a first version​

Run a canary, then roll back​

Troubleshooting​

Related pages​