Byg en AI API udfaldsbevisbog, før du lover kunde-SLA-kreditter

Når en upstream-modeludbyder har en hændelse, spørger dine kunder ikke kun, om udbyderen var nede. De spørger, om deres anmodninger mislykkedes, hvilke nøgler og modeller der var berørt, om udfaldet tæller imod din SLA, og hvilken kredit de skal modtage. En udbyderstatusside hjælper, men den kan ikke besvare disse lejerspecifikke spørgsmål af sig selv.

En AI API-gateway bør behandle udfaldsbeviser som en førsteklasses hovedbog: udbydersignaler, syntetiske proberesultater, symptomer på anmodningsniveau, lejers indvirkningsvinduer, tilskrivningsbeslutninger og kreditjusteringer. Målet er ikke at skabe en smukkere hændelsestidslinje. Målet er at gøre kundevendte beslutninger om afbrydelser forklarelige, gentagelige og modstandsdygtige over for både over- og underkreditering.

Hvad udbyderstatussider kan og ikke kan bevise

Fakta: Atlassian Statuspage afslører offentlige API slutpunkter for oversigt, status, komponenter, uløste hændelser, hændelser og planlagt vedligeholdelse. OpenAI og Anthropic udgiver Statusside-stil JSON slutpunkter, der inkluderer komponent- og hændelsesdata. Google Cloud dokumenterer Service Health API'er og dashboards og afslører også folkesundhedsoplysninger gennem feeds. Cloud-udbydere udgiver også anmeldelser efter hændelsen for nogle begivenheder.

Disse feeds er nyttige input. De kan fortælle dig, at en udbyder anerkendte en hændelse, hvilken brede komponent var berørt, og når hændelsen bevægede sig gennem tilstande som efterforskning, identificeret, overvågning, løst eller postmortem. De er ikke nok til at afgøre kundekreditter for et AI API forhandleroperationer-program.

Statussider halter ofte efter den reelle kundepåvirkning. De kan beskrive en bred komponent som f.eks. chat, svar, indlejringer, billeder eller filer uden at være direkte tilknytning til dine modelaliasser, udbyderkonti, regioner, implementeringer, serviceniveauer eller tilladelseslister for lejere. De kan heller ikke fortælle dig, om en specifik kundes anmodninger mislykkedes på grund af upstream-forringelse, gateway-throttling, opbrugt budget, ugyldigt input, timeout-adfærd på klientsiden eller et lokalt netværksproblem.

Anbefaling: brug udbyderstatus som én bevisstrøm, ikke som kredittrigger. Krediteringer bør afhænge af lejerpåvirkningsbeviser og et afstemningspas efter anmodningslogfiler, brugsafregning og opdateringer af udbyderhændelser er tilgængelige.

The Ledger Record You Need

Start med en holdbar afbrydelsesregistrering, der kan repræsentere både udbyder-omfattende hændelser og lejerspecifik påvirkning. Registreringen bør kun være tilføjet eller versioneret, så senere klassifikationsændringer sletter ikke det oprindelige registreringsspor.

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

Udbyderens hændelsestid og lejerens påvirkningstid er separate felter. En udbyder kan rapportere en bred hændelse fra 11:30 til 13:00, men en lejer kan have været upåvirket, fordi dens tilladte modeller brugte en anden udbyder. En anden lejer har muligvis kun set fejl fra 11:47 til 12:18, fordi routing flyttede den til en reservemodel. En tredje kan have oplevet høj latenstid, men ingen mislykkede anmodninger. Disse forskelle har betydning, når kreditter bliver til penge.

Indtag tre bevisstrømme

1. Provider Status API'er

Indsaml udbyderstatusdata efter en tidsplan og efter behov under hændelser. Gem den rå nyttelast-hash, hentetid, udbyderkomponentidentifikatorer, hændelsestilstand, hændelses-URL eller udbyderreference og enhver tekstoversigt. Overskriv ikke gamle tilstande. Hvis en hændelse går fra efterforskning til identificeret til overvågning, skal du bevare hver overgang.

Normaliser udbyderkomponenter til dine egne gateway-dimensioner:

