Core ML

Model Versioning

In standard software, version 2.0 is just new code. In ML, version 2.0 is new code, new data, and a new environment. If you don't version all three together, you can never reproduce a broken model to debug it.

An ML Model Version is a strict tuple of exactly three things: the exact Code (Git hash), the exact Data (DVC hash), and the exact Environment (Docker image).

Why Does This Exist?

In traditional software engineering, versioning is simple. If your website breaks, you look at git log, find the bad commit, and revert to the previous code.

If a Machine Learning model breaks in production (e.g., it suddenly starts predicting that every user is fraudulent), looking at git log is useless. The code might not have changed in 6 months! The model broke because the data it was retrained on last night was corrupted. Or because the underlying Python environment updated scikit-learn from version 1.2 to 1.3, which quietly changed how a default parameter works.

Model Versioning solves this by treating a "Model" not just as a file (like model.pkl), but as a strict, immutable triad: Code + Data + Environment.

Think of It Like This

Imagine trying to reproduce a famous restaurant's signature soup.

The Code is the Recipe (the written instructions).
The Data is the specific Ingredients (the exact tomatoes picked on a specific day).
The Environment is the Oven (a specific brand calibrated to a specific temperature).

If you use the exact same Recipe, but you buy cheap tomatoes and use a broken oven, the soup will taste different. To guarantee the exact same soup, you have to version all three things together in one box.

How It Actually Works

To properly version a model, you must version the three pillars simultaneously.

1. Versioning the Code (Git)

This is the easy part. You use Git to version your Python scripts, your ML pipeline DAGs, and your inference API code. Every model trained must be permanently tagged with the exact Git SHA (e.g., git rev-parse HEAD) that produced it.

2. Versioning the Environment (Docker / Poetry)

If you train a model using pandas 1.5 and deploy it on a server running pandas 2.0, it will likely crash. You must version the environment. This means tracking the exact requirements.txt, poetry.lock, or ideally, building a fixed Docker Image for training and inference, identified by its SHA-256 hash.

3. Versioning the Data (DVC)

You cannot store a 50GB CSV file in Git. It will crash the repository. Instead, we use Data Version Control tools (like DVC or LakeFS). DVC hashes the 50GB dataset (creating a unique string like a3f89b...) and uploads the actual data to cheap cloud storage (S3). It then creates a tiny text file in your Git repository (e.g., dataset.csv.dvc) containing just the hash. Now, your Git commit explicitly points to a specific, immutable snapshot of your 50GB dataset.

The Immutable Triad

When a model is saved, the ML Pipeline groups the Git Hash, the Docker Hash, and the DVC Hash together. This tuple is the Model Version. If a regulator asks, "Why did Version 3 deny this loan?", you can check out Git Hash X, download DVC Hash Y, spin up Docker Image Z, and flawlessly reproduce the exact state of the world when the model was trained.

Show Me the Code

Here is how DVC (Data Version Control) works in the terminal to version data alongside code.

1# 1. Add your massive dataset to DVC (not Git!)2dvc add data/training_set_v1.csv3
4# DVC does two things:5# - Uploads the massive CSV to your S3 bucket.6# - Creates a tiny file called 'data/training_set_v1.csv.dvc' containing the hash.7
8# 2. Add the tiny DVC tracker file to Git9git add data/training_set_v1.csv.dvc10git commit -m "Train model v2.0 using the Q3 dataset"11
12# 3. Later, when you need to reproduce the model, you checkout the old code:13git checkout <old-commit-hash>14
15# 4. And tell DVC to pull the exact data that matches this code:16dvc pull17
18# DVC looks at the .dvc file, goes to S3, and downloads the exact 19# 50GB CSV as it existed on that day.

Watch Out For

Relying purely on File Timestamps. Never version data by saying "We trained on the users table as it looked on Tuesday at 5 PM." Databases are mutable. Someone can run an UPDATE query on Wednesday that retroactively changes records from Monday. Unless you are using a strictly append-only event log, timestamps cannot guarantee reproducibility. You must use cryptographic hashes (like DVC) or a time-travel database (like Delta Lake or Snowflake).

The Quick Version

Model Versioning ensures that a machine learning model is completely reproducible for debugging and regulatory compliance.
A model version is not just the code; it is a strict combination of Code, Data, and Environment.
Code is versioned using Git.
Environment is versioned using Docker images or lockfiles.
Data is versioned using tools like DVC (Data Version Control), which store large files in cloud storage but track their hashes in Git.

Related concepts

Model Registry