Bygg en AI API utfallsbevisbok før du lover SLA-kreditter

Når en oppstrømsmodellleverandør har en hendelse, spør kundene dine ikke bare om leverandøren var nede. De spør om forespørslene deres mislyktes, hvilke nøkler og modeller som ble berørt, om strømbruddet teller mot din SLA, og hvilken kreditt de skal motta. En leverandørstatusside hjelper, men den kan ikke svare på de leietakerspesifikke spørsmålene alene.

En AI API-gateway bør behandle utfallsbevis som en førsteklasses hovedbok: leverandørsignaler, syntetiske proberesultater, symptomer på forespørselsnivå, innvirkningsvinduer for leietakere, attribusjonsbeslutninger og kredittjusteringer. Målet er ikke å lage en penere hendelsestidslinje. Målet er å gjøre kundevendte avbruddsbeslutninger forklarlige, repeterbare og motstandsdyktige mot både overkreditering og underkreditering.

Hva leverandørstatussider kan og ikke kan bevise

Fakta: Atlassian Statuspage avslører offentlige API endepunkter for sammendrag, status, komponenter, uløste hendelser, hendelser og planlagt vedlikehold. OpenAI og Anthropic publiserer statussidestil JSON-endepunkter som inkluderer komponent- og hendelsesdata. Google Cloud dokumenterer Service Health APIer og dashboards, og avslører også folkehelseinformasjon gjennom feeder. Skyleverandører publiserer også anmeldelser etter hendelsen for enkelte arrangementer.

Disse innmatingene er nyttige input. De kan fortelle deg at en leverandør anerkjente en hendelse, hvilken brede komponent som ble berørt, og når hendelsen beveget seg gjennom tilstander som etterforskning, identifisert, overvåking, løst eller postmortem. De er ikke nok til å bestemme kundekreditt for et AI API forhandleroperasjoner-program.

Statussider ligger ofte etter reell kundepåvirkning. De kan beskrive en bred komponent som nettprat, svar, innebygginger, bilder eller filer uten å være tydelig tilordnet modellaliaser, leverandørkontoer, regioner, distribusjoner, tjenestenivåer eller godkjenningslister for leietakere. De kan heller ikke fortelle deg om en spesifikk kundes forespørsler mislyktes på grunn av oppstrømsdegradering, gateway-struping, oppbrukt budsjett, ugyldig inndata, tidsavbrudd på klientsiden eller et lokalt nettverksproblem.

Anbefaling: bruk leverandørstatus som én bevisstrøm, ikke som kredittutløser. Kreditter bør avhenge av bevis for påvirkning fra leietaker og et avstemmingspass etter at forespørselslogger, bruksoppgjør og oppdateringer av leverandørhendelser er tilgjengelige.

The Ledger Record You Need

Start med en varig driftsstans som kan representere både leverandøromfattende hendelser og leietakerspesifikk påvirkning. Oppføringen skal bare legges til eller være versjonert slik at senere klassifiseringsendringer ikke sletter det opprinnelige deteksjonssporet.

{
  "incident_id": "inc_2026_05_29_openai_azure_eastus_latency",
  "provider": "azure_openai",
  "provider_account_id": "acct_prod_shared_01",
  "surface": "chat_completions",
  "model_or_deployment": "gpt-4o-prod-eastus",
  "region": "eastus",
  "source_signals": ["provider_status", "synthetic_canary", "request_symptoms"],
  "confidence": "confirmed",
  "provider_started_at": "2026-05-29T11:42:00Z",
  "provider_acknowledged_at": "2026-05-29T12:05:00Z",
  "detected_at": "2026-05-29T11:45:11Z",
  "mitigated_at": "2026-05-29T12:31:44Z",
  "recovered_at": "2026-05-29T12:48:00Z",
  "affected_tenant_ids": ["ten_123", "ten_456"],
  "linked_request_ids": ["req_a", "req_b", "req_c"],
  "credit_policy_version": "sla_2026_04",
  "credit_status": "pending_reconciliation"
}

Tid for leverandørhendelse og innvirkningstid for leietaker er separate felt. En leverandør kan rapportere en omfattende hendelse fra 11:30 til 13:00, men én leietaker kan ha vært upåvirket fordi de tillatte modellene brukte en annen leverandør. En annen leietaker kan ha sett feil bare fra 11:47 til 12:18 fordi ruting flyttet den til en reservemodell. En tredjedel kan ha opplevd høy latenstid, men ingen mislykkede forespørsler. Disse forskjellene betyr noe når kreditter blir penger.

Sett inn tre bevisstrømmer

1. Provider Status APIs

Samle leverandørstatusdata på en tidsplan og på forespørsel under hendelser. Lagre rånyttelasthashen, gjenfinningstid, leverandørkomponentidentifikatorer, hendelsestilstand, hendelses-URL eller leverandørreferanse og eventuelt tekstsammendrag. Ikke overskriv gamle tilstander. Hvis en hendelse går fra etterforskning til identifisert til overvåking, bevar hver overgang.

