# Model Registry and Versioning

A catalogue of trained models with versions, stages, aliases and lineage, making promotion an explicit auditable act.

**Rests on:** Model Serving APIs

**Leads to:** MLflow Tracing

*MLOps and Platform · MLOps*


## Why learn this

Think of a model registry and versioning as a library catalogue for your machine learning models. Without it, you don't know which model is currently answering requests, what data it was trained on, or how to roll back if something goes wrong. This is a foundational skill for any real-world AI project. Mastering it will let you: understand how teams manage models in production, prepare to work with tools like MLflow or Azure ML Studio, implement safe rollback strategies (a core part of release safety), and build trustworthy AI systems where every step is auditable—which is especially crucial in regulated industries like finance and healthcare.


## The intuition

When you train a model, you get a file with numbers—a snapshot of what the model learned. But that file isn't just the model itself; it's also tied to the data it saw, the code that trained it, and the settings used. In a busy team, many people train models—some tweaking a parameter, some using new data—and they all end up with file names like 'final_v2_real' or 'model_20231015_best'. Without a system to track these, chaos ensues: someone deploys a model that was actually a failed experiment, and nobody can tell what's running or how to revert. A model registry is like a formal ledger. It records every model, gives it a unique version, tracks its lineage (data, code, parameters), and lets you tag it as 'staging' or 'production'. With an alias like 'champion', production always points to the current best model, and rolling back is as simple as switching the alias back a version—just like undoing a file edit. The key idea is: it's not just about storing models; it's about making every action—promoting a model, demoting it, comparing versions—explicit, recorded, and reversible. This turns 'trust me, it works' into 'look, here's the proof'.


## An analogy

Imagine you run a busy restaurant with several chefs. Each chef adapts a soup recipe—one adds more salt, another tries a new vegetable. The restaurant serves the same soup daily to customers. Without a system, each chef just grabs whatever version is in the fridge, and customers never know what they'll get. Today might be too salty; tomorrow might be missing a key ingredient. To fix this, you create a recipe book. The book has a master recipe (the 'production' version). Each chef's variation is recorded as a separate page with a version number, notes on what changed, and the date. Before any variation is used for customers, it must be tested and approved, then it gets promoted to the main page. If customers complain about the new version, you can instantly flip back to the previous master recipe. The model registry works the same way: the 'recipe' is the model, the 'chefs' are your data scientists, and the 'customers' are your application users. The analogy stops working when you consider that model versions aren't just a recipe—they also have lineage (what data they were trained on) and can be deployed to many servers simultaneously, which the restaurant can't do. But the core idea—a controlled, reversible, auditable process—applies perfectly.


## Definition

A model registry is a central catalogue that stores every trained model, assigns each a unique version, records its lineage (data, code, parameters), and manages its lifecycle through stages like 'staging' and 'production', making promotion an explicit, auditable act.


## How it connects

You haven't studied any neighbouring topics yet, so this is your first step. It lays the foundation for everything that follows: Model Deployment (how to serve a model), Model Monitoring (how to watch it in production), and Release and Rollback Safety (how to make changes safe). This concept is part of MLOps—the practice of running machine learning systems reliably in production.


## The mathematics

This concept doesn't require heavy mathematics, but it does use a few simple ideas from arithmetic. The first is counting: each version gets a number, and you increment it when you save a new one. For example, `v1`, `v2`, `v3`. The second is comparing: when you test two models, you compare their performance scores to decide which is better. Suppose model A has an accuracy of 85% and model B has 90%—you can see that 90 > 85, so B is better. The registry's job is to keep track of these numbers and the models they belong to. It's not about calculating complex formulas; it's about organizing and retrieving information correctly.

No formula is needed for this concept. The mathematics is just counting, comparing, and ordering numbers—nothing more.


## A worked example

