Model Versioning — Patterns

Logical name resolved to a pinned snapshot

Problem. Call sites that name a concrete model version must all be edited to upgrade, so upgrades are big and rare. Call sites that name a floating alias upgrade themselves, which is worse.

Approach. Call sites reference a logical role — drafting, extraction, review. A single version-resolution table maps each role to an immutable pinned identifier, lives in version control, and is changed by pull request. The resolution happens once per request and the resolved identifier is attached to the request context from that point on.

Trade-off. The table becomes a release-coordination point, and a role that different services want to resolve differently forces either a per-service override mechanism or a new role. It also hides the concrete version from the code, so the recorded resolution on the response is the only place the truth is visible.

Version stamping at the point of generation

Problem. During an incident the question is always "what produced this output", and reconstructing it from deploy history and alias resolution tables after the fact is guesswork.

Approach. Write the resolved model version onto the artefact itself at generation time — the stored response row, the trace span, the evaluation result, and any cached entry — together with the configuration hash and prompt version. Prefer the version the API reports over the version you requested, because they differ exactly when it matters.

Trade-off. It is denormalised data that will diverge from the registry over time, and it enlarges every stored record. That redundancy is the point: it survives the registry being wrong.

Replay-gated upgrades

Problem. A new version is announced as better. Whether it is better for your traffic is unknown, and the only evidence available by default is the provider's benchmark table.

Approach. Keep a corpus of recorded production requests with their accepted outputs. On a candidate version, replay the corpus, diff outputs on the properties the product cares about — schema validity, tool-call correctness, refusal rate, length, latency, cost — and review the cases that changed rather than an aggregate score. Promote only after the diff is explained, then ramp.

Trade-off. The corpus is a privacy-sensitive asset requiring retention rules and access control, and it ages: replaying last quarter's traffic validates against last quarter's product. Diff review is manual work that scales poorly, so the corpus must be sampled deliberately rather than grown indefinitely.

Dual-running during a deprecation window

Problem. A pinned version has a retirement date, the replacement differs behaviourally, and the migration cannot be instantaneous because some workflows hold long-lived state tied to the old version's behaviour.

Approach. Run both versions concurrently, keyed by workflow or tenant rather than by percentage, so an individual unit of work completes entirely on one version. Migrate new work to the replacement first, drain the old version's long-lived work, and keep the dual path until the drain completes or the deadline forces a cut.

Trade-off. Two versions in production means two sets of prompts, two evaluation baselines, and two sets of failure modes to operate at once. The cost is real and bounded; the alternative is an unplanned cut on the provider's date.