• udbyder: OpenAI, Anthropic, Azure OpenAI, Google eller en anden upstream
• overflade: chat, svar, indlejringer, billeder, batch, lyd, realtid, filer, moderering
• model eller implementering: opstrømsmodel, internt alias eller cloud-implementeringsnavn
• region: hvor relevant
• konto eller legitimationspulje: delt konto, lejerbundet konto eller BYOK legitimationsoplysninger
• serviceniveau: standard, prioritet, klargjort, batch- eller internt niveaunavn

Trade-off: udbyderstatusindtagelse er billig og autoritativ til anerkendelse, men den kan være forsinket, bred eller ufuldstændig. Det bør vække mistanke og hjælpe med kundekommunikation, men det bør ikke automatisk generere kreditter.

2. Syntetiske Kanariske Øer

Syntetiske kanariefugle er små, kontrollerede anmodninger, der sendes gennem den samme gateway-sti som produktionstrafik. De bør dække de kombinationer, du sælger, ikke alle mulige udbyderfunktioner. En forhandler kan f.eks. køre kanariefugle for hver udbyder, overflade, modelniveau og region, der bruges af betalte planer.

Hvert kanariefugleresultat skal indeholde:

• canary_id og planlægningsversion
• udbyder, overflade, model, region, legitimationspulje og ruteprofil
• starttidspunkt, første bytetid, færdiggørelsestidspunkt og timeouttærskel
• HTTP status, udbyderfejlkode, gatewayfejlkode og tæller igen
• latency percentile bucket, ikke kun bestået eller mislykket
• anmodningskorrelations-id og redigerede svarmetadata

De Kanariske Øer bør undgå rå kundebeskeder. Brug faste, ikke-følsomme prompter, og hold svarvalidering enkel. En kanariefugl kan verificere, at endepunktet accepterer anmodninger, streams fuldføres, og latenstiden forbliver inden for en tærskel. Den behøver ikke at bedømme modelkvalitet for beslutninger om udfaldskredit.

Trade-off: Kanariefugle giver uafhængige beviser, før kunder rapporterer et problem. De tilføjer også omkostninger og kan forbruge kvoter under udbyderstress. Gas kanariefuglene under aktive hændelser, og undgå aggressiv genforsøgsadfærd, der bidrager til opstrømsbelastning.

3. Reelle anmodningssymptomer

Bevis på anmodningsniveau er den stærkeste kilde til lejerpåvirkning. Hver gateway-anmodning skal allerede have lejer, nøgle, bruger- eller slutbruger-id, modelalias, udbyderrute, region, status, latens, tokenbrug og faktureringstilstand. Til rapportering af udfald skal du tilføje klassifikationsfelter, der adskiller opstrømssymptomer fra kunde- og gatewayårsager.

Nyttige symptomklasser omfatter:

• provider_5xx: upstream HTTP 5XX eller tilsvarende udbyderserverfejl
• provider_timeout: intet udbydersvar før gateway-timeout
• provider_429_spike: opstrømshastighedsgrænse over normal baseline
• stream_abort_upstream: udbyderens stream sluttede uventet
• latency_degraded: fuldført anmodning overskredet politiktærskel
• gateway_throttle: gateway afviste anmodningen på grund af lejergrænse eller retfærdighedspolitik
• customer_error: ugyldig anmodning, ikke-understøttet model, dårlig godkendelse eller forkert udformet nyttelast
• budget_exhausted: lejerforbrug eller kreditgrænse blokeret afsendelse

Kun de første fem bør normalt tælle som udfaldssymptomer, og selv da kun efter tilskrivning. En stigning i upstream 429s kan være et udbyderproblem, men det kan også være forårsaget af, at en lejer overskrider dens reserverede gennemløb. En timeout kan være udbyderforringelse, men den kan også være forårsaget af en klientafbrydelse eller en timeout på programniveau, der er kortere end din gateway-timeout.

Det er her, en multimodel API-gateway for teams har brug for disciplineret hændelsesmodellering. Rutebeslutningen, genforsøgsforsøg, reserveresultat, endeligt svar og faktureringsafregning bør kunne forbindes med korrelations-id.

Separat Provider Incident Windows fra Tenant Impact Windows

Lad være med at kreditere kunder for udbyderens brede hændelsesvarighed. Krediter dem for den del af hændelsen, der påvirkede deres kvalificerede trafik i henhold til din politik.

