Model Deprecation Runbook for AI API Gateways: Inventory, Test, Migrate og Roll Back Before End-of-Life

Hardkodede modell-ID-er er stille produksjonsavhengigheter. De fungerer til en leverandør gir nytt navn til et endepunkt, trekker tilbake et datert øyeblikksbilde, endrer et alias, fjerner en forhåndsvisningsmodell eller introduserer en API-nivå inkompatibilitet. Feilen vises sjelden som én ren driftsstans. Det dukker opp som skjemafeil, høyere ventetid, uventede avslag, forskjellige argumenter for verktøyanrop, endrede kostnader eller kundebilletter fra leietakere hvis arbeidsbelastninger oppførte seg annerledes etter en forhastet migrering.

Den praktiske løsningen er å behandle modell-ID-er som administrerte avhengigheter, ikke statiske strenger i programkoden. I en AI API-gateway betyr det å bygge en repeterbar modellavviklings-runbook: inventar, oppdage, vurdere innvirkning, testerstatninger, skyggetrafikk, rulle ut gradvis og rulle tilbake raskt når kompatibiliteten bryter.

Fakta, anbefalinger og spådommer

Fakta: Store modellleverandører publiserer modellkataloger, versjonsveiledning, avviklingsmeldinger og migreringsveiledning. Disse ressursene viser at modelltilgjengeligheten ikke er statisk. Noen leverandører skiller bekvemmelighetsaliaser fra spesifikke modell-ID-er, og noen migreringer kan inkludere API-nivåforskjeller som bryter eksisterende integrasjoner.

Anbefalinger: Sett modelllivssykluskontroll inne i gatewayen. Vis logiske modellnavn for applikasjonsteam, spor leverandørmodellbruk sentralt, overvåk avviklingskilder og kjør kompatibilitetstester før du bytter produksjonstrafikk.

Spådommer: Modelllivssyklusoperasjoner vil bli en normal del av AI-plattformutvikling. Team som kjører systemer med flere leverandører vil i økende grad trenge kontroller i avhengighetsstil for modeller: versjonsbeholdning, endringsvinduer, regresjonssjekker, tilbakeføringsplaner og kundevarsler.

Feilmodus: ID-er for leverandørmodeller spredt gjennom programkode

En vanlig implementering starter ganske enkelt:

{
  "model": "provider-model-preview-2025-06",
  "messages": [
    {"role": "user", "content": "Extract the invoice fields as JSON."}
  ]
}

Dette er enkelt for en prototype og risikabelt i produksjon. Modellstrengen kan dupliseres på tvers av backend-tjenester, skript, arbeidsflyter med lav kode, interne verktøy, kundeintegrasjoner og partnerprodukter. Når modellen nærmer seg slutten av levetiden, kan ingen enkelt eier svare på grunnleggende spørsmål:

• Hvilke API nøkler sender fortsatt trafikk til den?
• Hvilke leietakere er avhengige av JSON-skjema, verktøykall, strømming, visjon, lyd eller lang kontekst?
• Hva er det daglige forbruket og inntektseksponeringen?
• Hvilke arbeidsbelastninger tåler en billigere modell, og hvilke krever en kvalitetsvurdering?
• Kan teamet rulle tilbake uten å omdistribuere alle appene?

En gateway er det naturlige stedet å løse dette fordi den allerede ser forespørsler, nøkler, leietakere, leverandører, kostnader, ventetid og feil.

Trinn 1: Lag en modellbeholdningstabell

Start med en holdbar beholdning. Ikke stol bare på leverandørdashbord, fordi du trenger din egen leietaker, nøkkel, fakturering og arbeidsflytkontekst.

En praktisk model_inventory-tabell kan inneholde:

logical_model_name       support-fast
provider                 provider_a
provider_model_id         model-x-preview-2025-06
endpoint_type             chat_completions
alias_status              pinned_snapshot | provider_alias | internal_alias
status                    active | deprecated | blocked | retired
replacement_candidates    ["support-fast-v2", "support-balanced"]
first_seen_at             timestamp
last_seen_at              timestamp
deprecation_announced_at  timestamp
shutdown_at               timestamp
admin_override            text
owner_team                support-platform