Normaliser leverandørkomponenter til dine egne gatewaydimensjoner:

• leverandør: OpenAI, Anthropic, Azure OpenAI, Google eller en annen oppstrøms
• overflate: chat, svar, innebygginger, bilder, batch, lyd, sanntid, filer, moderering
• modell eller distribusjon: oppstrømsmodell, internt alias eller skyimplementeringsnavn
• region: der det er aktuelt
• konto eller legitimasjonsgruppe: delt konto, leietakerbundet konto eller BYOK legitimasjon
• tjenestenivå: standard, prioritet, klargjort, batch- eller internt nivånavn

Trade-off: leverandørstatusinntak er billig og autoritativt for bekreftelse, men det kan være sent, bredt eller ufullstendig. Det bør vekke mistanke og hjelpe med kundekommunikasjon, men det skal ikke automatisk generere kreditter.

2. Syntetiske kanarifugler

Syntetiske kanarifugler er små, kontrollerte forespørsler som sendes gjennom samme gatewaybane som produksjonstrafikk. De bør dekke kombinasjonene du selger, ikke alle mulige leverandørfunksjoner. En forhandler kan for eksempel kjøre kanarifugler for hver leverandør, overflate, modellnivå og region som brukes av betalte planer.

Hvert kanari-resultat bør inneholde:

• canary_id og tidsplanversjon
• leverandør, overflate, modell, region, legitimasjonsgruppe og ruteprofil
• starttid, første bytetid, fullføringstid og tidsavbruddsgrense
• HTTP status, leverandørfeilkode, gatewayfeilkode og antall forsøk på nytt
• latency percentil-bøtte, ikke bare bestått eller mislykket
• forespørselskorrelasjons-ID og redigerte responsmetadata

Kanariøyene bør unngå rå kundeforespørsler. Bruk faste, ikke-sensitive forespørsler og hold svarvalideringen enkel. En kanarifugl kan verifisere at endepunktet godtar forespørsler, strømmer fullført og ventetiden holder seg innenfor en terskel. Den trenger ikke å bedømme modellens kvalitet for beslutninger om avbruddskreditt.

Trade-off: kanarifugler gir uavhengige bevis før kunder rapporterer et problem. De legger også til kostnader og kan konsumere kvote under leverandørstress. Gass kanarifuglene under aktive hendelser og unngå aggressiv oppførsel på nytt forsøk som bidrar til oppstrømsbelastning.

3. Reelle forespørselssymptomer

Bevis på forespørselsnivå er den sterkeste kilden til leietakerpåvirkning. Hver gateway-forespørsel skal allerede ha leietaker, nøkkel, bruker- eller sluttbrukeridentifikator, modellalias, leverandørrute, region, status, ventetid, tokenbruk og faktureringstilstand. For avbruddsrapportering legger du til klassifiseringsfelt som skiller oppstrømssymptomer fra kunde- og gatewayårsaker.

Nyttige symptomklasser inkluderer:

• provider_5xx: oppstrøms HTTP 5XX eller tilsvarende leverandørserverfeil
• provider_timeout: ingen leverandørrespons før gateway-tidsavbrudd
• provider_429_spike: oppstrøms hastighetsgrense over normal grunnlinje
• stream_abort_upstream: leverandørstrømmen ble avsluttet uventet
• latency_degraded: fullført forespørsel overskredet policyterskel
• gateway_throttle: gateway nektet forespørselen på grunn av leietakergrense eller rettferdighetspolicy
• customer_error: ugyldig forespørsel, modell som ikke støttes, dårlig autentisering eller feil utformet nyttelast
• budget_exhausted: leietakers forbruk eller kredittgrense blokkert forsendelse

Bare de fem første skal normalt telle som avbruddssymptomer, og selv da bare etter attribusjon. En økning i oppstrøms 429s kan være et leverandørproblem, men det kan også være forårsaket av at en leietaker overskrider den reserverte gjennomstrømningen. Et tidsavbrudd kan være leverandørforringelse, men det kan også være forårsaket av en klientfrakobling eller et tidsavbrudd på programnivå som er kortere enn gatewayens tidsavbrudd.

Det er her en multimodell API gateway for team trenger disiplinert hendelsesmodellering. Ruteavgjørelsen, forsøket på nytt, reserveresultatet, endelig svar og faktureringsoppgjøret bør kunne slås sammen med korrelasjons-ID.

Separat leverandørhendelse Windows fra Tenant Impact Windows

Ikke krediter kunder for leverandørens brede hendelsesvarighet. Kreditt dem for den delen av hendelsen som påvirket deres kvalifiserte trafikk i henhold til retningslinjene dine.

