Model versioning and deprecation

What is model versioning and deprecation?

When your application calls a hosted AI model, it sends a model ID: a string such as claude-sonnet-5 or gemini-3.8-flash. Behind that string sits one specific set of trained weights. Model versioning is how the provider tells versions apart and how you choose one. Deprecation is the provider announcing that a version will stop, then switching it off on a date.

Both halves land on you, because your prompts, your output parsers and your evals were all tuned against one version. Two things can go wrong. The model changes under a name that looks the same, so behaviour shifts without anyone on your side touching anything. Or the model disappears: Anthropic's deprecation page says requests to retired models will fail, and OpenAI gives every deprecated model a shutdown date. Think of a supplier who keeps the article number on the label but changes the recipe, and who also discontinues articles with two months' warning.

How providers name and version models

Three providers, three schemes, and the same word does not mean the same thing across them. This is what their pages said in September 2026.

Anthropic. Before the Claude 4.6 generation the ID carried a date, such as claude-sonnet-4-5-20250929, with a shorter alias claude-sonnet-4-5 pointing at the most recent dated snapshot. From 4.6 on the ID is dateless and is itself the pinned snapshot: claude-sonnet-4-6 never changes weights, and an updated model ships under a new ID. Anthropic's docs call the assumption that a dateless ID routes to the newest version a common misconception. Bedrock and Google Cloud use their own ID formats and their own retirement dates for the same models.

OpenAI. Dated snapshots such as gpt-4o-2024-05-13 sit next to plain aliases; the alias gpt-5.6 routes to gpt-5.6-sol. OpenAI has also sold models that were openly moving targets, like chatgpt-4o-latest, and those retire like any other ID: announced 18 November 2025, shut down 17 February 2026.

Google. Gemini uses four labels. A stable ID such as gemini-3.8-flash points at one model that usually does not change. A preview ID may run in production but can be deprecated with two weeks' notice. A latest alias such as gemini-flash-latest is hot-swapped at every release of that line, and experimental IDs are not for production at all. Google's own guidance is that most production apps should use a specific stable model.

The deprecation policies as of September 2026

Read the notice periods below as minimums, and look them up again on the day you plan, because they move.

• Anthropic gives at least 60 days' notice before retiring a publicly released model, by email and on its deprecations page, and dates every active model as "not sooner than" a given day. In practice the gap sits near the minimum: Claude Sonnet 4 and Opus 4 were announced on 14 April 2026 and retired on 15 June 2026.

• OpenAI counts a model as deprecated the moment it is announced, and commits to at least six months for generally available models, three for specialised variants such as Codex, and sometimes two weeks for previews. Its 22 April 2026 announcement retires gpt-4-turbo, gpt-3.5-turbo-0125 and other old snapshots on 23 October 2026; the GPT-5 snapshots from 2025 stop on 11 December 2026.

• Google publishes Gemini shutdown dates as the earliest possible day and promises notice before the exact date is fixed. Previews get at least two weeks, and a breaking swap behind a latest alias gets a two-week email warning. gemini-2.0-flash shut down on 1 June 2026.

What that does to an unprepared integration, with dates. On 13 August 2025 Anthropic told developers that both Claude Sonnet 3.5 snapshots, claude-3-5-sonnet-20240620 and claude-3-5-sonnet-20241022, would retire on 28 October 2025. From that morning every request to those IDs failed. A team with the string hardcoded in a Power Automate flow, and nobody reading the provider's mail, saw no slow decline in quality. They got an error on a workflow that had run untouched for a year. Previews go faster still: gpt-4.5-preview was announced on 14 April 2025 and gone on 14 July 2025.

What changes between versions, even when the name looks the same

A version move is never only a string change. Anthropic's migration guide for Claude Sonnet 5, a model it calls a drop-in upgrade from Sonnet 4.6, still lists all of this.

The tokenizer. Sonnet 5 uses a new one that produces roughly 30 percent more tokens for the same text. The price per token fell, from 3 and 15 dollars to 2 and 10 per million, but the cost of an equivalent request does not fall in proportion, and a max_tokens limit tuned on the old model can now cut output short. Token counts you budgeted on the previous version are wrong on this one.

