Styr Anthropic API versjoner og betaoverskrifter i en multi-tenant gateway

En Anthropic-kompatibel API-gateway bør ikke behandle anthropic-version og anthropic-beta som vanlige pass-through-hoder. De velger protokollatferd og eksperimentelle funksjoner som kan endre valideringsregler, svarblokkeringer, strømmehendelser, tilgjengelighet, priser og bufferregnskap.

Det praktiske problemet er å bevare den opprinnelige Claude-atferden uten å tillate en leietakers forespørselshoder å omgå plattformens retningslinjer. Løsningen er å gjøre protokolltilgang til en førsteklasses gateway-beslutning: autentiser den som ringer, løs versjonspolicyen, valider forespurte betafunksjoner, velg en kompatibel rute og registrer nøyaktig hva som ble sendt oppstrøms.

Definer policygrensen

Fakta: Direkte Claude API-forespørsler krever en anthropic-version-overskrift, selv om offisielle SDK-er vanligvis leverer den. Anthropic betafunksjoner er forespurt gjennom anthropic-beta eller en SDK-spesifikk betaparameter.

Anbefaling: Tolk begge verdiene som forespurte funksjoner, ikke pålitelige rutinginstruksjoner. En klient kan be om en versjon eller beta, men gatewayen avgjør om denne kombinasjonen støttes for leieren, API-nøkkelen, modellen, regionen og oppstrømslegitimasjonen.

Ikke fjern en ikke-godkjent betaversjon. Det kan gjøre en eksplisitt forespørsel til en vellykket samtale med annen semantikk. Avvis den før sending med en stabil gateway-feil som identifiserer den ikke-støttede funksjonen uten å avsløre oppstrømslegitimasjon 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 opptaksfeil og reserver 5xx-svar for gateway- eller oppstrømsfeil. Hold feilskjemaet stabilt selv om Anthropic endrer sitt eget feilformat.

Bygg et versjons- og kapasitetsregister

En datoformet versjonsstreng er enkel å validere syntaktisk, men umulig å styre fra syntaks alene. Gatewayen trenger et register som inneholder versjonene og betafunksjonene den faktisk har testet.

Versjonsposter

Hver versjonspost bør inneholde:

• Kanonisk versjonsidentifikator og livssyklusstatus: testing, tilgjengelig, standard, avviklet eller blokkert.
• Støttede forespørselsfelt, innholdsblokkeringer, stoppårsaker, bruksfelt og kjente strømmehendelser.
• Kompatible modeller, oppstrømsplattformer, regioner og legitimasjonsgrupper.
• Resultater av kontrakter og datoen for den siste vellykkede testen.
• Kompatibilitet med priskatalog og alle kjente implikasjoner for cache-regnskap.
• Adopsjonsbegrensninger, avviklingsdatoer og erstatningsveiledning.

Beta-poster

Betafunksjoner trenger separate poster fordi deres tilgjengelighet og operasjonelle risiko kan avvike fra grunnversjonen API. Registrer det kanoniske betanavnet, kompatible versjoner og modeller, tillatte regioner, obligatoriske forespørselsfelt, mulige svarblokkeringer, strømmehendelser, prisbehandling, rategrenseklasse og utrullingstilstand.

Model dette som data i stedet for applikasjonsbetingelser. En policy-evaluator kan deretter svare på et konkret spørsmål: "Kan nøkkel K bruke versjon V med betasett B på rute R?" Den samme katalogen kan støtte en multi-model API gateway for teams uten å tvinge hver adapter til å implementere sine egne leietakerregler.

Gi hver leietaker en eksplisitt versjonspolicy

Støtt tre policymoduser:

1. Pinned: Leietakeren eller nøkkelen må bruke én eksakt versjon. Avvis manglende eller andre verdier.
2. Gateway gjeldende: En manglende overskrift løser til gatewayens testede standard. En eksplisitt klientverdi er fortsatt validert.
3. Godkjent område: Klienten kan velge fra en begrenset godkjenningsliste over testede versjoner.

Unngå å tolke «område» som hver dato mellom to endepunkter. Anthropic versjoner er identifikatorer, ikke en kontinuerlig semantisk versjonssekvens. Lagre et eksplisitt sett med tillatte verdier.

Løs den effektive versjonen før du velger en oppstrøms rute:

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 forespurte og effektive verdiene atskilt. De kan være forskjellige når en policy angir en standard, men en revisjonspost må gjøre denne erstatningen synlig.

