Styr Anthropic API-versioner og beta-headere i en Multi-Tenant Gateway

En Anthropic-kompatibel API-gateway bør ikke behandle anthropic-version og anthropic-beta som almindelige pass-through-headere. De vælger protokoladfærd og eksperimentelle muligheder, der kan ændre valideringsregler, svarblokeringer, streaminghændelser, tilgængelighed, prissætning og cacheregnskab.

Det praktiske problem er at bevare den oprindelige Claude-adfærd uden at tillade en lejers anmodningsheadere at omgå platformpolitikken. Løsningen er at gøre protokoladgang til en førsteklasses gateway-beslutning: godkend den, der ringer, løs dens versionspolitik, valider anmodede betafunktioner, vælg en kompatibel rute, og optag præcis, hvad der blev sendt opstrøms.

Definer politikgrænsen

Fakta: Direkte Claude API anmodninger kræver en anthropic-version header, selvom officielle SDK'er normalt leverer det. Anthropic betafunktioner anmodes om via anthropic-beta eller en SDK-specifik betaparameter.

Anbefaling: Fortolk begge værdier som anmodede egenskaber, ikke betroede routinginstruktioner. En klient kan anmode om en version eller beta, men gatewayen afgør, om denne kombination er understøttet for lejer, API-nøgle, model, region og upstream-legitimationsoplysninger.

Du må ikke fjerne en ikke-godkendt beta-version. Det kan gøre en eksplicit anmodning til et vellykket opkald med forskellig semantik. Afvis det før afsendelse med en stabil gateway-fejl, der identificerer den ikke-understøttede funktion uden at afsløre opstrøms-legitimationsoplysninger eller interne rutedetaljer.

{
  "type": "gateway_policy_error",
  "code": "beta_not_allowed",
  "message": "The requested Anthropic beta is not enabled for this API key.",
  "details": {
    "beta": "example-beta-2026-01-01",
    "policy_id": "claude-production"
  }
}

Returner et 4xx-svar for adgangsfejl, og reserver 5xx-svar til gateway- eller upstream-fejl. Hold fejlskemaet stabilt, selvom Anthropic ændrer sit eget fejlformat.

Byg et versions- og funktionsregister

En datoformet versionsstreng er let at validere syntaktisk, men umulig at styre ud fra syntaks alene. Gatewayen har brug for et register, der indeholder de versioner og betafunktioner, den faktisk har testet.

Versionsposter

Hver versionspost skal indeholde:

• Kanonisk version-id og livscyklustilstand: testning, tilgængelig, standard, forældet eller blokeret.
• Understøttede anmodningsfelter, indholdsblokeringer, stopårsager, brugsfelter og kendte streaminghændelser.
• Kompatible modeller, upstream-platforme, regioner og legitimationspuljer.
• Resultater af kontraktopstilling og datoen for den seneste vellykkede test.
• Priskatalogkompatibilitet og alle kendte cache-konti-implikationer.
• Adoptionsrestriktioner, udfasningsdatoer og udskiftningsvejledning.

Beta records

Betafunktioner kræver separate registreringer, fordi deres tilgængelighed og operationelle risiko kan afvige fra basisversionen af API. Registrer det kanoniske betanavn, kompatible versioner og modeller, tilladte områder, obligatoriske anmodningsfelter, mulige svarblokke, streaminghændelser, prisbehandling, hastighedsgrænseklasse og udrulningstilstand.

Model dette som data i stedet for applikationsbetingelser. En politikevaluator kan derefter besvare et konkret spørgsmål: "Må nøgle K bruge version V med betasæt B på rute R?" Det samme katalog kan understøtte en multi-model API gateway for teams uden at tvinge hver adapter til at implementere sine egne lejerregler.

Giv hver lejer en eksplicit versionspolitik

Understøtte tre politiktilstande:

1. Pinned: Lejeren eller nøglen skal bruge én nøjagtig version. Afvis manglende eller forskellige værdier.
2. Gateway nuværende: En manglende overskrift løser til gatewayens testede standard. En eksplicit klientværdi er stadig valideret.
3. Godkendt område: Klienten kan vælge fra en begrænset tilladelsesliste over testede versioner.

Undgå at fortolke "interval" som hver dato mellem to endepunkter. Anthropic versioner er identifikatorer, ikke en kontinuerlig semantisk versionssekvens. Gem et eksplicit sæt tilladte værdier.

Løs den effektive version, før du vælger en opstrømsrute:

requested = parse_version_header(request)
policy = load_policy(tenant_id, api_key_id)
effective = resolve_version(requested, policy, registry)
betas = parse_and_canonicalize_betas(request)
admitted = authorize_betas(betas, policy, effective, registry)
route = select_compatible_route(model, region, effective, admitted)
dispatch(route, effective, admitted)