The API contract. On Claude 4.7 and later, a non-default temperature, top_p or top_k returns a 400 error rather than being ignored. Thinking is on by default on Sonnet 5, so a reply can start with a thinking block, and code that reads content[0].text stops working.

The output and the refusals. The same guide warns that JSON escaping in tool parameters can differ from earlier models, which a real JSON parser survives and a home-made string parser does not. Sonnet 5 also added cybersecurity safeguards Sonnet 4.6 did not have, and a refusal returns HTTP 200 with stop_reason: "refusal". A pipeline that only checks the status code records that as a success and stores an empty answer.

Pinning removes the big jumps, not every movement. Anthropic says the weights behind an ID are fixed, but the serving infrastructure around them, the router, the safety classifiers and the sampling logic, can be updated and sometimes shows as a small behaviour difference on a stable ID. A pin gives you a baseline to test against, not a promise that every answer stays identical.

So a prompt tuned for one version performs quietly worse on the next, a parser built on one output shape throws on another, and if nobody re-runs the eval after the switch neither surfaces until a customer mentions it three weeks later.

Alias versus pinned version: who decides when your behaviour changes

The question is not old model against new model, it is who holds the switch.

With an alias the provider holds it. gemini-flash-latest pointed at gemini-3-flash-preview on 21 January 2026, at gemini-3.5-flash on 19 May 2026 and at gemini-3.8-flash on 2 September 2026: three models behind one string in just over seven months, each swap announced by an email that has to reach the right person. You get the newest model without deploying, and you get its tokenizer, its output habits and its refusal patterns on the provider's calendar rather than yours.

With a pinned version you hold it. Nothing moves until you change the configuration, so you can run the eval first and roll back if the numbers drop. The price is the deadline: a pinned model is a model that will one day stop, and the calendar is now yours.

An alias is fine for a prototype or an internal helper where a slightly different answer costs nothing. Anything with a parser behind it, a cost budget or a promise to a customer belongs on a pinned version. An alias with a nightly eval is a defensible middle road, as long as you stay honest about it: the provider still decides, you only hear about it sooner.

The operating practice

1. Model IDs in configuration, one entry per task. Classification, extraction and the customer-facing agent move at different moments, so they get separate entries. An LLM gateway is a natural home for that table, and a config file per environment does for a small system. Nobody should have to search the codebase to find out which model answers which request.

2. An eval set per task, run before every switch. Fifty to a few hundred real inputs with known good answers, scored the same way each time. Run old and new on it and compare accuracy, output format, token count, latency and cost. Anthropic asks for the same thing: test replacements well before the retirement date, and its Sonnet 5 checklist ends with re-baselining cost on your own workload.

3. A changelog entry per switch. Date, old ID, new ID, eval numbers before and after, prompts changed and why, who signed off. When someone asks in six months why extraction quality dipped in March, that entry is the answer.

4. A deprecation calendar with a name on it. One row per pinned ID: earliest retirement date, recommended replacement, your planned switch date, and the person who reads the provider's deprecation mail. Anthropic lets you export usage per API key and model from its console, the fastest way to find a forgotten integration on an old ID.

5. Dual-run on real traffic for a week. Send live requests to both versions, serve the old answer, log the new one and compare. An eval covers the inputs you thought of, a week of production covers the ones you did not.

6. A rollback path with an expiry date. Keep the old ID configured until the new one has run clean, and remember it only exists until the old model retires. One more reason to switch early rather than in the last week of the notice period.

For models you train yourself, a model registry does the job the provider's ID scheme does for a hosted one: numbered versions, a movable alias such as champion, and lineage back to the training run. The eval before promotion, the changelog and the rollback are ordinary MLOps. Hosted models hide the version behind an API and add a retirement date you do not control.

The short version for an SME owner

You rent a model, you do not buy one. The landlord can renovate and can end the lease, with 60 days' notice at Anthropic and around six months at OpenAI for their standard models. Someone in your company should be able to say which model versions your tools call and where that is written down. Before any version changes, run the same test set on old and new and look at the numbers. Put every retirement date in a calendar with a name beside it, and never let "latest" be the answer for a tool your customers touch.