Area 07 · Deployment · Concept 17 of 20

Model Versioning

Pin exact model versions and record which version served each request.

11–20 · Production levelPhase 5 · Weeks 18–20≈ 30 min

The idea

Model aliases (like "latest") can point to new snapshots over time, and providers deprecate old models on a schedule. If you do not pin, your app’s behaviour can change without any change on your side.

Pin dated or specific model IDs in config, record the model ID returned in each response, and treat a model upgrade like a dependency upgrade: run evals, canary it, then switch. Track provider deprecation dates so you upgrade on your schedule.

For self-hosted and fine-tuned models, version the weights or adapters (with a registry such as Hugging Face Hub or MLflow) and the serving config together.

Why it matters

It makes behaviour changes traceable and model upgrades deliberate.

Words to know

  • Model snapshotA fixed, dated version of a model.

Try it without code

Check your pins

  1. Find every model name in your config.
  2. Look up each on the provider’s models page and note its deprecation date.

Use it in code

Record the served model on every response and alert on unexpected changes.

python
EXPECTED = {"chat": "claude-sonnet-5-5", "router": "claude-haiku-5-5"}

def check_served(feature, response, log):
    served = response.model                       # the API reports which model answered
    log.info("model_served", extra={"feature": feature, "model": served})
    if served != EXPECTED[feature]:
        log.warning("unexpected model", extra={"feature": feature, "expected": EXPECTED[feature], "served": served})
PRACTICE · TICK IT AFTER THIS

Pin every model in your config, log the served model, and write an upgrade checklist (evals → canary → switch).

Common mistakes

  • Using floating aliases in production.
  • Learning about a deprecation from an outage.

Go deeper