Model versioning

On this page 8

Model versioning is the practice of giving every trained machine learning model an immutable, uniquely identified version that is linked to the exact code, data, configuration and environment that produced it. In AI infrastructure, it is the foundation for reproducibility, safe deployment and rollback, because a model in production is only trustworthy when a team can say precisely which artifact is running and how it was built.

Model versioning differs from ordinary source control: a model is a large binary artifact whose behavior depends on data and training randomness, so a code commit alone cannot describe it.

What a model version must capture

A complete model version captures every input that can change model behavior, not only the weights file. If any of these elements is missing, a team cannot rebuild the model or explain why two versions behave differently.

ComponentWhat is storedWhy it matters
Weights artifactSerialized parameters with a content hashProves which exact file is served
Training codeCommit identifier of the repositoryLinks behavior to implementation
Dataset snapshotDataset version or hash of each splitData changes alter results silently
HyperparametersLearning rate, batch size, epochs, seedsRequired to repeat the training run
EnvironmentContainer image, library and driver versionsFramework updates change numerics
Evaluation resultsMetrics on fixed benchmark setsBasis for promotion decisions
LineageParent model, base checkpoint, adaptersTraces fine-tuned derivatives
Components recorded for each model version

The content hash, typically SHA-256 of the artifact, is the most reliable identity because it changes whenever a single byte changes. Human-readable labels are then mapped to hashes, never the other way around, so that a version label can never point to two different files.

Version identifiers and naming schemes

Teams use several identifier schemes in parallel, each answering a different question. A sequential number is easy to discuss, a hash is exact, and a semantic version communicates compatibility to consumers of the model.

SchemeExampleStrengthWeakness
Sequential numberfraud-model v14Simple orderingSays nothing about compatibility
Semantic versioning2.3.0Signals breaking changesNeeds agreed rules for models
Content hashsha256:9f2c…Exact and tamper evidentNot human-friendly
Date-stamped releasemodel-2026-11-01Shows recency clearlySeveral builds per day collide
Alias or stage labelproduction, stagingStable endpoint for clientsMoves over time, not reproducible
Common model version identifier schemes

For models, a practical semantic rule is: major for a changed input or output schema, minor for retraining that improves metrics with the same interface, and patch for fixes such as calibration or packaging. Hosted large language model providers follow a similar idea with dated model snapshots that stay fixed, alongside moving aliases that point to the newest snapshot.

How model versioning fits into MLOps

Model versioning connects experiment tracking, the model registry and model deployment into one traceable chain. Experiment tracking records many candidate runs; the best run is registered as a version; deployment references that version by identifier; and model monitoring reports metrics against it.

A model registry is the usual system of record. It stores version metadata, links to the artifact in object storage, and a stage or alias such as candidate, staging, production or archived. Promotion between stages is a controlled event that should require evaluation evidence and, in regulated settings, a recorded approval.

The table below separates model versioning from closely related practices that are often confused with it.

PracticeMain objectQuestion it answers
Model versioningTrained model artifact and lineageWhich exact model is this
Data versioningDatasets and their splitsWhich data trained or tested it
Experiment trackingIndividual training runsWhich settings produced which metrics
Model registryCatalog of registered versionsWhich version is approved for which stage
Code version controlSource filesWhich implementation was used
Model versioning compared with related practices

Deployment patterns that depend on versions

Safe release patterns require two versions to coexist, which is only possible when each is precisely identified. Model serving platforms and inference servers usually load models by name and version, so traffic can be split, compared and reversed.

PatternHow versions are usedBest suited for
Shadow deploymentNew version receives copied traffic, outputs not returnedValidating behavior without user risk
Canary releaseA small share, often 1 to 10 percent, goes to the new versionGradual rollout with fast rollback
A/B testTraffic split to measure business metricsComparing user impact
Blue-green switchFull traffic moves between two versions at onceSimple and fast reversal
Pinned versionClient requests a fixed version identifierReproducible downstream pipelines
Release patterns and their use of model versions

Rollback should be a pointer change, not a rebuild. If the previous artifact, its container image and its configuration are still stored, reverting takes seconds; if any piece must be retrained or rebuilt, rollback becomes an incident.

Versioning large language models and adapters

Large language model systems add new kinds of versioned artifacts beyond the base weights. A deployed assistant may combine a base checkpoint, a LoRA adapter, a quantized variant, a tokenizer, a system prompt and a retrieval index, and any of these can change outputs.

Good practice treats the whole serving configuration as a versioned bundle. A quantized 4-bit build of the same checkpoint is a separate version, because quantization changes numerical behavior; a revised prompt template is also a release that deserves its own identifier and evaluation. Model routing and model fallback rules should reference explicit versions, not moving aliases, so that incidents can be traced.

Common pitfalls in model versioning

Most failures come from versioning the weights but not their context. The following issues appear repeatedly in production teams.

  • Overwriting artifacts in place, for example saving a new file as model-latest, which breaks traceability.
  • Unversioned training data, so a retrained model cannot be compared fairly with the previous one.
  • Ignoring preprocessing code, which causes training and serving skew even with correct weights.
  • Relying on nondeterministic training without recording seeds, making exact reproduction impossible.
  • Deleting old versions too early, leaving no artifact to roll back to or to show an auditor.

Regulatory frameworks increase the stakes. Rules such as the EU AI Act expect technical documentation and logging for high-risk systems, which in practice means a team must show which model version produced a given decision and what data it was trained on.

A plain-language summary

Model versioning is like keeping dated editions of a book. Each edition comes with the drafts and notes used to make it. Every time an AI model is trained again, it gets a new label that never changes. It also gets a record of what went into it.

This answers simple but vital questions. Which model is running right now? What changed since last month? How can the team go back if the new one misbehaves? Without versioning, a team cannot reliably fix, compare or explain its own AI.

An example from practice

A payments company retrains its fraud detection model every two weeks on fresh transaction data. Each run is logged with its dataset snapshot, code commit and container image, and the best candidate is registered as version 37 with a content hash. The release pipeline first runs version 37 in shadow mode for three days, then sends 5 percent of traffic to it as a canary while version 36 keeps the rest.

On the second day of the canary, monitoring shows false declines rising from 0.8 to 1.6 percent for cards issued in one region. The on-call engineer moves the production alias back to version 36 in under a minute. Because version 37 records its exact data snapshot, the data team quickly finds a broken country code mapping in the new training data. Version 38 fixes the mapping and passes the same canary, and the audit log shows exactly which version scored every transaction during the incident.