Sett deretter sammen med bruksdata. For hver leverandørmodell og logisk modell, spor:

• Aktiverte leietakere og API-nøkler
• Forespørsler per dag og tokens per dag
• Forbruks-, margin- eller internkostnadsfordeling
• Latenspersentiler, ikke bare gjennomsnitt
• 5xx rate, provider error rate, timeout rate, and re try rate
• Bruk med strukturert utgang og skjemafeilfrekvens
• Bivirkninger ved bruk av verktøysamtaler og verktøykjøring
• Strømmebruk
• Modaliteter som tekst, bilde, lyd og filinndata
• Kontekstlengdefordeling

Denne beholdningen gjør en avviklingskunngjøring fra panikk til et søk.

Trinn 2: Rute gjennom logiske modellnavn

Applikasjonsteam skal ikke trenge å kjenne til alle leverandørers modelllivssyklusregler. Gi dem stabile logiske navn som representerer arbeidsbelastningens hensikt:

• support-fast
• support-quality
• coding-premium
• invoice-extractor-v2
• content-moderation-default

Gatewayen tilordner disse navnene til leverandørmodell-ID-er:

{
  "logical_model": "invoice-extractor-v2",
  "routing_policy": {
    "primary": {
      "provider": "provider_a",
      "model": "model-x-stable-2025-09"
    },
    "constraints": {
      "requires_json_schema": true,
      "max_input_tokens": 64000,
      "region": "eu"
    }
  }
}

Dette betyr ikke at du skjuler alle leverandørdetaljer. Det betyr å sette leverandørspesifikke evner i gateway-metadata i stedet for å spre dem gjennom produktkode. En god abstraksjon sier både hva applikasjonen vil ha og hva leverandøren faktisk kan gjøre.

Trinn 3: Overvåk avviklinger som planlagte operasjoner

En avviklingsmonitor bør kjøres etter en tidsplan og støtte manuelle overstyringer. Den bør sjekke leverandørmodellkataloger, avskrivningssider, endringslogger, versjonsnotater og interne administratoroppføringer. Ikke alle livssyklussignaler vil være tilgjengelige gjennom en ren maskinlesbar API, så la en operatør legge til eller korrigere datoer.

Når monitoren oppdager en livssyklushendelse, oppretter du en intern registrering:

provider_model_id: model-x-preview-2025-06
status: deprecated
shutdown_at: 2026-02-15
recommended_replacements:
  - model-x-stable-2025-09
  - model-y-mini-2025-10
source_type: provider_deprecation_page
confidence: confirmed

Deretter utløser du konsekvensanalyse automatisk. Et varsel om avvikling skal ikke sitte i en chattekanal før noen husker å undersøke det.

Trinn 4: Generer en konsekvensrapport

Konsekvensrapporten bør være spesifikk nok for ingeniør-, økonomi-, støtte- og partnerteam. Ta med:

• Utviklet leverandørmodell og berørte logiske navn
• Avslutningsdato og anbefalt beslutningsfrist
• Berørte leietakere, team og API nøkler
• Daglig forespørselsvolum og tokenvolum
• Daglig kostnad, kundefaktureringseksponering og marginpåvirkning hvis aktuelt
• Top endepunkter eller produkter som bruker modellen
• Forespørselskategorier eller lagrede ledetekstmaler
• Bruk av JSON skjemaer, funksjons- eller verktøykall, strømming, bilder, lyd, filer eller lang kontekst
• Gjeldende latenstidspersentiler og feilfrekvenser
• Kjente kontraktsmessige eller data-residency begrensninger

For Partner API-brukere, vis en filtrert versjon av disse metadataene slik at byråer, forhandlere og innebygde AI-produktbyggere kan advare sine egne kunder før en leverandørnedleggelse påvirker nedstrømstjenester.

Trinn 5: Lag en erstatningsliste etter evne

Ikke velg en erstatning etter merkenavn alene. Score kandidater mot arbeidsmengden.

Den nyeste flaggskipmodellen er ikke alltid den beste erstatningen. En mindre nyere modell kan spare ventetid og kostnader for høyvolumsarbeidsbelastninger. En mer kapabel modell kan være nødvendig for komplekse arbeidsflyter for koding, utvinning eller resonnement. Runbooken bør gjøre dette eksplisitt i stedet for å gjøre hver avskrivning til en oppgradering som standard.