Brug mindst fem vinduesmarkører:

• detektionstid: da dit system første gang registrerede unormal adfærd
• første berørte anmodning: første kvalificerede lejeranmodning med et udfaldssymptom
• udbyderens bekræftelsestidspunkt: når upstream-udbyderen offentliggjorde eller bekræftede hændelsen
• afbødningstid: når din gateway anvendte fallback, trafikformning, rutedeaktivering eller en anden begrænsning
• gendannelsesbekræftelse: når kanariefugle og reel trafik vendte tilbage under tærsklerne

Lejerens indvirkningsvindue kan beregnes pr. lejer, pr. nøgle, pr. modelalias og pr. serviceniveau. 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 adskillelse beskytter dig også mod overkreditering. Hvis en lejer ikke havde nogen trafik under udbyderhændelsen, er der muligvis ingen kredit. Hvis en lejer kun rutes til upåvirkede modeller, er der muligvis ingen kredit. Hvis alle fejl var ugyldige anmodninger eller budgetafvisninger, skal hændelsesrapporten sige det uden at bebrejde udbyderen.

Definer kreditpolitik før hændelsen

Kreditpolitik bør være en tabel- eller versionskonfiguration, ikke en støttevurdering improviseret under pres. Politikken behøver ikke at være fuldautomatisk, men den bør tydeliggøre reglerne for berettigelse og godkendelse.

Inkluder disse felter:

• kvalificerede symptomer: udbyder 5XX, upstream timeout, stream afbrydelse, alvorlig forringelse af latenstid eller andre klasser
• minimumsvarighed: f.eks. fem på hinanden følgende minutter eller en grænse for antallet af berørte anmodninger
• forsinkelsestærskel: fast tærskel, percentilbaseline eller serviceniveauspecifikt mål
• ekskluderede årsager: kundefejl, budgetopbrug, lejergasregulering, forkerte anmodninger, ikke-understøttet model, klientafbrydelser
• Prøv behandling igen: om vellykkede reserveanmodninger tæller som mislykkede, forringede eller formindskede
• kreditformel: procentdel af berørt brug, fast tegnebogsjustering, planbaseret SLA-kredit eller manuel gennemgang
• godkendelsesmyndighed: automatisk under en grænse, driftsgodkendelse over den, finansgodkendelse for store lejere
• leverandørkredithåndtering: videregivet, delt, bibeholdt eller håndteret separat fra kundekreditter
• bevarelse af beviser: hvor længe kan hændelser, anmodninger, kanariefugle og kreditoplysninger forespørges

Anbefaling: Gem kreditpolitikversionen ved hver foreløbig og endelig kreditbeslutning. Hvis du reviderer politikken senere, bør historiske beslutninger stadig forklare, hvilke regler der blev anvendt på det tidspunkt.

Afstem før endelige kreditter

Under en hændelse har kunder brug for statusopdateringer hurtigt. Kreditbeslutninger kan være foreløbige. Den endelige kreditoverførsel bør ske, efter at logfiler er færdige, hændelser med forsinket brug er afgjort, genforsøg og fallbacks er klassificeret, og udbyderens oplysninger efter hændelsen er blevet gennemgået.

En praktisk afstemningsarbejdsgang ser sådan ud:

1. Opret eller opdater hændelsesregistret fra udbyderstatus, kanariealarmer, eller anmod om symptomtærskler.
2. Frys den berørte ruteprofil, eller markér den som forringet, så nye rutebeslutninger kan undgå det, hvor det er muligt.
3. Generer foreløbige lejerindvirkningsvinduer fra anmodningslogfiler og kanariske tidslinjer.
4. Ekskluder årsager på kundesiden og gatewaysiden ved hjælp af klassificeringsregler.
5. Tilslut dig brugs- og faktureringsregistreringer, så berørte anmodninger er bundet til afregning af omkostninger og kundedebiteringer.
6. Anvend kreditpolitikversionen, og lav foreløbige kreditrækker.
7. Gennemgå tvetydige sager, især forringelse af delvis latenstid og lejere af høj værdi.
8. Send endelige kreditjusteringer til tegnebogen eller fakturaen med links tilbage til hændelsesregistret.

