Upravljajte Anthropic API verzijama i beta zaglavljima u pristupniku s više korisnika

Anthropic-kompatibilan API pristupnik ne bi trebao tretirati anthropic-version i anthropic-beta kao obična prolazna zaglavlja. Oni odabiru ponašanje protokola i eksperimentalne mogućnosti koje mogu promijeniti pravila provjere valjanosti, blokove odgovora, strujanje događaja, dostupnost, cijene i obračun predmemorije.

Praktični problem je očuvanje izvornog Claude ponašanja bez dopuštanja zaglavljima zahtjeva jednog stanara da zaobiđu pravila platforme. Rješenje je da pristup protokolu postane prvorazredna odluka pristupnika: autentificirajte pozivatelja, riješite njegovu politiku verzije, potvrdite tražene beta značajke, odaberite kompatibilnu rutu i zabilježite točno ono što je poslano uzvodno.

Definirajte granicu pravila

Činjenica: Izravni Claude API zahtjevi zahtijevaju anthropic-version zaglavlje, iako ga službeni SDK-ovi obično daju. Anthropic beta značajke zahtijevaju se putem anthropic-beta ili SDK-specifičnog beta parametra.

Preporuka: Obje vrijednosti protumačite kao tražene mogućnosti, a ne kao pouzdane upute za usmjeravanje. Klijent može tražiti verziju ili beta verziju, ali pristupnik odlučuje je li ta kombinacija podržana za zakupca, API ključ, model, regiju i vjerodajnice uzvodno.

Nemojte potiho uklanjati neodobrenu beta verziju. To može eksplicitni zahtjev pretvoriti u uspješan poziv s različitom semantikom. Odbijte ga prije slanja uz pogrešku stabilnog pristupnika koja identificira nepodržanu sposobnost bez izlaganja uzvodnih vjerodajnica ili pojedinosti interne rute.

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

Vrati odgovor 4xx za neuspjele pristupa i rezerviraj odgovore 5xx za neuspjehe pristupnika ili uzvodne mreže. Održavajte shemu pogreške stabilnom čak i ako Anthropic promijeni vlastiti format pogreške.

Izradite registar verzija i mogućnosti

Niz verzije u obliku datuma lako je provjeriti sintaktički, ali je nemoguće upravljati samo sintaksom. Gateway treba registar koji sadrži verzije i beta značajke koje je zapravo testirao.

Zapisi o verziji

Svaki zapis verzije treba sadržavati:

• Identifikator kanonske verzije i stanje životnog ciklusa: testiranje, dostupno, zadano, zastarjelo ili blokirano.
• Podržana polja zahtjeva, blokovi sadržaja, razlozi zaustavljanja, polja upotrebe i poznati događaji strujanja.
• Kompatibilni modeli, uzvodne platforme, regije i skupovi vjerodajnica.
• Rezultati ugovora i datum posljednjeg uspješnog testa.
• Kompatibilnost kataloga s cijenama i sve poznate implikacije za obračun predmemorije.
• Ograničenja usvajanja, datumi obustave i smjernice za zamjenu.

Beta zapisi

Beta značajke trebaju zasebne zapise jer se njihova dostupnost i operativni rizik mogu razlikovati od osnovne API verzije. Zabilježite naziv kanonske beta verzije, kompatibilne verzije i modele, dopuštene regije, obavezna polja zahtjeva, moguće blokove odgovora, strujanje događaja, cjenovni tretman, klasu ograničenja brzine i stanje uvođenja.

Modelirajte ovo kao podatke, a ne kao uvjete aplikacije. Procjenitelj politike tada može odgovoriti na konkretno pitanje: "Smije li ključ K koristiti verziju V s beta skupom B na ruti R?" Isti katalog može podržati multi-model API gateway za timove bez prisiljavanja svakog adaptera da implementira vlastita pravila stanara.

Dajte svakom zakupcu izričitu politiku verzije

Podržava tri načina pravila:

1. Prikvačeno: Stanar ili ključ mora koristiti jednu točnu verziju. Odbaci nedostajuće ili različite vrijednosti.
2. Gateway current: Zaglavlje koje nedostaje rješava se testiranom zadanom postavkom pristupnika. Eksplicitna vrijednost klijenta i dalje je potvrđena.
3. Odobreni raspon: Klijent može odabrati s konačnog popisa dopuštenih testiranih verzija.

Izbjegavajte tumačenje "raspona" kao svakog datuma između dvije krajnje točke. Anthropic verzije su identifikatori, a ne kontinuirani niz semantičkih verzija. Pohranite eksplicitan skup dopuštenih vrijednosti.

Razriješite efektivnu verziju prije odabira uzvodne 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)

Držite tražene i efektivne vrijednosti odvojeno. Mogu se razlikovati ako pravilo daje zadanu vrijednost, ali revizijski zapis mora učiniti tu zamjenu vidljivom.