```
Suppose you have three models for predicting customer churn. Version 1 (v1) was trained last month, version 2 (v2) this week, and version 3 (v3) is a candidate you're testing.

Step 1: v1: trained with data from January, accuracy 82%   # This is the first model, stored as v1. It was trained on a specific dataset, and we record its accuracy.
Step 2: v2: trained with data from February (more data), accuracy 87%   # The second model uses newer data, and its accuracy is higher. We can compare: 87 > 82, so v2 is better than v1.
Step 3: v3: trained with data from February but with different parameters, accuracy 85%   # The third model uses the same data as v2 but different settings, and its accuracy is lower: 85 < 87, so v2 is currently the best.
Step 4: Compare: 87 > 85 > 82, so v2 stands out   # By comparing numbers, we decide v2 is the best candidate for production.

Result: Model v2 has the highest accuracy, so we might promote it to production using a registry alias like 'champion'. If later v3 improves to 88%, we can promote v3 instead, but the registry keeps all versions for rollback.
```


## From scratch, in Python

```python
# We'll simulate a simple model registry using a Python dictionary.
# A dictionary is like a book that lets you look up information by a name (key) instead of a position (index).
# For example:
# person = {'name': 'Aisha', 'age': 30, 'city': 'Pune'}
# person['name'] gives 'Aisha'.

# Here, we'll create a registry to store models.
# Each model will be a dictionary with details.

registry = {}  # empty dictionary to hold our models

def add_model(version, data, accuracy, notes):
    # This is a function. It takes inputs, does something, and may return a result.
    # We use it to avoid repeating code.
    model_info = {
        'version': version,
        'data': data,
        'accuracy': accuracy,
        'notes': notes
    }
    registry[version] = model_info  # store it in our dictionary, keyed by version

def get_model(version):
    # Return the model info for a given version.
    return registry.get(version, None)  # .get returns None if key not found

def set_alias(alias, version):
    # Aliases let us have a name like 'current' that points to a version.
    # We'll store aliases in another dictionary.
    aliases[alias] = version

# Create our aliases dictionary (we need to define it before using it)
aliases = {}

# Add some models
add_model('v1', 'Jan', 0.82, 'original model')
add_model('v2', 'Feb', 0.87, 'more data, better')
add_model('v3', 'Feb', 0.85, 'different params')

# Set an alias for production
set_alias('champion', 'v2')

# Find out what is in production
prod_version = aliases['champion']
prod_model = get_model(prod_version)
print('Production model:', prod_model)
# Output: Production model: {'version': 'v2', 'data': 'Feb', 'accuracy': 0.87, 'notes': 'more data, better'}

# Now, if we want to rollback, we just change the alias
set_alias('champion', 'v1')
print('After rollback:', get_model(aliases['champion']))
# Output shows v1
```


## The same thing, with a framework

In practice, you'd use a dedicated tool like MLflow or Azure ML Studio. For example, with MLflow, you might do:
```python
import mlflow

# Log a model with a version
with mlflow.start_run():
    mlflow.log_metric('accuracy', 0.87)
    mlflow.sklearn.log_model(model, 'model')

# Register the model with a name
mv = mlflow.register_model('runs:/<run_id>/model', 'churn_model')

# Set an alias
client = mlflow.tracking.MlflowClient()
client.set_registered_model_alias('churn_model', 'champion', mv.version)
```
Underneath, MLflow is doing exactly what our from-scratch code did: keeping a dictionary-like record of models, versions, and aliases, and storing it in a database.


## What the code does

The code starts by creating an empty dictionary called `registry` to hold the models. A dictionary is a collection that associates keys with values—here, the key is the version string (like 'v1') and the value is another dictionary containing model details. The `add_model` function takes four inputs, builds a dictionary for the model, and stores it in `registry` using the version as the key. The `get_model` function retrieves the model info by version, returning `None` if not found. Next, we create a second dictionary `aliases` to map friendly names like 'champion' to a version. The `set_alias` function updates this mapping. We then add three models, set the alias 'champion' to 'v2', and print the production model. Finally, we change the alias to 'v1' to simulate a rollback and print again. This shows the core idea: the alias is a pointer that can be switched instantly, without changing the underlying models.


