Szabályozott Anthropic API. verziók és béta fejlécek egy többbérlős átjáróban

Egy Anthropic-kompatibilis API átjáró nem kezelheti a anthropic-version és anthropic-beta jeleket közönséges átmenő fejlécként. Kiválasztják a protokoll viselkedését és a kísérleti képességeket, amelyek módosíthatják az érvényesítési szabályokat, a válaszblokkokat, a streamelési eseményeket, a rendelkezésre állást, az árakat és a gyorsítótár-számlázást.

A gyakorlati probléma a natív Claude viselkedés megőrzése anélkül, hogy lehetővé tennénk, hogy a bérlői kérelmek fejlécei megkerüljék a platformszabályzatot. A megoldás az, hogy a protokoll-befogadást első osztályú átjáródöntéssé kell tenni: hitelesíteni kell a hívót, feloldja a verziószabályzatát, érvényesíteni kell a kért bétafunkciókat, kiválasztani egy kompatibilis útvonalat, és pontosan rögzíteni, hogy mit küldtek felfelé.

Határozza meg az irányelvek határait

Tény: A közvetlen Claude API kérésekhez anthropic-version fejléc szükséges, bár a hivatalos SDK-k általában ezt biztosítják. A Anthropic bétafunkciókat a anthropic-beta vagy egy SDK-specifikus bétaparaméteren keresztül kérik.

Javaslat: Mindkét értéket kért képességként értelmezze, nem megbízható útválasztási utasításként. Az ügyfél kérhet verziót vagy bétaverziót, de az átjáró eldönti, hogy ez a kombináció támogatott-e a bérlő, a API kulcs, a modell, a régió és az upstream hitelesítő adatok esetében.

Ne távolítsa el csendben a nem jóváhagyott bétát. Ez egy kifejezett kérést sikeres hívássá változtathat, eltérő szemantikával. Elküldés előtt utasítsa el egy stabil átjáró hibával, amely azonosítja a nem támogatott képességet anélkül, hogy felfedné az upstream hitelesítő adatokat vagy a belső útvonal részleteit.

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

4xx válasz visszaküldése a belépési hibák esetén, és 5xx válasz lefoglalása átjáró vagy upstream hibák esetén. Tartsa stabilan a hibasémát akkor is, ha a Anthropic megváltoztatja a saját hibaformátumát.

Verzió- és képességnyilvántartás létrehozása

A dátum alakú verziókarakterlánc szintaktikailag könnyen ellenőrizhető, de nem lehet pusztán szintaxisból irányítani. Az átjárónak szüksége van egy beállításjegyzékre, amely tartalmazza a ténylegesen tesztelt verziókat és bétafunkciókat.

Verziórekordok

Minden verziórekordnak tartalmaznia kell:

• Kanonikus verzióazonosító és életciklus-állapot: tesztelés, elérhető, alapértelmezett, elavult vagy letiltott.
• Támogatott kérésmezők, tartalomblokkok, leállási okok, használati mezők és ismert streamelési események.
• Kompatibilis modellek, upstream platformok, régiók és hitelesítőadat-készletek.
• A szerződéskötés eredményei és a legutóbbi sikeres teszt dátuma.
• Az árazási katalógus kompatibilitása és a gyorsítótár-könyvelés ismert következményei.
• Elfogadási korlátozások, megszüntetési dátumok és cserére vonatkozó útmutatás.

Béta rekordok

A béta funkcióknak külön rekordra van szükségük, mert elérhetőségük és működési kockázatuk eltérhet az alap API verziótól. Jegyezze fel a kanonikus béta nevet, a kompatibilis verziókat és modelleket, az engedélyezett régiókat, a kötelező kérésmezőket, a lehetséges válaszblokkokat, a streamelési eseményeket, az árkezelést, a sebességkorlátozási osztályt és a közzétételi állapotot.

Modellje ezt adatként, nem pedig alkalmazási feltételekként. A házirend-értékelő ezután válaszolhat egy konkrét kérdésre: „Használhatja a K kulcs az V verziót B bétakészlettel az R útvonalon?” Ugyanez a katalógus támogatja a többmodell API átjárót a csapatoknak anélkül, hogy minden adaptert a saját bérlői szabályainak megvalósítására kényszerítene.

