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.
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
- Find every model name in your config.
- 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.
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})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.