Upravljajte Anthropic API različice in glave beta v prehodu za več najemnikov

Anthropic-kompatibilen API prehod ne bi smel obravnavati anthropic-version in anthropic-beta kot običajnih prehodnih glav. Izberejo vedenje protokola in eksperimentalne zmogljivosti, ki lahko spremenijo pravila preverjanja, odzivne bloke, pretočne dogodke, razpoložljivost, cene in obračunavanje predpomnilnika.

Praktični problem je ohranjanje izvornega Claude vedenja, ne da bi dovolili, da glave zahtev enega najemnika obidejo politiko platforme. Rešitev je, da sprejem protokola postane prvorazredna odločitev prehoda: preverite pristnost klicatelja, razrešite njegovo politiko različice, potrdite zahtevane funkcije beta, izberite združljivo pot in zabeležite točno tisto, kar je bilo poslano navzgor.

Določite mejo pravilnika

Dejstvo: Neposredne Claude API zahteve zahtevajo anthropic-version glavo, čeprav jo uradni SDK običajno zagotovijo. Anthropic beta funkcije so zahtevane prek anthropic-beta ali parametra beta, specifičnega za SDK.

Priporočilo: Obe vrednosti razlagajte kot zahtevane zmogljivosti, ne kot zaupanja vredna navodila za usmerjanje. Odjemalec lahko zahteva različico ali beta, vendar se prehod odloči, ali je ta kombinacija podprta za najemnika, API ključ, model, regijo in poverilnice navzgor.

Ne odstranjujte tiho neodobrene različice beta. To lahko izrecno zahtevo spremeni v uspešen klic z drugačno semantiko. Zavrnite ga pred pošiljanjem s stabilno napako prehoda, ki identificira nepodprto zmogljivost, ne da bi razkrila poverilnice navzgor ali podrobnosti notranje poti.

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

Vrni odgovor 4xx za neuspele sprejeme in rezerviraj odgovore 5xx za neuspehe prehoda ali navzgor. Naj bo shema napak stabilna, tudi če Anthropic spremeni lastno obliko napake.

Izdelajte register različic in zmogljivosti

Niz različice v obliki datuma je enostavno sintaktično potrditi, vendar ga je nemogoče upravljati samo s sintakso. Prehod potrebuje register, ki vsebuje različice in beta funkcije, ki jih je dejansko preizkusil.

Zapisi različic

Vsak zapis različice mora vsebovati:

• Identifikator kanonične različice in stanje življenjskega cikla: testiranje, na voljo, privzeto, zastarelo ali blokirano.
• Podprta polja zahtev, bloki vsebine, razlogi za zaustavitev, polja uporabe in znani pretočni dogodki.
• Združljivi modeli, zgornje platforme, regije in skupine poverilnic.
• Rezultati pogodbe in datum zadnjega uspešnega preizkusa.
• Združljivost cenovnega kataloga in morebitne znane posledice za obračunavanje predpomnilnika.
• Omejitve uporabe, datumi opustitve in navodila za zamenjavo.

Beta zapisi

Funkcije beta potrebujejo ločene zapise, ker se lahko njihova razpoložljivost in operativno tveganje razlikujeta od osnovne API različice. Zabeležite kanonično ime beta, združljive različice in modele, dovoljene regije, obvezna polja za zahteve, možne odzivne bloke, pretočne dogodke, cenovno obravnavo, razred omejitve stopnje in stanje uvajanja.

Modelirajte to kot podatke in ne kot pogoje aplikacije. Ocenjevalec politike lahko nato odgovori na konkretno vprašanje: "Ali lahko ključ K uporablja različico V z beta nizom B na poti R?" Isti katalog lahko podpira večmodelni API prehod za ekipe, ne da bi moral vsak vmesnik implementirati lastna pravila za najemnike.

Vsakemu najemniku dajte izrecno politiko različice

Podpora za tri načine pravilnika:

1. Pripeto: Najemnik ali ključ mora uporabljati eno točno različico. Zavrni manjkajoče ali drugačne vrednosti.
2. Trenutni prehod: Manjkajoča glava se odpravi na preizkušeno privzeto vrednost prehoda. Izrecna vrednost odjemalca je še vedno potrjena.
3. Odobreni obseg: Stranka lahko izbira s končnega dovoljenega seznama preizkušenih različic.

Izogibajte se interpretaciji »razpona« kot vsakega datuma med dvema končnima točkama. Anthropic različice so identifikatorji, ne neprekinjeno zaporedje semantičnih različic. Shranite eksplicitni nabor dovoljenih vrednosti.

Razrešite učinkovito različico, preden izberete pot proti toku:

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)

Zahtevane in dejanske vrednosti hranite ločeno. Lahko se razlikujejo, če pravilnik zagotavlja privzeto vrednost, vendar mora biti v revizijskem zapisu ta zamenjava vidna.