Adjon meg minden bérlőnek egy kifejezett verzióra vonatkozó szabályzatot

Három házirendi mód támogatása:

1. Rögzítve: A bérlőnek vagy kulcsnak pontosan egy verziót kell használnia. Hiányzó vagy eltérő értékek elutasítása.
2. Átjáró aktuális: A hiányzó fejléc feloldja az átjáró tesztelt alapértelmezett értékét. Egy kifejezett ügyfélérték még érvényes.
3. Jóváhagyott tartomány: Az ügyfél a tesztelt verziók véges engedélyezési listájából választhat.

Ne értelmezze a „tartományt” két végpont közötti minden dátumként. A Anthropic verziók azonosítók, nem pedig folyamatos szemantikai verziósorozat. Tárolja a megengedett értékek explicit készletét.

A felfelé irányuló útvonal kiválasztása előtt oldja meg a hatályos verziót:

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)

Tartsa külön a kért és a hatályos értékeket. Ezek eltérhetnek, ha egy szabályzat alapértelmezett értéket ad meg, de az ellenőrzési rekordnak láthatóvá kell tennie ezt a helyettesítést.

Béta fejlécek szerkezeti elemzése

Ne engedélyezze a béta funkciókat részkarakterlánc-egyezéssel vagy nyers karakterlánc-egyenlítéssel. Elemezze a fejlécet az upstream API által elfogadott szintaxis szerint, utasítsa el a helytelenül formázott vagy ismétlődő bejegyzéseket, és hasonlítsa össze a kanonikus jellemzőazonosítókat.

A kanonikus rendezés hasznos az irányelv-gyorsítótár kulcsaihoz és a telemetriai dimenziókhoz:

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

Őrizzen meg elegendő kérési metaadatot a hibakereséshez, de ne őrizze meg végtelenségig a nyers fejléceket, ha a normalizált azonosítók elegendőek. A fejlécnaplók szükségtelen kliens-metaadatokat tartalmazhatnak, és ezek tárolása megnöveli a megőrzési és hozzáférés-szabályozási lehetőségeket.

A béta engedélyezésnek bérlői hatókörűnek, lehetőleg kulcsnak kell lennie. Egy fejlesztői kulcs megkaphatja a kísérleti képességet anélkül, hogy automatikusan megadná a termelési munkaterhelésekhez. Az engedélyezési listák módosításainak vezérlősík-ellenőrzési eseményeket kell létrehozniuk a szereplővel, az okkal, az előző állapottal, az új állapottal és a tényleges időponttal.

Külön belépés az útválasztástól

Egy kérés pusztán azért nem irányítható, mert létezik modellneve. Az útvonal alkalmassága a protokoll és az infrastruktúra-képességek metszéspontja:

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

Ha egyik útvonal sem felel meg a teljes készletnek, akkor a kérés elküldése előtt sikertelen. Ne hagyja ki a béta funkciókat, hogy egy útvonal jogosult legyen. Ne cserélje le automatikusan egy másik verziót, hacsak a bérlői szabályzat kifejezetten nem határozza meg ezt a viselkedést.

Ez a szétválasztás fontos a hitelesítő adatokat összegyűjtő, az ügyfelek által biztosított kulcsokat támogató vagy több régióban működő átjárók esetében. Ugyanahhoz a modellhez vezető két útvonal eltérő funkciókhoz való hozzáféréssel, lakóhely-korlátozással vagy díjszabással rendelkezhet.

Natív válaszszemantika megőrzése

Tény: Anthropic Az üzenetekre adott válaszok okokkal végződhetnek, beleértve az eszközhasználatot, a tokenkorlátokat, a kontextusablak korlátait, a szüneteltetett fordulásokat és az elutasításokat. A streamelési válaszok elnevezett szerver által küldött eseményeket használnak, és a Anthropic kompatibilitási útmutatója megköveteli, hogy az ügyfelek elviseljék az új eseménytípusokat.

