Skip to main content
A model lineage collects every trained iteration of one model under a single name, as numbered versions: acme-bot@v1, acme-bot@v2, and so on. Two reserved aliases, production and staging (plus any custom names you invent), point at versions. Promotion moves an alias; it never copies weights. Every alias move is audited: who, from which version, to which version, when, and why. Versions build on the model library: each version is a saved model plus its place in the lineage.

​
Register a training job as a version

When a training job completes, register it into a lineage. The lineage is created on first use, and its first version becomes production automatically; later versions are only served after you promote them.
Useful flags: Without --model, register behaves like veri models save and requires --name. --quiet prints just the version handle (acme-bot@v6) for scripting.

​
Inspect a lineage

--audit N controls how many alias moves are shown (--audit 0 hides the trail); --format json returns the whole lineage, versions, aliases, and audit as one object.

​
Promote

Point an alias at a version. --reason is required and lands in the audit trail. The conventional flow is staging first, production after your team has tested:
The version argument accepts v6 or 6. The alias move and its audit row commit together. What promotion changes in serving. A multi-adapter fleet that serves this lineage follows the production alias: promoting flips its adapter to the new version without a redeploy, and the next request is answered by the new weights. A deployment created from one specific library model (--from-model) is deliberately fixed: it keeps serving the version it was created from until you redeploy it.

​
Roll back

Rollback moves the alias back to the version it pointed at before its last move; fleets follow the same way. The rollback is itself an audited move, so rolling back twice returns to the promoted version. --alias rolls back a different alias; --reason is optional here and defaults to naming the undone move.

​
Pin a version

A pinned version is never purged by retention and its library model cannot be deleted.

​
Retention

Old, unprotected versions are purged by a nightly sweep so storage does not grow forever. Two knobs control the window:
--days 0 is a zero-data-retention opt-in: eligible versions are purged on the next nightly sweep. What is protected. These are never purged, regardless of age:
  • Versions any alias points at (production, staging, or custom).
  • The previous production version, so rollback always has somewhere to go.
  • Pinned versions and versions carrying any tag.
  • Versions a live deployment or fleet adapter is serving.
  • Dataset snapshots pinned by any of the above (and a stream’s newest snapshot, the @latest anchor).
Everything else becomes eligible once it ages out of the window. Age counts from the last time the version was live (the later of its creation and the last time an alias left it), so “30 days” means 30 days since it last mattered, not since training. What “purged” looks like. A purged version keeps its row: the version number, tags, and alias audit remain, but its weights are deleted and its library model can no longer be deployed or attached. A purged dataset snapshot stops resolving (training against it fails); its underlying rows remain in the stream.

​
See which version answered a request

Every request served by a registered version carries its model_version_id in the request log, and in trace metadata when tracing is enabled. Because an alias is a moving pointer, this is how you attribute quality to a version across promotes and rollbacks.

​
Where to go next

Dataset streams

Pin each version to the exact snapshot it trained on.

Custom models

The model library that versions build on.

Observability

Request telemetry and traces, grouped by version identity.