Why Version Models
Every deployed model needs a license plate
An unversioned model is a rumor: nobody can say what's serving, what changed, or how to go back. Model versioning gives every artifact an immutable identity so production is auditable and reversible.
What you will learn
- Explain why models must be versioned like software
- Describe what makes a version immutable
- List the pieces that define a version's identity
What is this?
Model versioning assigns every trained model an immutable, traceable identity — name, version number, content hash, recipe and state — so that at any moment you can say exactly what is serving, how it was built, and how to restore a previous one. It is the difference between 'model_final_v2.pkl on my laptop' and a governed asset.
Why do you need it?
- Production incidents demand an answer to 'what was serving and how do we revert it?'
- A reproducible retrain is only useful if the new version is distinctly addressable.
- Auditors, reviewers and downstream consumers need unambiguous references to an exact artifact.
- Multiple versions in flight (canary, champion, shadow) only make sense if versions are distinguishable.
Mental model
Versioned releases of a book
Model versions
A publishing house never prints 'the book — latest'. Editions carry ISBNs, print dates and revision notes. A model version is the ISBN: exact, immutable, and retriable long after it stopped shipping.
How it works
- Training produces bytes plus metadata (recipe, metrics, data ref).
- The artifact is written immutably and receives a version number and content hash.
- Metadata records: source run, data version, code commit, owner, evaluation evidence.
- The registry indexes versions and their states (staging, production, archived).
- Deployments reference version numbers; serving and monitoring attribute traffic to versions.
A versioned model's immutable identity chain.
In production
- A bank serves model_v14 while v15 canary runs at 5%; both are addressable registry versions.
- An incident rolls the canary back by pointing serving at version v14's artifact URI.
- A compliance query lists every version that served loan decisions in the last year.
Best practices
- Make version identity equal to content: number only increments on new bytes.
- Never overwrite a version — ship version n+1 instead.
- Attach the promotion gate evidence to the version record.
- Keep version history forever; retention applies to states, not to history.
Common mistakes
- Reusing the same filename for each retrain ('model.pkl' forever).
- Versioning in the filename string without a machine-readable registry.
- Overwriting a version by accident, breaking rollback.
- Versioning the artifact but not the recipe — a number with no story.
Debugging tips
- 'Can't tell which model served this request' — the version tag is missing from serving logs.
- 'Same version, different behavior' — the artifact bytes or its recipe drifted without a new version.
Interview checkpoint
Quick quiz
Which property is essential for a model version to support rollback?
Editing a stored model version is an acceptable way to fix a small issue.