Introduction

A Machine Learning project rarely produces only one model. Teams experiment with algorithms, features, hyperparameters, datasets, decision thresholds, preprocessing strategies, and dependency versions. Each experiment may produce a different model artifact.

Saving these artifacts with names such as model-final.pkl, model-final-new.pkl, or best-model-latest.pkl does not provide reliable version control. The names do not explain which data, code, configuration, metrics, or environment created the model.

Model version control provides every meaningful model release with a unique and traceable identity. It connects the model artifact to its training run, data version, source revision, feature logic, parameters, metrics, environment, approval status, deployment history, and monitoring evidence.

Learning Objectives

Prerequisites

python -m pip install mlflow dvc scikit-learn joblib pandas numpy

What Is Model Version Control?

Model version control is the systematic management of model artifacts and every behavior-changing asset associated with them. It ensures that teams can identify exactly which model was created, evaluated, approved, deployed, monitored, or retired.

Why Version Models?

Git Versioning vs Model Versioning

Experiment, Candidate, Version, and Release

Model Version Identifiers

A version identifier should uniquely identify an immutable model artifact. It should not depend on a mutable label such as latest.

Semantic Versioning for Models

Semantic versioning uses the form MAJOR.MINOR.PATCH. ML teams may adapt the meaning of each segment, but the policy must be documented and applied consistently.

Immutable Model Artifacts

After a model version is registered or approved, its artifact content should not be replaced. Any changed model, metadata, preprocessing, or threshold should become a new traceable version.

Calculate an Artifact Checksum

import hashlib
from pathlib import Path


def calculate_sha256(
    file_path
):
    file_path = Path(
        file_path
    )

    if not file_path.is_file():

        raise FileNotFoundError(
            f"Artifact not found: {file_path}"
        )

    hasher = hashlib.sha256()

    with open(
        file_path,
        "rb"
    ) as artifact_file:

        while True:

            block = artifact_file.read(
                1024
                *
                1024
            )

            if not block:
                break

            hasher.update(
                block
            )

    return hasher.hexdigest()


artifact_checksum = calculate_sha256(
    "artifacts/customer_churn_pipeline.joblib"
)


print(
    artifact_checksum
)

Verify Artifact Integrity

def verify_artifact_checksum(
    artifact_path,
    expected_checksum
):
    actual_checksum = calculate_sha256(
        artifact_path
    )

    if actual_checksum != expected_checksum:

        raise ValueError(
            "Model artifact checksum "
            "verification failed."
        )

    return {
        "verified": True,
        "sha256": actual_checksum
    }

Model Metadata

import json
import platform
from pathlib import Path

import joblib
import numpy as np
import pandas as pd
import sklearn


metadata = {
    "model_name": (
        "customer-churn-classifier"
    ),
    "model_version": "1.0.0",
    "artifact_file": (
        "customer_churn_pipeline.joblib"
    ),
    "artifact_sha256": (
        artifact_checksum
    ),
    "run_id": (
        "replace-with-training-run-id"
    ),
    "code_version": (
        "replace-with-source-revision"
    ),
    "training_data_version": (
        "replace-with-training-data-version"
    ),
    "validation_data_version": (
        "replace-with-validation-data-version"
    ),
    "test_data_version": (
        "replace-with-test-data-version"
    ),
    "feature_definition_version": "1.0.0",
    "input_schema_version": "1.0.0",
    "output_schema_version": "1.0.0",
    "decision_threshold": 0.60,
    "python_version": (
        platform.python_version()
    ),
    "numpy_version": np.__version__,
    "pandas_version": pd.__version__,
    "scikit_learn_version": (
        sklearn.__version__
    ),
    "joblib_version": (
        joblib.__version__
    ),
    "lifecycle_status": "candidate",
    "approval_status": "pending",
    "intended_use": (
        "Retention-review prioritization"
    ),
    "prohibited_use": (
        "Automatic denial or reduction "
        "of customer service"
    )
}


metadata_path = Path(
    "artifacts/model_metadata.json"
)


with open(
    metadata_path,
    "w",
    encoding="utf-8"
) as metadata_file:

    json.dump(
        metadata,
        metadata_file,
        indent=4
    )

Model Lineage

Model lineage explains where a model came from and how it was produced.