Javaslat: Ne csukja össze az összes sikeres terminálállapotot „befejezett” állapotba. Őrizze meg a felfelé irányuló leállási okot a natív válaszban és az átjáró telemetriájában. Előfordulhat, hogy az alkalmazásoknak végre kell hajtaniuk egy eszközt, folytatniuk kell a szüneteltetett fordulatot, csökkenteniük kell a kontextust, vagy meg kell jeleníteniük az elutasítást.

A streamproxynak fel kell ismernie a könyveléshez és az életciklus-kezeléshez szükséges eseményeket, miközben továbbra is kompatibilis:

• Ismeretlen eseménytípusok továbbítása, ha a bérlő házirendje lehetővé teszi a natív áthárítást.
• Őrizze meg a nyers eseménynevet és sorozatpozíciót a korlátos diagnosztikai metaadatokban.
• Ne használjon olyan kimerítő felsorolást, amely lezárja az adatfolyamot egy ismeretlen additív eseménynél.
• Megkülönbözteti a felfelé irányuló hibaeseményt a szállítási kapcsolat megszakításától és az ügyfélmegszakítástól.
• A használatot csak a mérvadó mezőkből zárja le; a befejezetlen adatfolyamokat ideiglenesként jelölje meg, ha a végső felhasználás nem érhető el.

Ha az átjáró egy OpenAI alakú végpontot is felfed, tartsa elkülönítve az adaptert a natív Messages elérési úttól. A Anthropic OpenAI kompatibilitási rétege dokumentált mező- és funkciókorlátokkal rendelkezik. Egy közös belső boríték segíthet az útválasztásban, de nem vetheti el a tartalomblokkolás sorrendjét, a gyorsítótár-vezérlőket, a gondolkodó aláírásokat, az eszközállapotot vagy a szolgáltató-specifikus leállási okokat.

Tegye tisztában a könyvelés verziójával

Tény: A prompt-cache használata elkülöníti a szokásos beviteli tokeneket, a gyorsítótár létrehozására szolgáló beviteli tokeneket és a gyorsítótár-olvasási beviteli tokeneket. A teljes bemeneti fogyasztásnak figyelembe kell vennie az összes alkalmazható kategóriát.

A verzió vagy a béta módosítása megváltoztathatja a gyorsítótár jogosultságát, a tartalommegjelenítést vagy a visszaadott használati mezőket. Ezért minden használati eseménynek tartalmaznia kell a következőket:

• Kért és hatályos API verzió.
• Kért és engedélyezett béta készletek.
• Bérlő, API kulcs, szabályzat, útvonal, modell, régió és felsőbb szintű kérésazonosító.
• Állapot, leállás oka, adatfolyam befejezésének állapota és hiba hozzárendelése.
• Beviteli, kimeneti, gyorsítótár-létrehozási és gyorsítótár-olvasási token kategóriák.
• Árképzési katalógus verziója és ideiglenes vagy véglegesített költségállapota.

Ezek a dimenziók lehetővé teszik az unified AI API billing magyarázatát, hogy az egyébként hasonló kérések miért okoztak eltérő költségeket. Kerülje el az egyetlen kombinált tokenszámból történő számlázást, ha a szolgáltató különböző díjszabású kategóriákat tesz közzé.

Tesztelés a verzió vagy a béta engedélyezése előtt

Hozzon létre szerződési feltételeket közönséges szöveghez, streaming szöveghez, eszközhívásokhoz, strukturált kimenetekhez, elutasításokhoz, token csonkoláshoz, kontextusablak kimerüléséhez, szüneteltetett fordulatokhoz, gyorsítótárazáshoz, hibásan formázott kérésekhez, sebességkorlátokhoz és adatfolyam közbeni hibákhoz.

Hasonlítsa össze az egyes rögzítéseknél több, mint HTTP állapotot. Rögzítse a tartalomblokk típusát és sorrendjét, a leállás okát, az eszközazonosítókat és argumentumokat, az eseménysorozatot, a használati mezők jelenlétét, a gyorsítótár kategóriáit és a hiba alakját. Tárolja a jóváhagyott szerkezeti elvárásokat a pontos prózai kimenet helyett.