Bruk minst fem vindusmarkører:

• deteksjonstid: når systemet først oppdaget unormal atferd
• første berørte forespørsel: første kvalifiserte leietakerforespørsel med et avbruddssymptom
• tidspunkt for bekreftelse av leverandør: når oppstrømsleverandøren publiserte eller bekreftet hendelsen
• reduserende tid: når gatewayen din brukte fallback, trafikkforming, rutedeaktivering eller en annen redusering
• gjenopprettingsbekreftelse: når kanarifugler og ekte trafikk returnerte under terskelverdiene

Leietakereffektvinduet kan beregnes per leietaker, per nøkkel, per modellalias og per tjenestenivå. For eksempel:

tenant_id: ten_123
model_alias: support-fast
eligible_requests: 842
failed_provider_requests: 96
degraded_latency_requests: 211
first_affected_at: 2026-05-29T11:47:08Z
last_affected_at: 2026-05-29T12:22:31Z
mitigation_applied_at: 2026-05-29T12:04:19Z
credit_status: provisional

Denne separasjonen beskytter deg også mot overkreditering. Hvis en leietaker ikke hadde trafikk under leverandørhendelsen, kan det hende at det ikke er kreditt. Hvis en leietaker kun rutes til upåvirkede modeller, kan det hende at det ikke er noen kreditt. Hvis alle feil var ugyldige forespørsler eller budsjettnektelser, bør hendelsesrapporten si det uten å klandre leverandøren.

Definer kredittpolicy før hendelsen

Kredittpolicy bør være en tabell eller versjonskonfigurasjon, ikke en støttevurdering improvisert under press. Retningslinjene trenger ikke være helautomatiske, men de bør gjøre kvalifikasjons- og godkjenningsreglene eksplisitt.

Inkluder disse feltene:

• kvalifiserte symptomer: leverandør 5XX, oppstrøms tidsavbrudd, strømavbrudd, alvorlig forringelse av ventetid eller andre klasser
• minimumsvarighet: for eksempel fem minutter på rad eller et terskelantall berørte forespørsler
• latensgrense: fast terskel, prosentilgrunnlinje eller tjenestenivåspesifikk mål
• ekskluderte årsaker: kundefeil, budsjettbruk, leietakergass, feilutformet forespørsler, modell som ikke støttes, klientfrakoblinger
• prøv behandling på nytt: om vellykkede reserveforespørsler teller som mislykket, forringet eller redusert
• kredittformel: prosentandel av berørt bruk, fast lommebokjustering, planbasert SLA-kreditt eller manuell gjennomgang
• godkjenningsmyndighet: automatisk under en grense, driftsgodkjenning over den, finansgodkjenning for store leietakere
• leverandørkreditthåndtering: sendt gjennom, delt, beholdt eller håndtert separat fra kundekreditter
• oppbevaring av bevis: hvor lenge hendelser, forespørsler, kanarifugler og kredittposter kan spørres

Anbefaling: lagre kredittpolicyversjonen ved hver foreløpig og endelig kredittbeslutning. Hvis du reviderer retningslinjene senere, bør historiske avgjørelser fortsatt forklare hvilke regler som ble brukt på det tidspunktet.

Avstem før endelige kreditter

Under en hendelse trenger kundene statusoppdateringer raskt. Kredittvedtak kan være foreløpige. Den endelige kredittovergangen bør skje etter at loggene er fullført, hendelser med forsinket bruk har avgjort, gjenforsøk og reserver er klassifisert, og leverandørinformasjonen etter hendelsen er gjennomgått.

En praktisk arbeidsflyt for avstemming ser slik ut:

1. Opprett eller oppdater hendelsesposten fra leverandørstatus, kanarievarsler eller be om symptomterskler.
2. Frys den berørte ruteprofilen eller merk den som degradert slik at nye rutebeslutninger kan unngå det der det er mulig.
3. Generer foreløpige innvirkningsvinduer for leietakere fra forespørselslogger og kanariøyetidslinjer.
4. Ekskluder årsaker på kundesiden og gatewaysiden ved å bruke klassifiseringsregler.
5. Bli med bruks- og faktureringsoppføringer slik at berørte forespørsler er knyttet til oppgjorte kostnader og kundebelastningsposter.
6. Bruk kredittpolicyversjonen og lag foreløpige kredittrader.
7. Gjennomgå tvetydige tilfeller, spesielt forringelse av delvis ventetid og høyverdige leietakere.
8. Legg inn endelige kredittjusteringer i lommeboken eller fakturareskontroen med lenker tilbake til hendelsesposten.

Dette knytter håndtering av strømbrudd til unified AI API billing i stedet for å legge igjen kreditter som manuelle notater i en støttebillett. Justeringen bør kunne revideres: hvem godkjente den, hvilken policy som gjaldt, hvilke forespørsler som var kvalifisert, og om den er endelig eller reversibel.

