Register and promote a model

A named version line across runs — which model is in production, and which run produced it

sf model register alice/support-agent --run run-4f2a91 --notes "kl 0.01, 500 steps"
sf model promote alice/support-agent@3
sf model ls

A run id is a fact about an experiment. A model version is a decision — this is the one we are willing to serve. Registering turns the first into the second.

Without it, “which model is in production right now?” and “which run produced the previous version, and who promoted it when?” are answerable only by somebody who remembers a run id. The registry turns “I ran 300 jobs” into “we have 5 models in use”.

Three kinds of version, three jobs

A platform ends up with three things called “version”. They do not overlap:

Concept	Attached to	Answers
Artifact	One run	What this training run produced
Model version (this page)	One named model	Which models we have, and which version each is on
Deployment revision	One deployment	What configuration this live service is running

Canary and rollback live at the deployment revision layer; the registry does not duplicate them — two places able to express “which one is running” would fork immediately.

Using it

# train → export → register as a new version (numbers auto-increment; no naming step)
sf export <RUN_ID>
sf model register qa-assistant --run <RUN_ID> --notes "new data mix"

# look at the version line
sf model ls                    # every model, and which version each runs
sf model ls alice/qa-assistant # the full version line for one model

# promote / retire
sf model promote alice/qa-assistant 3
sf model archive alice/qa-assistant 2

Base models and externally supplied weights belong on the line too, otherwise the first entry is missing:

sf model register qa-assistant --path /shared/models/qwen-base --notes "base model"

Deployments follow the registry

Pick “model registry” as a deployment’s source and leave the version empty to follow production:

{ "kind": "model", "model": "alice/qa-assistant" }

Swapping models then only takes sf model promote — the deployment never needs to know which training run is behind it. Pin a specific one with "version": 3.

Relationship to the evaluation gate

Registering a version requires that the training run passed its evaluation gate (when one was declared). The registry is an asset catalogue; entering a run that explicitly fell short makes the gate’s verdict pointless. Admins can override (audited).

Every version on the line carries the verdict from its training run — a number on a version line without an evaluation behind it is just a path.

Versions are immutable: a version pins a run id and a weight path. To change weights, register a new version. If a version already referenced by a deployment could change content, “which version is live” would stop being an answerable question.

Exactly one production version at a time: promoting a new one archives the previous. With two marked production, the reason this table exists is gone.