Parse beta-overskrifter strukturelt

Ikke autoriser betafunksjoner med understrengsamsvar eller råstrenglikhet. Parse overskriften i henhold til syntaksen som er akseptert av oppstrøms API, avvis misformede eller dupliserte oppføringer etter behov, og sammenlign kanoniske funksjonsidentifikatorer.

Kanonisk bestilling er nyttig for policy-buffernøkler og telemetridimensjoner:

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

Oppbevar nok forespørselsmetadata for feilsøking, men behold ikke råhoder på ubestemt tid når normaliserte identifikatorer er tilstrekkelige. Overskriftslogger kan inneholde unødvendige klientmetadata, og lagring av dem øker omfanget av oppbevaring og tilgangskontroller.

Betaautorisasjon bør være leietaker og helst nøkkelomfang. En utviklingsnøkkel kan motta en eksperimentell evne uten å automatisk gi den til produksjonsarbeidsbelastninger. Endringer i godkjenningslister bør produsere kontroll-planrevisjonshendelser med aktør, årsak, tidligere tilstand, ny tilstand og effektiv tid.

Separat adgang fra ruting

En forespørsel kan ikke rutes bare fordi modellnavnet eksisterer. Rutekvalifisering er skjæringspunktet mellom protokoll- og infrastrukturfunksjoner:

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 tilfredsstiller hele settet, mislykkes før du sender forespørselen. Ikke slipp betafunksjoner for å gjøre en rute kvalifisert. Ikke bytt automatisk ut en annen versjon med mindre leietakerpolicyen eksplisitt definerer denne oppførselen.

Denne separasjonen er viktig i gatewayer som samler legitimasjon, støtter kundeleverte nøkler eller opererer på tvers av regioner. To ruter til samme modell kan ha forskjellig funksjonstilgang, bostedsbegrensninger eller takstgrenser.

Bevar semantikk for opprinnelig respons

Fakta: Anthropic Meldingssvar kan ende med årsaker, inkludert verktøybruk, tokengrenser, kontekstvindugrenser, pauser i svinger og avslag. Strømmesvar bruker navngitte serversendte hendelser, og Anthropics kompatibilitetsveiledning krever at klienter tolererer nye hendelsestyper.

Anbefaling: Ikke skjul alle vellykkede terminaltilstander til «fullført». Bevar oppstrøms stoppårsak i den opprinnelige responsen og i gateway-telemetri. Apper må kanskje kjøre et verktøy, fortsette en pause på pause, redusere kontekst eller avsløre et avslag.

Strømproxyen skal gjenkjenne hendelser som kreves for regnskap og livssyklusadministrasjon, samtidig som den fortsatt er foroverkompatibel:

• Videresend ukjente hendelsestyper når leietakerens retningslinjer tillater native pass-through.
• Behold det rå hendelsesnavnet og sekvensposisjonen i avgrensede diagnostiske metadata.
• Ikke bruk en uttømmende oppsummering som lukker strømmen på en ukjent tilleggshendelse.
• Skill en oppstrøms feilhendelse fra en transportfrakobling og en klientkansellering.
• Fullfør bruk bare fra autoritative felt; merk ufullstendige strømmer som foreløpige når endelig bruk ikke er tilgjengelig.

Hvis gatewayen også viser et OpenAI-formet endepunkt, hold den adapteren atskilt fra den opprinnelige Messages-banen. Anthropics OpenAI-kompatibilitetslag har dokumenterte felt- og funksjonsbegrensninger. En felles intern konvolutt kan hjelpe med ruting, men den må ikke forkaste innholdsblokkeringsrekkefølge, bufferkontroller, tenkesignaturer, verktøystatus eller leverandørspesifikke stoppårsaker.

Gjør regnskapsversjon bevisst

Fakta: Prompt-cache-bruk skiller vanlige input-tokener, cache-oppretting input tokens og cache-read input tokens. Totalt inputforbruk må ta hensyn til alle aktuelle kategorier.

En versjon eller beta-endring kan endre bufferkvalifisering, innholdsrepresentasjon eller returnerte bruksfelt. Derfor bør hver brukshendelse inneholde:

• Forespurt og effektiv API versjon.
• Forespurte og godkjente betasett.
• Leietaker, API-nøkkel, policy, rute, modell, region og oppstrømsforespørsel-ID.
• Status, stoppårsak, status for strømgjennomføring og feilattribusjon.
• Inndata-, utdata-, bufferopprettelse og cache-lese tokenkategorier.
• Priskatalogversjon og foreløpig eller endelig kostnadsstatus.

Disse dimensjonene lar unified AI API billing forklare hvorfor lignende forespørsler ellers ga forskjellige kostnader. Unngå fakturering fra ett enkelt kombinert tokenantall når leverandøren avslører kategorier med forskjellige priser.

Test før du aktiverer en versjon eller beta

Opprett kontrakter for vanlig tekst, strømmetekst, verktøyanrop, strukturert utdata, avslag, tokenavkorting, utmattelse av kontekstvinduer, pauser, hurtigbufring, misformede forespørsler, hastighetsgrenser og midtstrømsfeil.

For hver kamp, sammenlign mer enn HTTP-status. Registrer innholdsblokktype og rekkefølge, stoppårsak, verktøyidentifikatorer og argumenter, hendelsessekvens, bruksfelttilstedeværelse, hurtigbufferkategorier og feilform. Lagre godkjente strukturelle forventninger i stedet for eksakt prosa.

Bruk bare skyggeforespørsler når duplikatkjøring er sikker. Forespørsler med verktøy, eksterne bivirkninger, sensitive data eller materialkostnader kan være uegnet. For disse arbeidsbelastningene kan du spille av desinficerte armaturer i et kontrollert miljø.

Prediksjon: Nye versjoner og betafunksjoner vil fortsette å legge til svarvarianter og hendelser. En gateway designet rundt kapasitetsposter og additiv parsing vil vanligvis absorbere disse endringene med mindre nødarbeid enn en bygd rundt faste oppslag og globale standardinnstillinger.

Rulle ut og trekke tilbake funksjoner trygt

Fremme en funksjon gjennom testing, intern, opt-in, canary, tilgjengelig, avviklet og blokkert tilstand. Sammenlign statusdistribusjoner, stoppårsaker, innholdsblokksekvenser, verktøyadferd, bruksfelt, ventetid og hurtigbufferutfall under kanariering. Definer tilbakeføringsterskler før trafikken begynner.

Pensjonering bør skje i etapper:

1. Blokkér adopsjon av nye leietakere mens eksisterende oppdrag fortsetter.
2. Identifiser berørte leietakere, nøkler, modeller og nylige forespørselsmønstre.
3. Oppgi en kompatibilitetsrapport eller testendepunkt for erstatningen.
4. Advar om innrømmede forespørsler og publiser en fast frist.
5. Krev eksplisitte unntak med eiere og utløpsdatoer.
6. Blokkér funksjonen og behold registerposten for historisk revisjon og faktureringstolkning.

Festing øker reproduserbarheten, men utvider testmatrisen. En gateway-omfattende versjon reduserer driftsvarianter, men kobler ikke-relaterte leietakere til én migreringsplan. Bred beta-gjennomgang akselererer funksjonstilgang, men svekker kostnads-, residens- og støttegarantier. For en tjeneste med flere leietakere er eksplisitte retningslinjer for per-leietakere vanligvis den forsvarlige mellomveien.

Implementeringssjekkliste

• Krev en versjonspolicy for hver leietaker eller API-nøkkel.
• Oppretthold testede versjoner og betafunksjoner.
• Avvis misformede, ukjente eller uautoriserte funksjoner før utsendelse.
• Velg ruter bare etter at du har løst hele protokollforespørselen.
• Bevar innebygde innholdsblokker, stoppårsaker, bruksfelt og strømmer.
• Videresend additive stream-hendelser trygt og behold hendelsesnavnene deres.
• Registrer forespurte og effektive protokollverdier for bruk og revisjonshendelser.
• Kjør kontraktsarmaturer og kontrollerte kanarifugler før du endrer standardinnstillingene.
• Trekk tilbake gamle funksjoner gjennom målte adopsjonskontroller, ikke stille omskrivinger.

Nøkkeldesignbeslutningen er enkel: versjons- og betaoverskrifter er policyinndata. Når gatewayen innrømmer, ruter, tester og måler dem som kapasiteter, blir den opprinnelige API-kompatibiliteten regulerbar uten å late som om eksperimentell atferd er vanlig HTTP metadata.

Relatert lesing

• regnskap for endelig strømming, bruk og partiell kanalisering svar