Trinn 6: Kjør en kompatibilitetsevalueringspakke

Før du endrer produksjonsruting, må du kjøre en evalueringspakke som gjenspeiler faktisk arbeidsbelastningsrisiko.

Minimumsevalueringssett

• Gylne meldinger: stabile eksempler med forventede egenskaper, ikke nødvendigvis ett eksakt svar.
• Skjemavaliditetstester: JSON parsesuksess, obligatoriske felt, enum-verdier, lengdegrenser og nestede objektkontroller.
• Tester for verktøyanrop: riktig verktøyvalg, gyldige argumenter, ingen usikre duplikatbivirkninger.
• Sikkerhets- og avslagskontroller: bekrefter at legitime forretningsforespørsler fortsatt er fullført.
• Kostnadssammenligning: inndatatokener, utdatatokener, forsøk på nytt og eventuelle dupliserte anrop.
• Sammenligning av ventetid: p50, p95, p99, tidsavbruddsfrekvens og forsinkelse for strømming av første token der det er relevant.
• Menneskelig gjennomgang: kreves for høyverdi eller tvetydige arbeidsflyter der automatiserte kontroller ikke er tilstrekkelige.

For strukturerte arbeidsflyter er ikke en enkelt kvalitetspoengsum på naturlig språk nok. Erstatningen må produsere utdata som nedstrømskode kan analysere og stole på.

Trinn 7: Skygge produksjonstrafikk trygt

Skyggetesting betyr å duplisere et utvalg av produksjonsforespørsler til kandidatmodellen mens du bare returnerer den gjeldende modellens svar til brukeren. Lagre kandidatens svar separat for sammenligning.

if route.shadow_enabled and request.is_safe_to_shadow:
    primary_response = call(current_model, request)
    enqueue_shadow_call(candidate_model, request, trace_id)
    return primary_response

Ikke skygge alt. Unngå å duplisere forespørsler som inneholder sideeffektende verktøykall med mindre verktøyutførelseslaget er deaktivert eller hånet. Vær forsiktig med sensitive data, oppbevaringsregler og leiekontrakter. Skyggetesting øker det midlertidige tokenforbruket, men det gir bevis fra virkelige forespørsler i stedet for bare håndplukkede testtilfeller.

Sammenlign skyggeresultater på:

• Skjemavaliditet
• Tool-call-kompatibilitet
• Utdatalengde
• Kostnad per vellykket forespørsel
• Latensdistribusjon
• Avvisnings- og feilmønstre
• Oppgavespesifikke gjennomgangsresultater

Trinn 8: Utrulling med prosentbasert ruting

Når kandidaten har bestått evalueringen, ruller du ut gradvis. Foretrekk rutingkontroller ved gatewayen etter leietaker, nøkkel eller logisk modell i stedet for å omdistribuere hver applikasjon.

En konservativ sekvens:

1. Bare interne leietakere
2. 1 % av kvalifisert produksjonstrafikk
3. 5 %
4. 25 %
5. 50 %
6. 100 %

Definer tilbakeføringsterskler før utrullingen starter:

rollback_if:
  schema_failure_rate_increase: "> 1.0 percentage point"
  provider_5xx_rate: "> 2x baseline"
  p95_latency_increase: "> 30%"
  cost_per_successful_request: "> 25% over approved budget"
  tool_argument_validation_failures: "> 0.5%"
  tenant_blocklist_hit: "any critical tenant"

Terskler bør justeres etter arbeidsbelastning. En chatbot kan ofte tolerere mer variasjon i ordlyden enn en fakturautvinningspipeline. En bakgrunnsoppsummeringsjobb kan tåle høyere ventetid enn en interaktiv støtteassistent.

Trinn 9: Bevar faktureringsattribusjonen under migrering

Modelmigrering kan forvrenge bruksanalyse hvis gatewayen bare registrerer leverandørmodell-ID-er. Bevar både logiske og fysiske modelldimensjoner:

tenant_id
api_key_id
logical_model_name
provider
provider_model_id
migration_id
input_tokens
output_tokens
provider_cost
customer_charge
latency_ms
status
schema_valid

