Model Deprecation Runbook: Migrate LLMs Without Breaking Apps

Treat every provider model retirement as an owned migration, not a last-day string replacement. Find every caller, pin the provider deadline, test a specific replacement, move a controlled cohort behind a stable alias, prove that old-model traffic reaches zero for the workload's full schedule, and keep rollback available before the upstream cutoff.

That indirection is necessary, but it is not sufficient. Two models that accept similar JSON can still differ in tool calling, context windows, safety behavior, latency, pricing, and output quality. A safe migration therefore combines stable aliases with contract tests, representative evaluations, controlled traffic movement, observability, and a tested rollback path.

This article presents a practical deprecation runbook and shows where AISIX AI Gateway can centralize model aliases, caller access, routing, and gateway-visible evidence. It does not claim that an alert, a recommended model, or a latest alias proves compatibility.

Key Takeaways

• Open a migration record as soon as an official provider notice is confirmed; assign an owner and a last safe rollback date.
• Give applications a stable, capability-oriented alias, but pin every migration candidate to a specific provider model version.
• A recommended or latest model is a discovery input, not proof of quality, latency, cost, tool, safety, or regional compatibility.
• Observe both the requested alias and resolved upstream target, then verify zero old-model traffic across frequent and infrequent jobs.
• Closing an alert records workflow state; it must not be confused with changing routing or blocking old traffic.
• Retire the previous target only after the rollback window and provider deadline no longer conflict.

Start with the Provider Notice, Not the Dashboard Badge

Providers regularly introduce model families, retire snapshots, change recommended versions, and alter availability by region. Confirm the event through the provider's official lifecycle notice—such as the current pages from OpenAI, Anthropic, Google Cloud, or Microsoft Foundry—and record the notice URL and observation time.

An inventory or gateway can surface affected callers and suggest a replacement. The upstream notice still controls the date, regions, model identifiers, and migration conditions. A vendor recommendation narrows the search; it does not establish that the replacement meets your workload's contract.

Create one migration record per retiring target:

Hard-coding upstream model IDs spreads that work across every application. Even when the endpoint remains compatible, a replacement can change:

• supported parameters and their valid ranges;
• context and output token limits;
• tool-call schemas and selection behavior;
• structured-output reliability;
• refusal and content-safety behavior;
• streaming event details;
• regional availability, latency, and price;
• quality on the organization's actual prompts.

An LLM gateway can centralize the mapping, but the organization still needs an explicit contract and rollout process.

Put a Stable Contract in Front of Provider Models

A useful alias describes what the caller needs, not which vendor currently supplies it. Names such as support-chat-standard, code-review-fast, or document-analysis-large age better than an upstream release identifier.

flowchart LR
    A[Applications] -->|model: support-chat-standard| G[AI Model Gateway]
    G --> C{Alias and policy}
    C -->|Current| M1[Provider A model version]
    C -->|Candidate cohort| M2[Provider B model version]
    G --> O[Logs, metrics, traces, and evaluations]

The alias contract should record at least five dimensions:

1. API behavior: endpoint, request fields, streaming semantics, error classes, and retry expectations.
2. Capabilities: text, images, tools, JSON schema, embeddings, or other modes the application may use.
3. Operating limits: context size, output limits, timeouts, concurrency, and rate limits.
4. Quality and safety: evaluation thresholds, refusal policy, prompt-injection defenses, and allowed data classes.
5. Service objectives: target latency, availability, regions, and cost envelope.

This turns a model alias into a platform contract that can be tested. It also prevents a common mistake: swapping a model because the new endpoint returns HTTP 200 while ignoring whether it still meets the application's behavioral requirements.

How Model Aliases Work in AISIX AI Gateway

The behavior in this section is pinned to AISIX OSS 1.8.0 source commit 248ed0045896050d8c94e8d5d6e3217ed558df05. Verify the current documentation and release notes before applying the example to another version or to AISIX Enterprise/Cloud.

In AISIX, the caller-facing display_name is distinct from the upstream model_name. A direct model resource can therefore expose a stable name while the provider-specific identifier remains an implementation detail. The following illustrative open-source configuration follows the documented model alias and resource model:

models:
  - display_name: support-chat-standard
    provider: openai
    model_name: gpt-5-mini
    provider_key: openai-production

Applications send the stable name:

{
  "model": "support-chat-standard",
  "messages": [
    {"role": "user", "content": "Summarize this support case."}
  ]
}

AISIX also supports routing, semantic-routing, and ensemble model resources. The exact resource shape and reference method depend on deployment mode and version; use the matching documentation instead of copying an OSS file into Enterprise or Cloud.