Strukturno razčleni glave beta

Ne dovolite beta funkcij z ujemanjem podnizov ali enakostjo surovih nizov. Razčlenite glavo v skladu s sintakso, ki jo sprejema zgornji tok API, zavrnite napačno oblikovane ali podvojene vnose, kot je primerno, in primerjajte kanonične identifikatorje funkcij.

Kanonično razvrščanje je uporabno za ključe predpomnilnika pravilnika in 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

Ohrani dovolj metapodatkov zahteve za odpravljanje napak, vendar ne obdrži neobdelanih glav za nedoločen čas, ko zadostujejo normalizirani identifikatorji. Dnevniki glave lahko vsebujejo nepotrebne metapodatke odjemalca, njihovo shranjevanje pa poveča obseg hrambe in nadzor dostopa.

Pooblastilo beta mora biti v obsegu najemnika in po možnosti v obsegu ključa. Razvojni ključ lahko prejme poskusno zmogljivost, ne da bi jo samodejno dodelil proizvodnim delovnim obremenitvam. Spremembe seznamov dovoljenih bi morale ustvariti revizijske dogodke nadzorne ravnine z akterjem, razlogom, prejšnjim stanjem, novim stanjem in efektivnim časom.

Ločite sprejem od usmerjanja

Zahteve ni mogoče usmerjati zgolj zato, ker obstaja njeno ime modela. Primernost poti je presečišče zmogljivosti protokola in 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

Če nobena pot ne izpolnjuje celotnega nabora, pred pošiljanjem zahteve ne uspe. Ne izpustite funkcij beta, da bo pot primerna. Ne zamenjajte samodejno druge različice, razen če pravilnik o najemniku izrecno določa to vedenje.

Ta ločitev je pomembna pri prehodih, ki združujejo poverilnice, podpirajo ključe, ki jih zagotovijo stranke, ali delujejo med regijami. Dve poti do istega modela imata lahko različen dostop do funkcij, omejitve prebivališča ali omejitve hitrosti.

Ohrani izvorno semantiko odgovora

Dejstvo: Anthropic Odgovori na sporočila se lahko končajo z razlogi, vključno z uporabo orodja, omejitvami žetonov, omejitvami kontekstnega okna, začasno ustavljenimi zavoji in zavrnitvami. Pretočni odzivi uporabljajo poimenovane dogodke, ki jih pošlje strežnik, Anthropic pa navodila za združljivost zahtevajo, da odjemalci dopuščajo nove vrste dogodkov.

Priporočilo: Ne strnite vseh uspešnih stanj terminala v »dokončano«. Ohranite razlog za zaustavitev navzgor v izvornem odgovoru in v telemetriji prehoda. Aplikacije bodo morda morale izvesti orodje, nadaljevati začasno ustavljeni obrat, zmanjšati kontekst ali prikazati zavrnitev.

Posrednik toka mora prepoznati dogodke, potrebne za vodenje računovodstva in življenjskega cikla, hkrati pa ostati združljiv naprej:

• Posreduj neznane vrste dogodkov, ko pravilnik najemnika dovoljuje izvorni prehod.
• Ohrani neobdelano ime dogodka in položaj zaporedja v omejenih diagnostičnih metapodatkih.
• Ne uporabljajte izčrpnega enuma, ki zapre tok ob neznanem dogodku dodatka.
• Razločite dogodek napake navzgor od prekinitve transportne povezave in preklica odjemalca.
• Dokončajte uporabo samo iz verodostojnih polj; označi nepopolne tokove kot začasne, ko končna uporaba ni na voljo.

Če prehod izpostavi tudi končno točko v obliki OpenAI, naj bo ta adapter ločen od izvorne poti sporočil. Združljivostna plast Anthropic OpenAI ima dokumentirane omejitve polj in funkcij. Skupna notranja ovojnica lahko pomaga pri usmerjanju, vendar ne sme zavreči vrstnega reda blokov vsebine, kontrol predpomnilnika, miselnih podpisov, stanja orodja ali razlogov za zaustavitev, specifičnih za ponudnika.

Zavedanje različice računovodstva

Dejstvo: Uporaba hitrega predpomnilnika ločuje navadne vhodne žetone, vhodne žetone za ustvarjanje predpomnilnika in vhodne žetone za branje predpomnilnika. Skupna poraba vložkov mora upoštevati vse ustrezne kategorije.

Spremembe različice ali beta lahko spremenijo primernost predpomnilnika, predstavitev vsebine ali vrnjena polja za uporabo. Zato mora vsak dogodek uporabe vključevati:

• Zahtevana in veljavna API različica.
• Zahtevani in sprejeti kompleti beta.
• Najemnik, API ključ, pravilnik, pot, model, regija in ID zahteve navzgor.
• Stanje, razlog za zaustavitev, stanje dokončanja toka in pripis napake.
• Kategorije žetonov za vnos, izhod, ustvarjanje predpomnilnika in branje predpomnilnika.
• Različica cenovnega kataloga in začasno ali končno stanje stroškov.