Dette knytter håndtering af afbrydelser til unified AI API billing i stedet for at efterlade kreditter som manuelle noter i en supportbillet. Justeringen skal kunne revideres: hvem godkendte den, hvilken politik anvendte, hvilke anmodninger var kvalificerede, og om den er endelig eller reversibel.

Eksponer kunde og partner API visninger

Kunder har brug for en klar hændelsesforklaring, ikke hele dit interne sporingslager. Downstream-platforme, der videresælger eller integrerer din API, skal muligvis også vise hændelsesstatus i deres egne portaler. Et Partner API-slutpunkt kan afsløre en hændelsesvisning med lejeromfang.

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 visning begrænset. Inkluder syntetiske kanarie-id'er, anmodningskorrelations-id'er, berørte modeller, berørte nøgler og endelig kredittilstand. Undgå som standard rå prompter og komplette svarinstanser. Hvis en kunde har brug for dybere beviser, skal du sørge for en kontrolleret eksport med redaktions- og godkendelsestjek.

Skabelon for kundehændelsesrapport

En nyttig kunderapport kan være kort, hvis hovedbogen er komplet. Den bør skelne bekræftede fakta fra operationel fortolkning.

Fakta

• Berørt udbyder og overflade
• Indvirkningsvindue for lejer
• Antal kvalificerede mislykkede, timeout, afbrudte eller forringede anmodninger
• Berørte modelaliasser, regioner og kundenøgler
• Reduktion anvendt og gendannelsesbekræftelsestid

Gateway-vurdering

• Om symptomerne blev tilskrevet udbyderen, gatewayen, lejerkonfigurationen eller kundeanmodningsadfærd
• Om reserveruting reducerede virkningen
• Om hændelsen overholder kreditpolitikkens grænse
• Om kreditten er foreløbig, godkendt, anvendt eller nægtet

Grænser

• Udbyderhændelsesoplysninger kan ændre sig efter postmortem publicering
• Tærskler for latensnedbrydning er politikdefinerede, ikke universelle
• Anmodninger, der er ekskluderet som kundefejl eller budgetnægtelser, tælles ikke som leverandørafbrydelsespåvirkning

Forudsigelser og designindsatser

Forudsigelse: kundevendt udfaldsrapportering bliver en normal funktion af AI API forhandlerplatforme, især for SaaS-leverandører, der eksponerer AI-funktioner under deres eget varemærke. Efterhånden som AI-arbejdsbelastninger bevæger sig fra eksperimentering til produktion, vil kunderne forvente den samme hændelsesansvarlighed, som de modtager fra leverandører af cloud-infrastruktur.

Forudsigelse: udbyderstatussider forbliver nødvendige, men utilstrækkelige. Flere hændelser vil involvere delvis forringelse: latenstidsspidser, streamingafbrydelser, regionale kapacitetsproblemer, kvalitetsregressioner, fejl i værktøjsopkald eller kontospecifik kvoteadfærd. Disse sager kræver bevis på anmodningsniveau og lejerniveau.

Anbefaling: opbyg hovedbogen, før du lover stærke SLA-kreditter. Eftermontering af hændelsesbeviser efter en omstridt driftsafbrydelse er dyrt og ofte uoverskueligt.

Handlingsbar konklusion

Lad ikke udbyderstatussider blive din eneste kilde til sandhed for kundekreditter. Opbyg en afbrydelsesbeviser, der forbinder udbyderhændelsesfeeds, syntetiske kanariefugle, anmodningssymptomer, rutebeslutninger, lejers indvirkningsvinduer, faktureringsregistreringer og endelige kreditjusteringer.

Den mindste brugbare version er ligetil: indtag udbyderstatus JSON, kør lavvolumen-kanariefugle for solgte modelregion-niveauer, klassificer anmodningsfejl efter årsag, beregn lejers indvirkningsvinduer og anvend en versioneret kreditpolitik efter afstemning. Det giver support, økonomi, teknik og downstream-partnere det samme bevisgrundlag. Det giver dig også mulighed for at forklare hændelser uden blindt at spejle upstream-statussider eller udstede manuelle goodwill-kreditter, når en kunde klager.

Relateret læsning

• kundevendt brugs- og justeringsrapportering