An alias hides the upstream name from callers. It does not prove that a replacement model has equal capabilities, quality, safety, or compliance characteristics. Those properties remain the platform team's responsibility.

Stable Alias Does Not Mean Automatically Latest

There are two useful but different patterns:

• A business alias such as support-chat-standard changes only after the platform's acceptance and rollout gates pass.
• A provider- or gateway-managed latest alias changes when its owner points the name at a newer model.

The second pattern reduces manual configuration, but it deliberately transfers change timing to another party or process. Use it for experimentation or for workloads whose risk policy explicitly accepts automatic movement. For a production contract that requires reproducibility, pin the candidate during evaluation and promote it behind your own stable alias after approval.

LiteLLM's November 6, 2026 announcement of -latest aliases is a useful example of the convenience. Its November 5 deprecation workflow separately emphasizes affected callers, official provider notices, recommended replacements, and verifying that old traffic reaches zero. Those are different jobs: an alias selects a target; a migration process establishes whether the target is acceptable.

Build an Affected-Caller Inventory

Start from gateway records, application configuration, secret ownership, deployment manifests, and scheduled jobs. Gateway logs see only traffic that crossed the gateway during the selected window; a weekly or month-end job can be absent from a short sample.

Use a compact inventory that can be reviewed without copying prompt content:

caller_id,owner,stable_alias,resolved_model,last_seen,frequency,candidate,status
support-api,support-platform,support-chat-standard,provider/model-old,2026-11-08T16:30:00Z,continuous,provider/model-new,testing
weekly-report,finance-automation,report-long,provider/model-old,2026-11-02T02:00:00Z,weekly,provider/model-new,not_started

For each row, verify:

• the caller identity is gateway-issued or otherwise authoritative, not an arbitrary request header;
• the owner can approve task-quality and data-handling changes;
• the frequency determines the zero-traffic observation window;
• indirect dependencies such as tools, images, structured output, or context size are recorded; and
• a missing owner or unknown frequency blocks closure rather than becoming an empty field that looks complete.

Runnable Inventory Gate

The following Python 3.10+ script fails if a migration row lacks an owner, candidate, frequency, or allowed workflow status. Save it as check_model_migration.py and run it against the CSV above:

#!/usr/bin/env python3
import csv
import sys
from pathlib import Path

REQUIRED = {
    "caller_id", "owner", "stable_alias", "resolved_model",
    "last_seen", "frequency", "candidate", "status",
}
ALLOWED_STATUS = {"not_started", "testing", "canary", "migrated", "verified_zero"}

def main(path: str) -> int:
    failures: list[str] = []
    with Path(path).open(newline="", encoding="utf-8") as stream:
        reader = csv.DictReader(stream)
        missing_columns = REQUIRED - set(reader.fieldnames or [])
        if missing_columns:
            print("missing columns: " + ", ".join(sorted(missing_columns)))
            return 2
        for line, row in enumerate(reader, start=2):
            for field in REQUIRED:
                if not (row.get(field) or "").strip():
                    failures.append(f"line {line}: empty {field}")
            if row.get("status") not in ALLOWED_STATUS:
                failures.append(f"line {line}: invalid status {row.get('status')!r}")
            if row.get("status") == "verified_zero" and row.get("resolved_model") != row.get("candidate"):
                failures.append(f"line {line}: resolved target does not match candidate")
    for failure in failures:
        print(failure)
    return 1 if failures else 0

if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1]))

This gate checks workflow completeness only. It does not inspect live traffic, validate a provider notice, or prove model compatibility.

A Seven-Step Model Migration Playbook

1. Inventory Callers and Deprecation Deadlines

Start with the provider's official retirement notice. Identify every caller, region, tenant, prompt template, tool definition, and policy attached to the current alias. Record the last safe cutover date and allow time for rollback before the provider deadline.

The inventory should include indirect dependencies. For example, an application may never name the upstream model but still depend on its context window, exact JSON behavior, or image support.

2. Create a Candidate Without Moving Production

Register the replacement as a separate candidate resource. Do not immediately repoint the production alias. A candidate name such as support-chat-standard-candidate creates a testable surface for offline evaluation, integration tests, and controlled production cohorts.

Keep credentials and provider configuration centralized. If the candidate belongs to another cloud or vendor, apply the same data-residency and security review used for a new external dependency. The multi-cloud AI gateway guide explains the broader provider portability trade-offs.

3. Run Contract Tests and Representative Evaluations

Contract tests should exercise every feature applications actually use:

An evaluation set should represent real traffic without exposing uncontrolled sensitive data. It should also include hard cases and known failures, not only happy paths. API compatibility and task quality are separate gates.