Te razsežnosti omogočajo poenotenemu AI API obračunavanju pojasniti, zakaj so sicer podobne zahteve povzročile različne stroške. Izogibajte se zaračunavanju iz enega samega kombiniranega števila žetonov, ko ponudnik izpostavi kategorije z različnimi stopnjami.

Preizkusite pred omogočanjem različice ali beta

Ustvarite pogodbene nastavke za običajno besedilo, pretočno besedilo, klice orodij, strukturiran izhod, zavrnitve, obrezovanje žetonov, izčrpanost kontekstnega okna, začasno ustavljene obračanja, hitro predpomnjenje, nepravilno oblikovane zahteve, omejitve hitrosti in napake med tokom.

Za vsako tekmo primerjajte več kot HTTP stanje. Zajemite vrsto in vrstni red bloka vsebine, razlog za zaustavitev, identifikatorje in argumente orodja, zaporedje dogodkov, prisotnost polja uporabe, kategorije predpomnilnika in obliko napake. Shranjujte odobrena strukturna pričakovanja namesto natančnega proznega rezultata.

Uporabi senčne zahteve le, če je podvojena izvedba varna. Zahteve z orodji, zunanjimi stranskimi učinki, občutljivimi podatki ali materialnimi stroški so lahko neprimerne. Za te delovne obremenitve ponovno predvajajte razkužene napeljave v nadzorovanem okolju.

Predvidevanje: Nove različice in funkcije beta bodo še naprej dodajale različice odgovorov in dogodke. Prehod, zasnovan okoli zapisov zmogljivosti in aditivnega razčlenjevanja, bo običajno absorbiral te spremembe z manj nujnega dela kot prehod, zgrajen okoli fiksnih enumov in globalnih privzetih vrednosti.

Varno uvedite in umaknite zmogljivosti

Spodbujajte zmožnost prek testiranj, notranjih stanj, stanj izbire, kanarčkov, razpoložljivih, zastarelih in blokiranih stanj. Med kanariziranjem primerjajte porazdelitve stanja, razloge za zaustavitev, zaporedja blokov vsebine, obnašanje orodja, polja uporabe, zakasnitev in rezultate predpomnilnika. Določite pragove za povrnitev pred začetkom prometa.

Upokojitev bi morala potekati po stopnjah:

1. Blokiraj sprejemanje novih najemnikov, medtem ko se obstoječe dodelitve nadaljujejo.
2. Identificirajte prizadete najemnike, ključe, modele in nedavne vzorce zahtev.
3. Posredujte poročilo o združljivosti ali preizkusite končno točko za zamenjavo.
4. Opozori na sprejete zahteve in objavi trdno mejo.
5. Zahtevaj izrecne izjeme z lastniki in datumi poteka.
6. Blokirajte zmožnost in obdržite zapis registra za preteklo revizijo in razlago zaračunavanja.

Pripenjanje poveča ponovljivost, vendar razširi preskusno matriko. Različica na celotnem prehodu zmanjša operativne različice, vendar združi nepovezane najemnike v en urnik selitve. Širok prehod beta pospeši dostop do funkcij, vendar oslabi garancije glede stroškov, stalnega prebivališča in podpore. Pri storitvi z več najemniki je izrecna politika za vsakega najemnika običajno srednja pot.

Kontrolni seznam za implementacijo

• Zahtevaj pravilnik o različici za vsakega najemnika ali API ključ.
• Vzdržujte zapise o preizkušeni različici in zmogljivosti beta.
• Zavrni napačno oblikovane, neznane ali nepooblaščene zmogljivosti pred pošiljanjem.
• Izberite poti šele po razrešitvi celotne zahteve protokola.
• Ohranite izvorne bloke vsebine, razloge za zaustavitev, polja uporabe in tokove.
• Varno posredujte dogodke dodatnega toka in ohranite njihova imena dogodkov.
• Zabeležite zahtevane in veljavne vrednosti protokola o dogodkih uporabe in revizije.
• Zaženi pogodbene napeljave in nadzorovane kanarčke, preden spremeniš privzete nastavitve.
• Upokojitev starih zmogljivosti z merjenimi kontrolami sprejemanja, ne s tihim prepisovanjem.

Ključna odločitev glede oblikovanja je preprosta: glave različice in beta so vhodi pravilnika. Ko jih prehod sprejme, usmeri, preizkusi in meri kot zmožnosti, postane domača API združljivost obvladljiva, ne da bi se pretvarjali, da je eksperimentalno vedenje navaden HTTP metapodatek.

Sorodno branje

• upoštevanje končne uporabe, odpovedi in delnega pretakanja odgovori