Csak akkor használjon árnyékkérelmeket, ha a párhuzamos végrehajtás biztonságos. Előfordulhat, hogy az eszközökkel, külső mellékhatásokkal, érzékeny adatokkal vagy anyagköltséggel kapcsolatos kérések nem megfelelőek. Ilyen munkaterhelések esetén játssza le újra a fertőtlenített készülékeket ellenőrzött környezetben.

Előrejelzés: Az új verziók és bétafunkciók továbbra is válaszváltozatokat és eseményeket adnak hozzá. A képességrekordokra és az additív elemzésre tervezett átjáró általában kevesebb vészhelyzeti munkával veszi fel ezeket a változásokat, mint egy rögzített enumokra és globális alapértelmezett értékekre épülő átjáró.

A képességek biztonságos bevezetése és megszüntetése

Egy képesség népszerűsítése teszteléssel, belső, feliratkozási, kanári, elérhető, elavult és blokkolt állapotokkal. A kanyarozás során hasonlítsa össze az állapoteloszlásokat, a leállási okokat, a tartalomblokkoló sorozatokat, az eszköz viselkedését, a használati mezőket, a késleltetést és a gyorsítótár kimeneteit. Határozza meg a visszaállítási küszöbértékeket a forgalom megkezdése előtt.

A nyugdíjba vonulás szakaszosan történjen:

1. Az új bérlői átvétel letiltása, amíg a meglévő hozzárendelések folytatódnak.
2. Az érintett bérlők, kulcsok, modellek és a legutóbbi kérésminták azonosítása.
3. Adjon meg kompatibilitási jelentést vagy tesztvégpontot a cseréhez.
4. Figyelmeztessen az elfogadott kérésekre, és tegyen közzé egy határozott határértéket.
5. Kifejezett kivételek megkövetelése a tulajdonosokkal és a lejárati dátumokkal.
6. Tiltja le a funkciót, és őrizze meg a rendszerleíró adatbázis rekordját a korábbi audit és számlázás értelmezéséhez.

A rögzítés növeli a reprodukálhatóságot, de kibővíti a tesztmátrixot. Az átjáróra kiterjedő változat csökkenti a működési változatokat, de a nem kapcsolódó bérlőket egyetlen áttelepítési ütemezéshez kapcsolja. A széles körű béta áthaladás felgyorsítja a funkciók elérését, de gyengíti a költségeket, a tartózkodási helyet és a támogatási garanciákat. Több bérlős szolgáltatás esetén az explicit bérlőnkénti szabályzat általában a védhető középút.

Megvalósítási ellenőrzőlista

• Verziószabályzat megkövetelése minden bérlőhöz vagy API kulcshoz.
• A tesztelt verzió és a béta képességek nyilvántartása.
• A hibás, ismeretlen vagy nem engedélyezett képességek visszautasítása a feladás előtt.
• Csak a teljes protokollkérelem megoldása után válasszon útvonalakat.
• Megőrzi a natív tartalomblokkolókat, a leállási okokat, a használati mezőket és a streameket.
• Továbbítsa az additív eseményeket biztonságosan, és őrizze meg az eseménynevüket.
• Rögzítse a kért és hatékony protokollértékeket a használati és ellenőrzési eseményeken.
• Az alapértelmezett beállítások módosítása előtt futtasson szerződéses feltételeket és irányított kanáriakat.
• Szüntesse meg a régi képességeket mért átvételi vezérléssel, nem pedig csendes átírással.

A legfontosabb tervezési döntés egyszerű: a verzió és a béta fejlécek a szabályzat bemenetei. Miután az átjáró elismeri, irányítja, teszteli és méri őket képességként, a natív API kompatibilitás szabályozhatóvá válik anélkül, hogy a kísérleti viselkedés szokásos HTTP metaadatnak tűnne.

Kapcsolódó olvasmány

• a végső adatfolyamok, használat és elszámolások elszámolása válaszok