Expose Customer and Partner API Views

Kunder trenger en tydelig hendelsesforklaring, ikke hele den interne sporingsbutikken din. Nedstrømsplattformer som videreselger eller bygger inn API kan også trenge å vise hendelsesstatus i sine egne portaler. Et Partner API-endepunkt kan avsløre en hendelsesvisning med leietakeromfang.

GET /partner/incidents/{incident_id}/tenant-impact?tenant_id=ten_123

{
  "incident_id": "inc_2026_05_29_openai_azure_eastus_latency",
  "status": "final",
  "summary": "Elevated upstream latency and intermittent failures affected selected chat requests.",
  "affected_windows": [
    {
      "model_alias": "support-fast",
      "first_affected_at": "2026-05-29T11:47:08Z",
      "last_affected_at": "2026-05-29T12:22:31Z",
      "eligible_failed_requests": 96,
      "eligible_degraded_requests": 211
    }
  ],
  "affected_keys": ["key_live_abc"],
  "credit_status": "applied",
  "credit_adjustment_id": "adj_789",
  "evidence": {
    "canary_ids": ["canary_chat_eastus_01"],
    "sample_request_ids": ["req_a", "req_b"]
  }
}

Hold denne visningen begrenset. Ta med syntetiske kanarifugl-ID-er, forespørselskorrelasjons-ID-er, berørte modeller, berørte nøkler og endelig kredittstatus. Unngå ubehandlede meldinger og fullstendige svarinstanser som standard. Hvis en kunde trenger dypere bevis, gi en kontrollert eksport med redaksjons- og autorisasjonssjekker.

Mal for kundehendelserapport

En nyttig kunderapport kan være kort hvis hovedboken er fullstendig. Den bør skille bekreftede fakta fra operasjonell tolkning.

Fakta

• Leverandør og overflate berørt
• Leietakers innvirkningsvindu
• Antall kvalifiserte mislykkede, tidsavbrutt, avbrente eller forringede forespørsler
• Berørte modellaliaser, regioner og kundenøkler
• Begrensning brukt og bekreftelsestid for gjenoppretting

Gateway Assessment

• Om symptomene ble tilskrevet leverandøren, gatewayen, leietakerkonfigurasjonen eller kundeforespørseladferd
• Om reserveruting reduserte innvirkningen
• Om hendelsen oppfyller grensen for kredittpolicy
• Om kreditt er foreløpig, godkjent, brukt eller nektet

Begrensninger

• Detaljer om leverandørhendelse kan endres etter postmortem-publisering
• Terskler for latensdegradering er policydefinerte, ikke universelle
• Forespørsler som er ekskludert som kundefeil eller budsjettnektelser, regnes ikke som leverandøravbrudd

Spådommer og designspill

Prediksjon: kundevendt avbruddsrapportering vil bli en normal funksjon på AI API forhandlerplattformer, spesielt for SaaS-leverandører som eksponerer AI-funksjoner under sitt eget merke. Ettersom AI-arbeidsbelastninger går fra eksperimentering til produksjon, vil kundene forvente den samme hendelsesansvarligheten som de mottar fra leverandører av nettskyinfrastruktur.

Prediksjon: leverandørstatussider vil fortsatt være nødvendige, men utilstrekkelige. Flere hendelser vil involvere delvis forringelse: latenstidstopper, strømmeavbrudd, regionale kapasitetsproblemer, kvalitetsregresjoner, feil med verktøyanrop eller kontospesifikk kvoteatferd. Disse sakene krever bevis på forespørsels- og leietakernivå.

Anbefaling: bygg hovedboken før du lover sterke SLA-kreditter. Ettermontering av hendelsesbevis etter et omstridt driftsavbrudd er dyrt og ofte usikkert.

Handlingsbar konklusjon

Ikke la leverandørstatussider bli den eneste kilden til sannhet for kundekreditter. Bygg en avbruddsbevisbok som kobler seg til leverandørhendelsesfeeder, syntetiske kanarifugler, forespørselssymptomer, rutebeslutninger, innvirkningsvinduer for leietakere, faktureringsoppføringer og endelige kredittjusteringer.

Den minste nyttige versjonen er enkel: innta leverandørstatus JSON, kjør lavvolum kanarifugler for solgte modellregionnivåer, klassifiser forespørselsfeil etter årsak, beregn leietakers innvirkningsvinduer og bruk en versjonert kredittpolicy etter avstemming. Det gir støtte, økonomi, ingeniørarbeid og nedstrømspartnere det samme bevisgrunnlaget. Den lar deg også forklare hendelser uten blindt å speile oppstrøms statussider eller utstede manuelle goodwillkreditter når en kunde klager.

Relatert lesing

• kundevendt bruks- og justeringsrapportering