Hold de anmodede og effektive værdier adskilt. De kan være forskellige, når en politik angiver en standard, men en revisionspost skal gøre denne erstatning synlig.

Parse beta-headere strukturelt

Godkend ikke betafunktioner med understrengs-matchning eller rå-streng-lighed. Parse headeren i overensstemmelse med den syntaks, der er accepteret af upstream API, afvis forkert udformede eller duplikerede poster efter behov, og sammenlign kanoniske feature-id'er.

Kanonisk bestilling er nyttig til politikcache-nøgler og telemetridimensioner:

requested header: beta-b, beta-a
canonical policy set: [beta-a, beta-b]
upstream header: beta-b,beta-a  // serialized in accepted upstream syntax

Bevar nok anmodningsmetadata til fejlretning, men behold ikke rå overskrifter på ubestemt tid, når normaliserede identifikatorer er tilstrækkelige. Header-logfiler kan indeholde unødvendige klient-metadata, og lagring af dem øger omfanget af opbevaring og adgangskontrol.

Beta-godkendelse bør være lejer-omfang og helst nøgle-omfang. En udviklingsnøgle kan modtage en eksperimentel kapacitet uden automatisk at give den til produktionsarbejdsbelastninger. Ændringer af tilladelseslister bør producere kontrolplan-revisionsbegivenheder med aktør, årsag, tidligere tilstand, ny tilstand og effektiv tid.

Separat adgang fra routing

En anmodning kan ikke dirigeres, blot fordi dens modelnavn findes. Ruteberettigelse er skæringspunktet mellem protokol- og infrastrukturkapacitet:

eligible(route) =
  route.platform supports effective_version
  AND route.model supports every admitted_beta
  AND route.region permits every admitted_beta
  AND route.credentials are entitled to those capabilities
  AND route.pricing_catalog can account for the result

Hvis ingen rute opfylder det fulde sæt, skal du mislykkes, før du sender anmodningen. Slip ikke betafunktioner for at gøre en rute kvalificeret. Udskift ikke automatisk en anden version, medmindre lejerpolitikken udtrykkeligt definerer denne adfærd.

Denne adskillelse er vigtig i gateways, der samler legitimationsoplysninger, understøtter kundeleverede nøgler eller fungerer på tværs af regioner. To ruter til den samme model kan have forskellig funktionsadgang, opholdsbegrænsninger eller takstgrænser.

Bevar native respons-semantik

Fakta: Anthropic Beskedersvar kan ende med årsager, herunder brug af værktøj, token-grænser, kontekstvinduegrænser, pausede drejninger og afvisninger. Streamingsvar bruger navngivne server-sendte hændelser, og Anthropics kompatibilitetsvejledning kræver, at klienter tolererer nye hændelsestyper.

Anbefaling: Undlad at skjule alle vellykkede terminaltilstande til "fuldført". Bevar opstrøms stopårsagen i det oprindelige svar og i gateway-telemetri. Applikationer skal muligvis udføre et værktøj, fortsætte en pause, reducere kontekst eller vise et afslag.

Strømproxyen bør genkende hændelser, der kræves til regnskab og livscyklusstyring, mens den forbliver fremadkompatibel:

• Videresend ukendte hændelsestyper, når lejerens politik tillader indbygget pass-through.
• Behold det rå hændelsesnavn og sekvensposition i afgrænsede diagnostiske metadata.
• Brug ikke en udtømmende enum, der lukker strømmen ved en ukendt tilføjelsesbegivenhed.
• Skelne en opstrøms fejlhændelse fra en transportafbrydelse og en klientannullering.
• Afslut kun brug fra autoritative felter; markér ufuldstændige streams som foreløbige, når endelig brug ikke er tilgængelig.

Hvis gatewayen også afslører et OpenAI-formet slutpunkt, skal du holde denne adapter adskilt fra den oprindelige meddelelsessti. Anthropics OpenAI kompatibilitetslag har dokumenterede felt- og funktionsbegrænsninger. En fælles intern konvolut kan hjælpe med routing, men den må ikke kassere indholdsblokrækkefølge, cachekontroller, tænkende signaturer, værktøjstilstand eller udbyderspecifikke stopårsager.

Gør regnskabsversionsbevidst

Fakta: Brug af prompt-cache adskiller almindelige input-tokens, cache-oprettelse-input-tokens og cache-læse-input-tokens. Det samlede inputforbrug skal tage højde for alle relevante kategorier.