Version the Data Reference

Reproducing a model requires the exact training, validation, and testing data or immutable references capable of resolving those datasets.

Version Feature Definitions

Version the Environment

python==3.12.*
numpy==replace-with-tested-version
pandas==replace-with-tested-version
scikit-learn==replace-with-tested-version
joblib==replace-with-tested-version

What Is a Model Registry?

A model registry is a controlled system for organizing registered model identities, immutable versions, metadata, lineage, aliases, lifecycle status, approvals, and deployment relationships.

Track an Experiment with MLflow

import mlflow
import mlflow.sklearn


mlflow.set_experiment(
    "customer-churn-training"
)


with mlflow.start_run() as run:

    mlflow.log_param(
        "algorithm",
        "logistic-regression"
    )

    mlflow.log_param(
        "decision_threshold",
        0.60
    )

    mlflow.log_param(
        "random_state",
        42
    )

    mlflow.set_tag(
        "code_version",
        "replace-with-source-revision"
    )

    mlflow.set_tag(
        "training_data_version",
        "replace-with-data-version"
    )

    mlflow.set_tag(
        "intended_use",
        "retention-review-prioritization"
    )

    mlflow.log_metrics(
        calculated_validation_metrics
    )

    mlflow.sklearn.log_model(
        sk_model=model_pipeline,
        name="model"
    )

    training_run_id = run.info.run_id


print(
    training_run_id
)

Register an MLflow Model

import mlflow


model_uri = (
    f"runs:/{training_run_id}/model"
)


registered_version = (
    mlflow.register_model(
        model_uri=model_uri,
        name=(
            "customer-churn-classifier"
        )
    )
)


print(
    registered_version.name
)


print(
    registered_version.version
)

Add Model-Version Metadata

from mlflow import MlflowClient


client = MlflowClient()


model_name = (
    "customer-churn-classifier"
)


model_version = (
    registered_version.version
)


client.set_model_version_tag(
    name=model_name,
    version=model_version,
    key="validation_status",
    value="passed"
)


client.set_model_version_tag(
    name=model_name,
    version=model_version,
    key="input_schema_version",
    value="1.0.0"
)


client.set_model_version_tag(
    name=model_name,
    version=model_version,
    key="decision_threshold",
    value="0.60"
)


client.set_model_version_tag(
    name=model_name,
    version=model_version,
    key="approval_status",
    value="pending"
)

Use Model Aliases

An alias is a movable reference to a selected immutable model version. The version remains unchanged when the alias moves.

client.set_registered_model_alias(
    name=model_name,
    alias="candidate",
    version=model_version
)

candidate_version = (
    client.get_model_version_by_alias(
        name=model_name,
        alias="candidate"
    )
)


print(
    candidate_version.version
)

Promote an Approved Version

def promote_approved_model(
    client,
    model_name,
    model_version,
    approval_status
):
    if approval_status != "approved":

        raise ValueError(
            "Only an approved model "
            "can be promoted."
        )

    current_champion = None

    try:
        current_champion = (
            client.get_model_version_by_alias(
                name=model_name,
                alias="champion"
            )
        )

    except Exception:
        current_champion = None

    if current_champion is not None:

        client.set_registered_model_alias(
            name=model_name,
            alias="rollback",
            version=(
                current_champion.version
            )
        )

    client.set_registered_model_alias(
        name=model_name,
        alias="champion",
        version=model_version
    )

    client.set_model_version_tag(
        name=model_name,
        version=model_version,
        key="approval_status",
        value="approved"
    )

Load a Registered Version

import mlflow.pyfunc


registered_model_uri = (
    "models:/"
    "customer-churn-classifier"
    "@champion"
)


loaded_model = mlflow.pyfunc.load_model(
    registered_model_uri
)


prediction_output = loaded_model.predict(
    inference_frame
)

Compare Model Versions

def compare_model_versions(
    candidate_metrics,
    champion_metrics
):
    metric_names = sorted(
        set(
            candidate_metrics
        )
        |
        set(
            champion_metrics
        )
    )

    comparison = []

    for metric_name in metric_names:

        candidate_value = (
            candidate_metrics.get(
                metric_name
            )
        )

        champion_value = (
            champion_metrics.get(
                metric_name
            )
        )

        difference = None

        if (
            candidate_value is not None
            and champion_value is not None
        ):
            difference = (
                candidate_value
                -
                champion_value
            )

        comparison.append(
            {
                "metric": metric_name,
                "candidate": candidate_value,
                "champion": champion_value,
                "difference": difference
            }
        )

    return comparison