migration_id betyr noe. Den lar økonomi og støtte sammenligne gammel og ny atferd under utrullingsvinduet. Hvis en erstatningsmodell er dyrere, kan bedriften bestemme om den skal absorbere differansen, oppdatere priser, flytte noen leietakere til en mindre modell eller kreve godkjenning fra kunden.

Trinn 10: Hold en revisjonslogg og tilbakeføringsplan

Hver migrering bør etterlate en post:

• Utviklet modell og erstatningsmodell
• Logiske modellnavn berørt
• Beslutningseier og godkjennere
• Kobling til konsekvensrapport
• Evalueringsresultater
• Shadow traffic summary
• Tidsstempler for utrulling
• Terskler for tilbakeføring
• Kunde- eller partnervarsler
• Endelig status og lærdom

En tilbakerullingsplan bør være operativ, ikke ambisjonell. Hvis den gamle leverandørmodellen snart vil bli stengt, kan tilbakeføring bety ruting til en andre erstatningskandidat, deaktivering av en funksjon, bruk av en strengere melding eller midlertidig begrenset berørte leietakere. Dokumenter de tilgjengelige alternativene før cutover.

Avveininger å administrere

• Fastede modell-ID-er forbedrer reproduserbarheten men øker risikoen for slutten av livet når øyeblikksbilder blir trukket tilbake.
• Tilbyderaliaser reduserer vedlikehold men kan endre atferd under en applikasjon, så de trenger regresjonsovervåking.
• Astraksjon på gateway-nivå forenkler migrering, men kan skjule leverandørspesifikke muligheter med mindre kapasitetsmetadata er eksplisitte.
• Skyggetesting forbedrer selvtilliten men øker midlertidige tokenforbruk fordi forespørsler dupliseres.
• Automatisk migrering reduserer risikoen for strømbrudd, men kan skape semantiske regresjoner hvis erstatninger kun velges etter pris eller generiske referansepoeng.
• Per-tenant-overstyringer beskytter viktige kunder men øker driftskompleksiteten og støttebyrden.
• Streng kompatibilitetsporter beskytter strukturerte arbeidsflyter, men kan forsinke bruken av bedre modeller som krever spørsmål eller skjemaendringer.

Implementeringssjekkliste

• Opprett en sentral beholdning av leverandørmodeller og logiske modellnavn.
• Blokkér modell-ID-er for direkte leverandør fra applikasjonsteam der det er mulig.
• Legg til leverandørlivssyklusovervåking og manuelle administratoroverstyringer.
• Generer effektrapporter for hver avviklingshendelse.
• Score erstatninger etter kapasitet, kostnad, ventetid, overholdelse og kompatibilitet.
• Kjør gylne forespørsler, skjemasjekker, verktøykontroller, sikkerhetssjekker og kostnadssammenligninger.
• Skyggesikker produksjonstrafikk før du avslører erstatningen.
• Rulling etter leietaker, nøkkel eller prosentandel med forhåndsdefinerte tilbakerullingsterskler.
• Spor logisk modell, leverandørmodell og migrerings-ID i bruksanalyse.
• Avslør avviklingsmetadata gjennom partnervendte APIer når nedstrømskunder er berørt.

Aktiv konklusjon

Det sikreste tidspunktet for å designe en modellavviklingsprosess er før neste avslutningsvarsel. Start med én regel: applikasjoner ber om logiske modellnavn, og gatewayen eier leverandørtilordningen. Legg deretter til det operative laget rundt den regelen: inventar, overvåking, konsekvensrapporter, evalueringer, skyggetrafikk, trinnvis utrulling, tilbakerulling og revisjonslogger.

Dette gjør modellmigrering fra en strengerstatning i siste øyeblikk til en administrert avhengighetsarbeidsflyt. Målet er ikke å fryse modellatferd for alltid. Målet er å endre modeller bevisst og samtidig bevare kvalitet, kostnader, ventetid, strukturert produksjonsatferd og faktureringsattribusjon.

Relatert lesing

• kontroller av strukturert utgang og verktøy-anropskompatibilitet
• tilbakeføringskontroller for LMS APIer
• partnervendt leietaker og metadata for bruk