Model Persistence

Why Can't We Just Train Every Time?

Imagine you're a baker who has spent six months perfecting a sourdough recipe. Every morning, you know exactly how long to prove the dough, how much flour to use, and what temperature the oven needs. That knowledge lives in your head.

Now imagine you get amnesia every night. Each morning, you'd have to re-learn everything from scratch—six months of experiments, repeated daily, just to bake one loaf.

From Training to Serving

Model persistence bridges two very different worlds: training (slow, expensive, infrequent) and serving (fast, lightweight, continuous). The pipeline has six stages. Tap each one:

The Gate Before Saving

Training produces a model, but that doesn't mean it's good enough to ship. Before serialising, you evaluate the candidate on a held-out test set and compare its metrics against predefined thresholds and the currently deployed baseline.

The evaluation gate checks two things: (1) does the candidate meet absolute thresholds—minimum acceptable values for each metric? And (2) does it match or beat the baseline—the model currently in production?

import joblib
from sklearn.metrics import accuracy_score, precision_score, recall_score

# --- Define the gate ---
THRESHOLDS = {'accuracy': 0.88, 'precision': 0.70, 'recall': 0.65}
BASELINE   = {'accuracy': 0.90, 'precision': 0.72, 'recall': 0.68}

# --- Evaluate candidate on held-out test set ---
y_pred = candidate_model.predict(X_test)
results = {
    'accuracy':  accuracy_score(y_test, y_pred),
    'precision': precision_score(y_test, y_pred),
    'recall':    recall_score(y_test, y_pred),
}

# --- Gate logic: must pass BOTH checks ---
meets_thresholds = all(results[m] >= THRESHOLDS[m] for m in THRESHOLDS)
beats_baseline   = all(results[m] >= BASELINE[m]   for m in BASELINE)

if meets_thresholds and beats_baseline:
    joblib.dump(candidate_model, 'model_v1.3.0.pkl', compress=3)
    print("PASS: Model serialised as v1.3.0")
else:
    print("FAIL: Model did not clear the gate")
    for m in results:
        flag = "  ✓" if results[m] >= THRESHOLDS[m] else "  ✗"
        print(f"{flag} {m}: {results[m]:.3f}  (threshold {THRESHOLDS[m]}, baseline {BASELINE[m]})")

Saving: From Memory to Disk

A trained model lives in your computer's RAM as a complex web of Python objects—arrays of weights, configuration dicts, fitted parameters. When the programme ends, RAM is wiped clean. Serialisation converts that in-memory object into a byte stream that can be written to a file.

import joblib
from sklearn.ensemble import RandomForestClassifier

# Train the model (the expensive part)
model = RandomForestClassifier(n_estimators=200)
model.fit(X_train, y_train)

# Serialise to disk
joblib.dump(model, 'model_v1.2.3.pkl', compress=3)
# compress=3 shrinks file size with minimal speed cost

joblib.dump() does two things: it serialises the Python object into bytes, and it optionally compresses those bytes (like zipping a file) before writing to disk. The result is a single .pkl file, typically tens of megabytes for a scikit-learn model.

Why Version Your Models?

Versioning your serialised models (e.g. model_v1.2.3.pkl) means you can instantly roll back to a known-good version, compare performance across versions, and keep an audit trail of what changed and when. It also enables hot-swapping: loading a new model version into the serving layer while the old one continues handling requests, with zero downtime.

The Model's Passport

A .pkl file on its own is a black box—it contains the learned parameters, but nothing about where it came from, how well it performed, or what it needs to run. In production, you version not just the model weights but a metadata bundle that makes every artefact self-documenting.

A well-structured metadata card typically includes:

import json, time, hashlib, joblib, sklearn

# --- Build the metadata bundle ---
metadata = {
    "version":        "1.3.0",
    "trained_at":     time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime()),
    "dataset":        "churn_q1_2025.csv",
    "dataset_hash":   hashlib.sha256(raw_bytes).hexdigest(),
    "algorithm":      type(model).__name__,
    "hyperparams":    model.get_params(),
    "metrics":        results,       # from the eval gate
    "dependencies":  {"scikit-learn": sklearn.__version__, "joblib": joblib.__version__},
}

# --- Save model + metadata as a versioned pair ---
joblib.dump(model, "model_v1.3.0.pkl", compress=3)
with open("model_v1.3.0_meta.json", "w") as f:
    json.dump(metadata, f, indent=2)

Loading: From Disk Back to Memory

When it's time to make predictions, you load the saved file back into RAM. This is deserialisation—reconstructing the full model object from the byte stream.

import joblib

# Deserialise — reconstruct the model from disk
model = joblib.load('model_v1.2.3.pkl')

# Predict in milliseconds, no retraining needed
prediction = model.predict(new_customer_data)

When Models Go Stale

A model trained on last year's data may not reflect today's reality. Customer preferences shift, markets change, and new patterns emerge. This is called model drift, and it's why persistence isn't a one-time event—it's part of a cycle.

Each iteration through this cycle produces a new versioned artefact on disk—but only if it passes the evaluation gate. The serving layer loads the latest approved version while older versions remain available for rollback.

Quick Comprehension Check

The Complete Picture

Model persistence is the practice of serialising a trained, evaluated model to disk so it can be loaded and served independently of the training process. This single idea unlocks: