Model Deprecation Runbook för AI API-gateways: Inventering, test, migrera och återställ före slutet av livet

Hårdkodade modell-ID:n är tysta produktionsberoenden. De fungerar tills en leverantör byter namn på en slutpunkt, tar bort en daterad ögonblicksbild, ändrar ett alias, tar bort en förhandsgranskningsmodell eller introducerar en inkompatibilitet på API-nivå. Felet visas sällan som ett rent avbrott. Det dyker upp som schemafel, högre fördröjning, oväntade avslag, olika verktygsanropsargument, ändrade kostnader eller kundbiljetter från hyresgäster vars arbetsbelastningar betedde sig annorlunda efter en förhastad migrering.

Den praktiska lösningen är att behandla modell-ID:n som hanterade beroenden, inte statiska strängar i programkoden. I en AI API-gateway innebär det att man bygger en upprepningsbok för utfasning av modeller: inventering, upptäck, utvärdera påverkan, testersättningar, skuggtrafik, rulla ut gradvis och rulla tillbaka snabbt när kompatibiliteten avbryts.

Fakta, rekommendationer och förutsägelser

Fakta: Stora modellleverantörer publicerar modellkataloger, versionsanvisningar, meddelanden om utfasning och migreringsvägledning. Dessa resurser visar att modelltillgängligheten inte är statisk. Vissa leverantörer skiljer bekvämlighetsalias från specifika modell-ID:n, och vissa migreringar kan inkludera API-nivåskillnader som bryter befintliga integrationer.

Rekommendationer: Placera modelllivscykelkontroll i gatewayen. Exponera logiska modellnamn för applikationsteam, spåra leverantörsmodellanvändning centralt, övervaka utfasningskällor och kör kompatibilitetstester innan du byter produktionstrafik.

Prognoser: Modelllivscykeldrift kommer att bli en normal del av AI-plattformsteknik. Team som kör system med flera leverantörer kommer i allt högre grad att behöva kontroller av beroendestil för modeller: versionsinventering, ändringsfönster, regressionskontroller, återställningsplaner och kundmeddelanden.

Fejlläget: ID:n för leverantörsmodeller spridda genom applikationskoden

En vanlig implementering börjar helt enkelt:

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

Detta är enkelt för en prototyp och riskabelt i produktionen. Modellsträngen kan dupliceras över backend-tjänster, skript, arbetsflöden med låg kod, interna verktyg, kundintegrationer och partnerprodukter. När modellen närmar sig slutet av sin livslängd kan ingen enskild ägare svara på grundläggande frågor:

• Vilka API nycklar skickar fortfarande trafik till den?
• Vilka hyresgäster är beroende av JSON-schema, verktygsanrop, streaming, vision, ljud eller långa sammanhang?
• Vad är de dagliga utgifterna och intäkterna?
• Vilka arbetsbelastningar kan tolerera en billigare modell och vilka kräver en kvalitetsgranskning?
• Kan teamet rulla tillbaka utan att distribuera om alla appar?

En gateway är den naturliga platsen att lösa detta eftersom den redan ser förfrågningar, nycklar, hyresgäster, leverantörer, kostnader, latens och misslyckanden.

Steg 1: Skapa en modellinventeringstabell

Börja med ett hållbart lager. Lita inte bara på leverantörsinstrumentpaneler, eftersom du behöver din egen klient, nyckel, fakturering och arbetsflödeskontext.

En praktisk model_inventory-tabell kan innehålla:

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

Sätt sedan ihop detta med användningsdata. För varje leverantörsmodell och logisk modell, spår:

• Aktiverade hyresgäster och API-nycklar
• Förfrågningar per dag och tokens per dag
• Utgifter, marginal eller intern kostnadsfördelning
• Latenspercentiler, inte bara genomsnitt
• 5xx-frekvens, leverantörsfelfrekvens, timeoutfrekvens och återförsöksfrekvens
• Användning av strukturerad utdata och schemafelfrekvens
• Biverkningar för användning av verktygssamtal och verkställande av verktyg
• Streaminganvändning
• Modaliteter som text, bild, ljud och filinmatning
• Kontextlängdsfördelning

Det här annonsutrymmet förvandlar ett meddelande om utfasning från panik till en fråga.

Steg 2: Rutt genom logiska modellnamn

Ansökningsteam ska inte behöva känna till varje leverantörs modelllivscykelregler. Ge dem stabila logiska namn som representerar arbetsbelastningens avsikt:

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

Gatewayen mappar dessa namn till leverantörsmodell-ID:

{
  "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"
    }
  }
}

Detta betyder inte att du döljer alla leverantörsuppgifter. Det innebär att man lägger leverantörsspecifika funktioner i gateway-metadata istället för att sprida dem genom produktkod. En bra sammanfattning säger både vad applikationen vill och vad leverantören faktiskt kan göra.

Steg 3: Övervaka utfasningar som schemalagda åtgärder

En utfasningsövervakare bör köras enligt ett schema och stödja manuella åsidosättningar. Den bör kontrollera leverantörsmodellkataloger, utfasningssidor, ändringsloggar, releasenotes och interna administratörsposter. Inte alla livscykelsignaler kommer att vara tillgängliga via en ren maskinläsbar API, så låt en operatör lägga till eller korrigera datum.

När monitorn upptäcker en livscykelhändelse, skapa en intern post:

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

Utlös sedan effektanalys automatiskt. Ett meddelande om utfasning ska inte sitta i en chattkanal förrän någon kommer ihåg att undersöka det.

Steg 4: Skapa en effektrapport

Konsekvensrapporten bör vara tillräckligt specifik för teknik-, ekonomi-, support- och partnerteam. Inkludera:

• Utvecklad leverantörsmodell och påverkade logiska namn
• Stängningsdatum och rekommenderad deadline för beslut
• Berörda hyresgäster, team och API nycklar
• Daglig begäranvolym och tokenvolym
• Daglig kostnad, kundfaktureringsexponering och marginalpåverkan om tillämpligt
• Bästa slutpunkter eller produkter som använder modellen
• Promptkategorier eller sparade promptmallar
• Användning av JSON scheman, funktions- eller verktygsanrop, streaming, bilder, ljud, filer eller lång sammanhang
• Aktuella latenspercentiler och felfrekvenser
• Kända avtals- eller datauppehållsbegränsningar

För Partner API-användare, exponera en filtrerad version av denna metadata så att byråer, återförsäljare och inbäddade AI-produktbyggare kan varna sina egna kunder innan en leverantörsstängning påverkar nedströmstjänster.

Steg 5: Skapa en ersättningslista efter kapacitet

Välj inte en ersättning med enbart varumärke. Betyg kandidater mot arbetsbelastningen.

Den senaste flaggskeppsmodellen är inte alltid den bästa ersättningen. En mindre nyare modell kan bevara latens och kostnad för stora volymer arbetsbelastningar. En mer kapabel modell kan vara nödvändig för komplexa arbetsflöden för kodning, extraktion eller resonemang. Runbook bör göra detta explicit istället för att förvandla varje utfasning till en uppgradering som standard.

Steg 6: Kör ett kompatibilitetsutvärderingspaket

Innan du ändrar produktionsrutt, kör ett utvärderingspaket som återspeglar den faktiska risken för arbetsbelastning.

Minsta utvärderingsuppsättning

• Gyllene uppmaningar: stabila exempel med förväntade egenskaper, inte nödvändigtvis ett exakt svar.
• Schemavaliditetstester: JSON parse framgång, obligatoriska fält, enumvärden, längdgränser och kapslade objektkontroller.
• Tester för verktygsanrop: korrekt verktygsval, giltiga argument, inga osäkra dubbletter av bieffekter.
• Säkerhets- och avslagskontroller: bekräftar att legitima affärsförfrågningar fortfarande är klara.
• Kostnadsjämförelse: indatatoken, utdatatoken, återförsök och eventuella dubbla samtal.
• Latensjämförelse: p50, p95, p99, timeoutfrekvens och strömmande första token-latens där det är relevant.
• Mänsklig granskning: krävs för värdefulla eller tvetydiga arbetsflöden där automatiserade kontroller är otillräckliga.

För strukturerade arbetsflöden räcker det inte med ett enda kvalitetsresultat på naturligt språk. Ersättningen måste producera utdata som nedströmskod kan analysera och lita på.

Steg 7: Skugga produktionstrafik på ett säkert sätt

Skuggtestning innebär att man duplicerar ett urval av produktionsförfrågningar till kandidatmodellen samtidigt som man endast returnerar den aktuella modellens svar till användaren. Spara kandidatsvaret separat för jämförelse.

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

Skugga inte allt. Undvik att duplicera förfrågningar som innehåller sidoverkande verktygsanrop om inte verktygsexekveringsskiktet är inaktiverat eller hånat. Var försiktig med känsliga uppgifter, lagringsregler och hyresgästkontrakt. Skuggtestning ökar temporära tokenutgifter, men det ger bevis från riktiga uppmaningar snarare än bara handplockade testfall.

Jämför skuggresultat på:

• Schemaets giltighet
• Kompatibilitet med verktyg och samtal
• Utdatalängd
• Kostnad per framgångsrik begäran
• Latensdistribution
• Monster för avslag och fel
• Uppgiftsspecifika granskningsresultat

Steg 8: Lansering med procentbaserad routing

När kandidaten klarar utvärderingen, rulla ut gradvis. Föredrar routingkontroller vid gatewayen efter klient, nyckel eller logisk modell snarare än att omdistribuera varje applikation.