## Common misconceptions

**Versioning is just renaming files** — I can just save my model as 'model_v2.pkl' and that's enough.

File names are informal and easily overwritten or lost. A registry provides a controlled, searchable record with metadata (data, code, metrics) and supports aliases and stages. Without it, you can't know if 'model_v2.pkl' is actually the version you think it is. In fact: Versioning is a formal process: each model gets a unique identifier and its lineage is recorded, so you can always trace what it is and how it was produced.

**Aliases are just labels** — An alias like 'champion' is just a nickname; I still have to update all my deployment code to point to the new version.

In a proper registry, the alias is a reference that your deployment reads at runtime. Changing the alias redirects traffic without touching the deployment code. This is what makes rollback instant. In fact: Aliases are dynamic pointers. The deployment code uses the alias; changing the alias changes which model is served, instantly and without redeployment.

**The registry only stores the model file** — A registry is just a database where I put my .pkl or .h5 files.

The model file is only part of the story. The registry stores rich metadata: training data, code version, hyperparameters, evaluation results, and the current stage. This metadata is crucial for debugging and auditing. In fact: A registry stores the model artifact plus a complete record of how it was created, including data and code lineage.

**Staging and production are just words** — Whether a model is in staging or production doesn't matter; it's the same model file.

Stages enforce rules. A model in staging might be exposed to internal testing but not to real users. Promotion to production is an explicit, approved action with an audit trail. This prevents deploying unvalidated models. In fact: Stages are a controlled lifecycle: a model must pass validation before being promoted to production, and every promotion is logged.

**Rollback just means redeploying the old file** — If a new model breaks, I can just go to my backup drive and upload the old one.

That assumes you have a reliable backup, know which file is the old one, and can redeploy quickly. In practice, with a registry, rollback is as simple as changing an alias—no file copying, no downtime. In fact: Because the registry preserves every version and uses aliases, rollback is immediate and reliable—just point the alias back.


## In short

A model registry is a central catalogue that stores every model version, tracks its lineage, and manages its lifecycle through stages and aliases. It makes promotion an explicit, auditable act and enables instant rollback. Without it, you can't know what's running, why, or how to revert—leading to outages and regulatory risk. Always use aliases for production, log everything, and keep every version.


## Where this is used

In practice, every serious AI team uses a model registry. In large language models (LLMs), a registry tracks fine-tuned versions—e.g., a version trained on legal documents vs. a general one. The registry stores the base model version, the fine-tuning dataset, and evaluation scores. Alias 'current' points to the latest safe version; if a new version performs poorly on live traffic, you roll back by changing the alias. In small models on devices (like keyword spotters in phones), the registry keeps track of quantized versions (converted to run on low-power hardware) and their accuracy vs. full-size counterparts. Developers retrieve the right version for each device type. In retrieval-augmented generation (RAG), the registry logs the embedding model version used to index the knowledge base; if the index becomes stale, you know which model version to rerun. In agentic systems that plan and call tools, the registry tracks the agent's policy model and its prompt template version, making it possible to audit what the agent did in production. In everyday applied ML—fraud detection, recommendation, forecasting—the registry is essential: it holds candidate models, lets you compare them on validation data, and promotes the winner. A developer writes code to log models, register them, set aliases, and transition stages. What breaks when done badly: you deploy a model that isn't the one you tested, causing outages. Metrics become untrustworthy because you don't know which model produced them. Auditors cannot trace which data a model used, leading to regulatory fines. Debugging becomes impossible: you can't reproduce a model's behavior without knowing its lineage. A registry prevents all this by making every model's history explicit.


---

Read this on the web: https://basavapurushottam.com/learn-ai/model-registry-and-versioning