En version eller betaændring kan ændre cache-kvalificering, indholdsrepræsentation eller returnerede brugsfelter. Derfor bør enhver brugshændelse indeholde:

• Anmodet og effektiv API version.
• Anmodede og godkendte betasæt.
• Lejer, API-nøgle, politik, rute, model, region og upstream-anmodnings-id.
• Status, stopårsag, strømafslutningstilstand og fejltilskrivning.
• Input-, output-, cache-oprettelse og cache-læste tokenkategorier.
• Priskatalogversion og foreløbig eller endelig omkostningstilstand.

Disse dimensioner lader unified AI API billing forklare, hvorfor lignende anmodninger ellers gav forskellige omkostninger. Undgå fakturering fra et enkelt kombineret tokenantal, når udbyderen afslører kategorier med forskellige takster.

Test før du aktiverer en version eller beta

Opret kontraktarmaturer for almindelig tekst, streaming tekst, værktøjskald, struktureret output, afvisninger, token-trunkering, kontekstvindueudmattelse, pausede vendinger, promptcaching, misformede anmodninger, hastighedsgrænser og mid-stream-fejl.

Sammenlign status for mere end HTTP for hver opstilling. Indfang indholdsbloktype og rækkefølge, stopårsag, værktøjs-id'er og argumenter, hændelsessekvens, tilstedeværelse af brugsfelter, cachekategorier og fejlform. Gem godkendte strukturelle forventninger frem for nøjagtige prosaoutput.

Brug kun skyggeanmodninger, når duplikatudførelse er sikker. Forespørgsler med værktøjer, eksterne bivirkninger, følsomme data eller materialeomkostninger kan være uegnede. For disse arbejdsbelastninger skal du genafspille desinficerede armaturer i et kontrolleret miljø.

Forudsigelse: Nye versioner og betafunktioner vil fortsætte med at tilføje svarvarianter og begivenheder. En gateway, der er designet omkring kapacitetsregistreringer og additiv parsing, vil normalt absorbere disse ændringer med mindre nødarbejde end en, der er bygget op omkring faste opgørelser og globale standardindstillinger.

Rul ud og træk funktionerne ud på en sikker måde

Fremme en kapacitet gennem test, intern, opt-in, canary, tilgængelig, forældet og blokeret tilstand. Sammenlign statusfordelinger, stopårsager, indholdsbloksekvenser, værktøjsadfærd, brugsfelter, latenstid og cache-resultater under kanariefågen. Definer rollback-tærskler, før trafikken begynder.

Pensionering bør ske i etaper:

1. Bloker adoption af nye lejere, mens eksisterende opgaver fortsætter.
2. Identificer berørte lejere, nøgler, modeller og seneste anmodningsmønstre.
3. Giv en kompatibilitetsrapport eller testslutpunkt for erstatningen.
4. Advar om indrømmede anmodninger og offentliggør en fast cutoff.
5. Kræv eksplicitte undtagelser med ejere og udløbsdatoer.
6. Bloker kapaciteten, og behold registreringsdatabasen for historisk revision og faktureringsfortolkning.

Fastning øger reproducerbarheden, men udvider testmatrixen. En gateway-dækkende version reducerer driftsvarianter, men kobler ikke-relaterede lejere til én migreringsplan. Bred beta-pass-through accelererer adgang til funktioner, men svækker omkostninger, opholdstilladelse og supportgarantier. For en tjeneste med flere lejere er en eksplicit per-lejer-politik normalt den forsvarlige mellemvej.

Implementeringstjekliste

• Kræv en versionspolitik for hver lejer eller API-nøgle.
• Opretholdelse af testede versioner og betafunktioner.
• Afvis forkerte, ukendte eller uautoriserede funktioner før afsendelse.
• Vælg kun ruter efter at have løst hele protokolanmodningen.
• Bevar native indholdsblokeringer, stopårsager, brugsfelter og streams.
• Videresend additive stream-begivenheder sikkert, og behold deres begivenhedsnavne.
• Optag anmodede og effektive protokolværdier for brugs- og revisionsbegivenheder.
• Kør kontraktopstillinger og kontrollerede kanariefugle, før du ændrer standardindstillinger.
• Træk gamle kapaciteter tilbage gennem målte adoptionskontroller, ikke tavse omskrivninger.

Nøgledesignbeslutningen er enkel: versions- og betaheadere er politikinput. Når gatewayen indrømmer, ruter, tester og måler dem som kapaciteter, bliver indbygget API-kompatibilitet regulerbar uden at foregive, at eksperimentel adfærd er almindelige HTTP metadata.

Relateret læsning

• opgørelse af endelige, brugs- og partielle afregninger for streaming, brug og partial afregning svar