4. Canary a Defined Cohort

Move a small, identifiable cohort to the candidate. Good cohort keys include a platform-controlled tenant group, internal users, or a server-side experiment assignment. Avoid blindly trusting caller-supplied headers for privileged routing; validate or overwrite them at a trusted boundary.

Use a fixed exposure window and explicit stop conditions. For example, halt the canary if tool-call validity drops, p95 latency exceeds the contract, safety regressions appear, or unit cost crosses the approved envelope.

For multi-provider distribution patterns, see AI gateway load balancing. Load balancing can distribute traffic, but it does not replace a migration acceptance gate.

5. Promote by Changing the Gateway Mapping

After the candidate passes the gates, update the mapping behind the stable production alias. Applications should not need a code deployment merely to adopt the new upstream model.

Apply dependent resources in a safe order: provider credentials first, then the model resource, then caller access policy. A configuration write being accepted is not the same as caller-visible readiness. Confirm that the alias appears through the caller-facing model interface and send a real request through the production path.

6. Observe the Requested Alias and Resolved Model

Record both identities:

• the stable alias requested by the application;
• the actual provider and model version selected by the gateway.

The first attributes experience to an application contract; the second distinguishes candidates and provider failures. Track latency, status, timeout stage, tokens, cost, cache behavior, tool outcomes, and evaluation signals. The AI gateway observability guide covers the core telemetry model.

7. Preserve Rollback and Retire Deliberately

Keep the previous model resource, credentials, and validated configuration available through the rollback window. A rollback should restore the previous mapping and policy, not require emergency application releases.

Retire the old resource only after logs show that no production caller depends on it and the provider deadline no longer creates a recovery trap. “Zero” needs a complete observation window: a continuous service may need several normal peaks, while a weekly or month-end job must run at least once after cutover. Confirm infrequent jobs with their owners instead of assuming silence means completion.

If new traffic appears after the migration is marked complete, reopen it. Closing a workflow item records an operator decision; it does not change routing, block the old model, or prove that every caller moved.

Check Dependencies Before Rename or Deletion

Before renaming or deleting a model resource, inspect every reference in the deployed version: routing groups, failover targets, ensemble members, semantic-routing destinations, cache selectors, guardrail attachments, caller allowlists, rate-limit conditions, dashboards, alerts, and cost attribution. Some systems update references, some block deletion, and some leave a name-based rule configured but inactive.

Use the version-specific AISIX model alias documentation and configuration validation for the deployment you operate. Then rerun an allowed caller, a denied caller, and every endpoint-specific contract after the change. Do not generalize OSS file-mode behavior to AISIX Enterprise or Cloud.

What an AI Model Gateway Can—and Cannot—Guarantee

An AI model gateway can centralize names, credentials, routing, policy, and telemetry. It can make a tested cutover reversible and reduce application coupling.

It cannot guarantee that two providers interpret prompts identically. It cannot manufacture a capability that the candidate lacks, make a region compliant by configuration alone, or turn an untested model into a safe replacement. Provider failover also does not automatically preserve conversation state or tool side effects.

Use these explicit non-claims in migration reviews:

• OpenAI-compatible request syntax does not imply semantic parity.
• A stable alias does not imply an immutable upstream model.
• A successful canary does not eliminate the need for post-cutover monitoring.
• Routing across providers does not by itself satisfy data residency or contractual requirements.

Migration Checklist

• Pin the source model, target model, gateway version, and provider deadlines.
• Save the official provider notice, observation time, migration owner, and last safe rollback date.
• Define the alias contract and acceptance thresholds.
• Inventory frequent and scheduled callers, tools, policies, regions, and data classifications.
• Create a separately addressable candidate.
• Run API contract, task-quality, safety, latency, and cost evaluations.
• Canary a controlled cohort with stop conditions.
• Verify the caller-visible path after configuration changes.
• Observe both requested alias and resolved upstream model.
• Test rollback before full promotion.
• Recheck rate-limit and other name-based policy dependencies.
• Prove old traffic is zero across the full caller schedule and reopen on regression.
• Retire the old model only after the rollback window closes and rollback no longer depends on it.

Make the Next Model Change a Configuration Decision

Model churn is inevitable; an emergency application rewrite is optional. A stable, tested contract plus an owned deprecation workflow lets platform teams adopt new models while application teams keep using a durable interface.

Explore AISIX AI Gateway to centralize model aliases, provider configuration, policy, routing, and gateway-visible evidence—then keep provider notices, workload evaluations, owner approval, and retirement decisions explicit in your operating process.