En konservativ sekvens:

1. Endast interna hyresgäster
2. 1 % av kvalificerad produktionstrafik
3. 5 %
4. 25 %
5. 50 %
6. 100 %

Definiera återställningströsklar innan lanseringen startar:

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"

Tröskelvärden bör anpassas efter arbetsbelastning. En chatbot kan ofta tolerera mer formuleringsvariation än en pipeline för fakturautvinning. Ett bakgrundssammanfattningsjobb kan tolerera högre latens än en interaktiv supportassistent.

Steg 9: Bevara faktureringsattributionen under migreringen

Modelmigrering kan förvränga användningsanalys om gatewayen bara registrerar leverantörsmodell-ID:n. Bevara både logiska och fysiska modelldimensioner:

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 spelar roll. Det låter ekonomi och support jämföra gammalt kontra nytt beteende under utrullningsfönstret. Om en ersättningsmodell är dyrare kan företaget bestämma om det ska absorbera skillnaden, uppdatera prissättningen, flytta några hyresgäster till en mindre modell eller kräva kundens godkännande.

Steg 10: Håll en granskningslogg och återställningsplan

Varje migrering bör lämna en post:

• Utvecklad modell och ersättningsmodell
• Logiska modellnamn påverkas
• Beslutsägare och godkännare
• Konsekvensrapportlänk
• Utvärderingsresultat
• Sammanfattning av skuggtrafik
• Tidsstämplar för lansering
• Trösklar för återställning
• Kund- eller partnermeddelanden
• Slutlig status och lärdomar

En återställningsplan bör vara operativ, inte ambitiös. Om den gamla leverantörsmodellen snart kommer att stängas av kan återställning innebära att man dirigerar till en andra ersättningskandidat, inaktiverar en funktion, använder en striktare uppmaning eller tillfälligt begränsar berörda hyresgäster. Dokumentera de tillgängliga alternativen före cutover.

Avvägningar att hantera

• Fästa modell-ID:n förbättrar reproducerbarheten men ökar risken för livets slut när ögonblicksbilder tas bort.
• Provideralias minskar underhåll men kan ändra beteende under en app, så de behöver regressionsövervakning.
• Abstraktion på gatewaynivå förenklar migreringen men kan dölja leverantörsspecifika funktioner om inte metadata för kapacitet är explicit.
• Skuggtestning förbättrar förtroendet men ökar temporära tokenutgifter eftersom förfrågningar dupliceras.
• Automatisk migrering minskar risken för avbrott men kan skapa semantiska regressioner om ersättningar endast väljs utifrån pris eller generella riktmärken.
• Åsidosättanden av per-tenant skyddar viktiga kunder men ökar den operativa komplexiteten och supportbördan.
• Strikta kompatibilitetsgrindar skyddar strukturerade arbetsflöden men kan bromsa införandet av bättre modeller som kräver snabba ändringar eller schemaändringar.

Checklista för implementering

• Skapa en central inventering av leverantörsmodeller och logiska modellnamn.
• Blockera id:n för direktleverantörsmodeller från applikationsteam där det är möjligt.
• Lägg till leverantörslivscykelövervakning och manuella administratörsåtsidosättningar.
• Skapa effektrapporter för varje utfasningshändelse.
• Betyg ersättningar efter kapacitet, kostnad, latens, efterlevnad och kompatibilitet.
• Kör gyllene uppmaningar, schemakontroller, verktygssamtalskontroller, säkerhetskontroller och kostnadsjämförelser.
• Skuggsäker produktionstrafik innan du exponerar ersättningen.
• Rulla ut efter hyresgäst, nyckel eller procentandel med fördefinierade trösklar för återställning.
• Spåra logisk modell, leverantörsmodell och migrerings-ID i användningsanalys.
• Exponera utfasningsmetadata genom partnerinriktade API:er när nedströmskunder påverkas.

Aktiv slutsats

Den säkraste tiden att utforma en modellfasningsprocess är innan nästa meddelande om avstängning. Börja med en regel: applikationer begär logiska modellnamn och gatewayen äger leverantörsmappningen. Lägg sedan till det operativa lagret runt den regeln: inventering, övervakning, konsekvensrapporter, utvärderingar, skuggtrafik, utrullning i etapper, återställning och revisionsloggar.

Detta förvandlar modellmigrering från en strängersättning i sista minuten till ett hanterat beroendearbetsflöde. Målet är inte att frysa modellbeteende för alltid. Målet är att ändra modeller medvetet samtidigt som man bevarar kvalitet, kostnad, fördröjning, strukturerat utdatabeteende och faktureringstillskrivning.

Relaterad läsning

• kontroller av strukturerad utdata och verktyg-samtal kompatibilitet
• återställningsbeteende för Ls och återställningsbeteende API:er
• partnervända hyresgäster och metadata för användning