What should you version besides the model file?
A model’s behavior comes from more than its weights. Version the pieces together, or you cannot explain a change in results.
| Item | Why it needs a version |
|---|---|
| Training data or snapshot | Different data gives a different model |
| Code and configuration | Hyperparameters and preprocessing change outputs |
| Prompts | A reworded prompt can change results as much as new weights |
| Evaluation set | A score is only comparable on the same test |
| Dependencies and environment | Library upgrades shift numerics |
| Model ID or registry entry | The thing the application actually calls |
Every prediction should log the version that made it. Then an audit question, “which model approved this?”, has an answer.
How do you version a hosted model?
With an API model you control the model string and little else. Pin the exact model ID you evaluated, store it with each result, and treat a change to it as a release that needs a fresh test run, not a config tweak. Vendors retire models and features on set dates: Anthropic’s fast mode page lists the Opus 4.8 fast mode removal date as 30 November 2026, after which requests that ask for it return an error (Anthropic, fast mode, read 19 November 2026). A dated list of the versions you depend on tells you what to migrate and when. See model portability for keeping the switch cheap.
How do we handle model versions and migrations?
We review retrieval systems for clients and teams, and one finding we raise is an embedding model with no version recorded. In our review checklist the fix is an embedding_model_version column from day one and a planned re-embedding migration, because models get deprecated and similarity scores across versions are meaningless. A model swap that looks like one line of config can invalidate a stored index.
For hosted chat models, we publish what changed when the model string moves, for example in what breaks when you switch to Claude Fable 5.2, where editing an earlier turn now returns an error, and Fable 5.2 reads thinking blocks from older models but only Fable 5.2 and Mythos 5.2 can read its own. A new version is a migration with a test run, not a silent upgrade.
How do you roll back a model?
Keep the previous version deployable until the new one has run in production without regressions. Shift a small share of traffic first, as in a canary deployment, compare against the old version on the same evaluation set and watch for model drift afterwards. A version you cannot redeploy is a log entry, not a rollback plan. Wire the switch to a flag, so reverting is a config change and not a rebuild.