Raščlanjivanje beta zaglavlja strukturalno

Nemojte odobriti beta značajke s podudaranjem podnizova ili jednakosti sirovih nizova. Raščlanite zaglavlje u skladu sa sintaksom koju prihvaća uzlazni API, odbacite pogrešno oblikovane ili duplicirane unose prema potrebi i usporedite kanonske identifikatore značajki.

Kanonski poredak je koristan za ključeve predmemorije pravila i dimenzije telemetrije:

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

Sačuvajte dovoljno metapodataka zahtjeva za otklanjanje pogrešaka, ali ne zadržavajte neobrađena zaglavlja na neodređeno vrijeme kada su dovoljni normalizirani identifikatori. Dnevnici zaglavlja mogu sadržavati nepotrebne metapodatke klijenta, a njihovo pohranjivanje povećava opseg zadržavanja i kontrola pristupa.

Beta autorizacija trebala bi biti obuhvaćena zakupcem i po mogućnosti ključem. Razvojni ključ može dobiti eksperimentalnu sposobnost bez da je automatski dodijeli proizvodnim radnim opterećenjima. Promjene popisa dopuštenih trebale bi proizvesti događaje revizije kontrolne razine s akterom, razlogom, prethodnim stanjem, novim stanjem i efektivnim vremenom.

Odvojite ulaz od usmjeravanja

Zahtjev se ne može usmjeravati samo zato što postoji naziv njegovog modela. Podobnost rute je presjek mogućnosti protokola i infrastrukture:

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

Ako nijedna ruta ne zadovoljava cijeli skup, ne uspije prije slanja zahtjeva. Ne ispuštajte beta značajke kako bi ruta bila prihvatljiva. Nemojte automatski zamijeniti drugu verziju osim ako pravila zakupca izričito ne definiraju takvo ponašanje.

Ovo odvajanje je važno u pristupnicima koji skupljaju vjerodajnice, podržavaju ključeve koje dostavljaju korisnici ili rade u različitim regijama. Dvije rute do istog modela mogu imati različit pristup značajkama, ograničenja prebivališta ili ograničenja stope.

Očuvanje izvorne semantike odgovora

Činjenica: Anthropic Odgovori na poruke mogu završiti s razlozima uključujući upotrebu alata, ograničenja tokena, ograničenja prozora konteksta, pauzirana kretanja i odbijanja. Streaming odgovori koriste imenovane događaje poslane s poslužitelja, a Anthropic smjernice za kompatibilnost zahtijevaju da klijenti toleriraju nove vrste događaja.

Preporuka: Nemojte sažimati sva uspješna stanja terminala u "dovršeno." Sačuvajte uzvodni razlog zaustavljanja u izvornom odgovoru i telemetriji pristupnika. Aplikacije će možda trebati izvršiti alat, nastaviti pauzirani potez, smanjiti kontekst ili prikazati odbijanje.

Stream proxy treba prepoznati događaje koji su potrebni za računovodstvo i upravljanje životnim ciklusom, a pritom ostati kompatibilan prema naprijed:

• Prosljeđivanje nepoznatih vrsta događaja kada pravila zakupca dopuštaju nativni prolaz.
• Zadrži neobrađeni naziv događaja i poziciju niza u ograničenim dijagnostičkim metapodacima.
• Nemojte koristiti iscrpan enum koji zatvara tok na nepoznatom aditivnom događaju.
• Razlikujte uzvodni događaj pogreške od prekida veze prijenosa i otkazivanja klijenta.
• Dovršite korištenje samo iz ovlaštenih polja; označi nepotpune tokove kao privremene kada konačna upotreba nije dostupna.

Ako pristupnik također izlaže krajnju točku u obliku OpenAI, držite taj adapter odvojen od izvorne staze poruka. Anthropic OpenAI sloj kompatibilnosti ima dokumentirana ograničenja polja i značajki. Uobičajena interna omotnica može pomoći pri usmjeravanju, ali ne smije odbaciti redoslijed blokova sadržaja, kontrole predmemorije, potpise razmišljanja, stanje alata ili razloge zaustavljanja specifične za pružatelja usluga.

Usvijestite o verziji računovodstva

Činjenica: Upotreba brze predmemorije odvaja obične ulazne tokene, ulazne tokene za stvaranje predmemorije i ulazne tokene za čitanje predmemorije. Ukupna potrošnja inputa mora uzeti u obzir sve primjenjive kategorije.

Promjena verzije ili beta može promijeniti podobnost predmemorije, prikaz sadržaja ili vraćena polja upotrebe. Stoga bi svaki događaj korištenja trebao uključivati:

• Tražena i učinkovita API verzija.
• Zatraženi i dopušteni beta setovi.
• Zakupac, API ključ, pravilo, ruta, model, regija i ID uzlaznog zahtjeva.
• Status, razlog zaustavljanja, stanje završetka streama i pripisivanje pogreške.
• Kategorije tokena ulaza, izlaza, stvaranja predmemorije i čitanja predmemorije.
• Verzija kataloga s cijenama i stanje privremenog ili konačnog troška.

Ove dimenzije omogućuju objedinjenoj AI API naplati objašnjenje zašto su inače slični zahtjevi proizveli različite troškove. Izbjegavajte naplatu iz jednog kombiniranog broja tokena kada pružatelj izlaže kategorije s različitim stopama.

Testirajte prije omogućavanja verzije ili beta

Stvorite ugovorne postavke za obični tekst, strujni tekst, pozive alata, strukturirani izlaz, odbijanja, skraćivanje tokena, iscrpljenost kontekstnog prozora, pauzirana skretanja, brzo predmemoriju, neispravne zahtjeve, ograničenja brzine i pogreške usred toka.

Za svaki raspored, usporedite više od HTTP statusa. Zabilježite vrstu i redoslijed bloka sadržaja, razlog zaustavljanja, identifikatore i argumente alata, redoslijed događaja, prisutnost polja upotrebe, kategorije predmemorije i oblik pogreške. Pohranite odobrena strukturna očekivanja radije nego točan prozni rezultat.

Koristite zahtjeve u sjeni samo kada je sigurno dvostruko izvršenje. Zahtjevi s alatima, vanjskim nuspojavama, osjetljivim podacima ili troškovima materijala mogu biti neprikladni. Za ta radna opterećenja, reproducirajte dezinficirane utakmice u kontroliranom okruženju.

Predviđanje: Nove verzije i beta značajke nastavit će dodavati varijante odgovora i događaje. Pristupnik dizajniran oko zapisa o mogućnostima i aditivnog parsiranja obično će apsorbirati te promjene s manje hitnog rada nego onaj izgrađen oko fiksnih enuma i globalnih zadanih vrijednosti.

Sigurno uvođenje i povlačenje mogućnosti

Promovirajte sposobnost putem testiranja, internog, opt-in, canary, dostupnog, zastarjelog i blokiranog stanja. Tijekom kanariranja, usporedite distribucije statusa, razloge zaustavljanja, sekvence blokova sadržaja, ponašanje alata, polja upotrebe, latenciju i ishode predmemorije. Definirajte pragove vraćanja prije početka prometa.

Umirovljenje bi se trebalo dogoditi u fazama:

1. Blokiraj usvajanje novog stanara dok se postojeći dodjele nastavljaju.
2. Identificirajte pogođene stanare, ključeve, modele i nedavne uzorke zahtjeva.
3. Pružite izvješće o kompatibilnosti ili testirajte krajnju točku za zamjenu.
4. Upozorite na primljene zahtjeve i objavite čvrsto ograničenje.
5. Zahtijevaj izričite iznimke s vlasnicima i datumima isteka.
6. Blokirajte mogućnost i zadržite zapis registra za povijesnu reviziju i tumačenje naplate.

Prikvačivanje povećava ponovljivost, ali proširuje testnu matricu. Verzija za cijeli pristupnik smanjuje operativne varijante, ali spaja nepovezane stanare u jedan raspored migracije. Široki beta prolaz ubrzava pristup značajkama, ali slabi cijenu, prebivalište i jamstva podrške. Za uslugu s više stanara, eksplicitna politika za svakog stanara obično je branjiva sredina.

Popis za provjeru implementacije

• Zahtijevaj pravilo verzije za svakog stanara ili API ključ.
• Održavajte evidenciju testirane verzije i beta mogućnosti.
• Odbacite krivo oblikovane, nepoznate ili neovlaštene mogućnosti prije slanja.
• Odaberite rute tek nakon rješavanja kompletnog zahtjeva protokola.
• Očuvajte izvorne blokove sadržaja, razloge zaustavljanja, polja upotrebe i streamove.
• Sigurno proslijedite događaje dodatnog toka i zadržite njihove nazive događaja.
• Zabilježite tražene i efektivne vrijednosti protokola o korištenju i revizijskim događajima.
• Pokreni ugovorne rasporede i kontrolirane kanarince prije promjene zadanih postavki.
• Povući stare mogućnosti kroz odmjerene kontrole usvajanja, a ne tihim prepisivanjem.

Ključna odluka o dizajnu je jednostavna: verzija i beta zaglavlja su ulazi pravila. Nakon što ih pristupnik prihvati, usmjeri, testira i mjeri kao mogućnosti, izvorna API kompatibilnost postaje moguća bez pretvaranja da su eksperimentalno ponašanje obični HTTP metapodaci.

Povezano čitanje

• računavanje konačne upotrebe, otkazivanja i djelomičnog strujanja odgovori