Promotion Is Not Copying

A controlled promotion should update metadata or an alias so that a deployment workflow references an already verified immutable artifact.

Model Lifecycle States

Approval Record

{
    "model_name": "customer-churn-classifier",
    "model_version": "1.0.0",
    "registry_version": "replace-with-registry-version",
    "approval_status": "approved",
    "approved_use": "Retention-review prioritization",
    "approval_reference": "replace-with-approved-reference",
    "approval_conditions": [
        "Use only within the documented retention workflow",
        "Maintain human review",
        "Monitor input quality and delayed performance"
    ],
    "rollback_version": "replace-with-approved-rollback-version"
}

Roll Back a Model Version

rollback_version = (
    client.get_model_version_by_alias(
        name=model_name,
        alias="rollback"
    )
)


client.set_registered_model_alias(
    name=model_name,
    alias="champion",
    version=rollback_version.version
)


print(
    "Champion restored to version:",
    rollback_version.version
)

Data Version Control with DVC

DVC can track data and model artifact references through small metadata files committed to Git while the larger content is stored through configured external storage.

git init
dvc init

dvc add data/customer_churn.csv

git add \
  .dvc \
  .gitignore \
  data/customer_churn.csv.dvc

git commit \
  -m "Track customer churn dataset"

Configure DVC Remote Storage

dvc remote add \
  --default \
  model-storage \
  replace-with-approved-remote-location

dvc push

git add .dvc/config
git commit -m "Configure DVC remote"

Restore a DVC-Tracked Artifact

git checkout replace-with-source-revision

dvc pull

Recommended Artifact Structure

model-registry-export/
└── customer-churn-classifier/
    ├── 1.0.0/
    │   ├── model.joblib
    │   ├── metadata.json
    │   ├── input_schema.json
    │   ├── output_schema.json
    │   ├── evaluation_report.json
    │   ├── model_card.md
    │   ├── requirements.txt
    │   └── checksum.sha256
    └── 1.1.0/
        ├── model.joblib
        ├── metadata.json
        ├── input_schema.json
        ├── output_schema.json
        ├── evaluation_report.json
        ├── model_card.md
        ├── requirements.txt
        └── checksum.sha256

Test Model-Version Consistency

import json

import joblib
import numpy as np


def validate_model_version(
    artifact_path,
    metadata_path,
    representative_input,
    expected_probabilities
):
    with open(
        metadata_path,
        "r",
        encoding="utf-8"
    ) as metadata_file:

        metadata = json.load(
            metadata_file
        )

    verify_artifact_checksum(
        artifact_path=artifact_path,
        expected_checksum=(
            metadata[
                "artifact_sha256"
            ]
        )
    )

    model = joblib.load(
        artifact_path
    )

    actual_probabilities = (
        model.predict_proba(
            representative_input
        )[:, 1]
    )

    np.testing.assert_allclose(
        actual_probabilities,
        expected_probabilities,
        rtol=1e-10,
        atol=1e-12
    )

    return {
        "model_version": metadata[
            "model_version"
        ],
        "verified": True
    }

Registry Security

Separation of Duties

Connect Versions to Monitoring

Monitoring events must identify the immutable model version that generated each prediction.

{
    "request_id": "generated-request-identifier",
    "model_name": "customer-churn-classifier",
    "model_version": "1.0.0",
    "registry_version": "17",
    "artifact_sha256": "recorded-artifact-checksum",
    "application_version": "2.3.0",
    "input_schema_version": "1.0.0",
    "decision_threshold": 0.6,
    "prediction": "churned"
}

Version the Complete Release

A production release consists of more than a model version. Record every component that can affect inference behavior.

Retention and Archival

Retire a Model

Responsible Model Versioning

Common Version-Control Mistakes

Recommended Version-Control Workflow

Hands-On Practice

Knowledge Check

Model Version-Control Readiness Checklist

Lesson Summary