Model Versioning

Model versioning records the complete behavior that may be served or audited: artifact, code, data, preprocessing, thresholds, environment, evaluation evidence, approval status, and deployment target. Versioning only the weight file is not enough for rollbacks.

The promotion lifecycle

A candidate model is registered after training, compared against baselines, approved or rejected, and promoted through environments. The registry entry should point back to experiment tracking and dataset versioning records, then forward to model-serving deployments.

The version is the join key for the whole system: monitoring, incident response, and audits all reference it, so it must be immutable once approved and never overwritten in place.

flowchart TD
  Train[Training run] --> Register[Register candidate version]
  Register --> Evaluate[Evaluate against baseline and gates]
  Evaluate --> Approve[Approve or reject]
  Approve --> Canary[Deploy to canary]
  Canary --> Prod[Promote to production]
  Prod --> Rollback[Roll back to a prior version on regression]
  Rollback --> Prod

What a version pins

A servable version is more than a weight file. Each of these can change behavior independently, so each is part of the version:

Component	Why it is pinned
Model artifact and hash	the exact weights that produce scores
Code commit	inference and preprocessing logic
Dataset version	what the model learned from
Feature pipeline version	how raw inputs become model inputs
Threshold / decision config	where scores turn into actions
Evaluation report	the evidence the version was approved on
Environment	libraries and hardware that affect numerics

Artifact: Registry Entry

model_version:
  name: fraud-scorer
  version: 42
  artifact_uri: "s3://ml-artifacts/fraud/42/model.pkl"
  artifact_sha256: "2c8f..."
  code_commit: "9b51c0e"
  dataset: "fraud_training:2026-07-11.v3"
  feature_pipeline: "features:v19"
  threshold_config: "thresholds:v8"
  eval_report: "s3://ml-reports/fraud/42.html"
  approval:
    status: approved_for_canary
    approver: risk-ml-lead

The version is immutable once approved. If a threshold changes, create a new behavior version or a separately versioned threshold config that the serving contract records.

Failure Modes

Versioning fails when models are overwritten in place, when preprocessing lives only in code, or when labels and thresholds are excluded from lineage. In regulated or high-risk systems, missing version links turn an incident into an audit problem.

Connections

• Rollbacks depend on prior versions being immutable and redeployable.
• CD for ML gates promotion on the evaluation evidence attached to a version.
• Model Serving records which version answered each request, closing the loop with monitoring.

References

• MLflow Models documentation
• DVC: Versioning Data and Models

Nav

Section — ML Engineering and MLOps

← Dataset Versioning Evaluation Datasets →