Управљајте верзијама Anthropic API и бета заглављима у мрежном пролазу за више корисника

Гејтвеј компатибилан са Anthropic API не би требало да третира anthropic-version и anthropic-beta као обична пролазна заглавља. Они бирају понашање протокола и експерименталне могућности које могу да промене правила валидације, блокове одговора, догађаје стримовања, доступност, цене и обрачун кеша.

Практични проблем је очување природног понашања Claude без допуштања да заглавља захтева једног станара заобиђу политику платформе. Решење је да се пријем протокола учини првокласном одлуком гатеваи-а: аутентификујте позиваоца, решите његову политику верзије, потврдите тражене бета функције, изаберете компатибилну руту и забележите тачно оно што је послато узводно.

Дефинишите границу смерница

Чињеница: Директни захтеви Claude API захтевају anthropic-version заглавље, иако га званични СДК-ови обично обезбеђују. Anthropic бета функције се захтевају преко anthropic-beta или бета параметра специфичног за SDK.

Препорука: Обе вредности тумачите као тражене могућности, а не као поуздана упутства за рутирање. Клијент може затражити верзију или бета верзију, али мрежни пролаз одлучује да ли је та комбинација подржана за акредитиве закупца, кључа API, модела, региона и упстреам.

Немојте тихо уклањати неодобрену бета верзију. То може претворити експлицитан захтев у успешан позив са различитом семантиком. Одбијте га пре слања са стабилном грешком мрежног пролаза која идентификује неподржану могућност без откривања упстреам акредитива или детаља интерне руте.

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

Вратите 4кк одговор за грешке у пријему и резервишите 5кк одговоре за грешке мрежног пролаза или упстреам. Одржавајте шему грешке стабилном чак и ако Anthropic промени сопствени формат грешке.

Направите регистар верзија и могућности

Стринг верзије у облику датума је лако синтактички потврдити, али је немогуће управљати само из синтаксе. Мрежном пролазу је потребан регистар који садржи верзије и бета функције које је стварно тестирао.

Записи о верзији

Сваки запис верзије треба да садржи:

• Канонски идентификатор верзије и стање животног циклуса: тестирање, доступно, подразумевано, застарело или блокирано.
• Подржана поља захтева, блокови садржаја, разлози заустављања, поља коришћења и познати догађаји стримовања.
• Компатибилни модели, узводне платформе, региони и скупови акредитива.
• Резултати уговора и датум последњег успешног теста.
• Компатибилност каталога цена и све познате импликације за обрачун кеша.
• Ограничења усвајања, датуми застарелости и упутства за замену.

Бета записи

Бета функције захтевају посебне записе јер се њихова доступност и оперативни ризик могу разликовати од основне верзије API. Забележите канонски назив бета верзије, компатибилне верзије и моделе, дозвољене регионе, обавезна поља захтева, могуће блокове одговора, догађаје стримовања, третман цена, класу ограничења брзине и стање увођења.

Моделирајте ово као податке, а не као услове апликације. Евалуатор политике онда може да одговори на конкретно питање: „Да ли кључ К користи верзију В са бета скупом Б на рути Р?“ Исти каталог може да подржи капију више модела API за тимове без присиљавања сваког адаптера да примени сопствена правила закупца.

Дајте сваком закупцу експлицитну политику верзије

Подржава три режима смерница:

1. Закачено: Закупац или кључ морају да користе једну тачну верзију. Одбијте вредности које недостају или су различите.
2. Актуелни мрежни пролаз: Заглавље које недостаје решава се на тестирану подразумевану вредност мрежног пролаза. Експлицитна вредност клијента је и даље потврђена.
3. Одобрени опсег: Клијент може да бира са коначне дозвољене листе тестираних верзија.

Избегавајте да тумачите „опсег“ као сваки датум између две крајње тачке. Anthropic верзије су идентификатори, а не непрекидна секвенца семантичке верзије. Чувајте експлицитни скуп дозвољених вредности.

Решите ефективну верзију пре него што изаберете узводну руту:

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)

Држите тражене и ефективне вредности одвојене. Могу се разликовати када смерница даје подразумевану вредност, али запис ревизије мора да учини ту замену видљивом.

Распореди структурно бета заглавља

Не овлашћујте бета функције са подударањем подстрингова или једнакошћу необрађених низова. Рашчланите заглавље у складу са синтакси коју прихвата узводни API, одбаците погрешно обликоване или дуплиране уносе према потреби и упоредите канонске идентификаторе обележја.

Канонски поредак је користан за кључеве кеша смерница и димензије телеметрије:

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

Сачувајте довољно метаподатака захтева за отклањање грешака, али не задржавајте необрађена заглавља на неодређено време када су нормализовани идентификатори довољни. Евиденције заглавља могу да садрже непотребне метаподатке клијента, а њихово складиштење повећава обим контроле задржавања и приступа.

Бета овлашћење би требало да буде у опсегу закупца и по могућности на кључу. Развојни кључ може добити експерименталну могућност без аутоматског додељивања производним радним оптерећењима. Промене на листама дозвољених треба да произведу догађаје ревизије на контролној равни са актером, разлогом, претходним стањем, новим стањем и ефективним временом.

Одвојите пријем од рутирања

Захтев није рутабилан само зато што постоји назив његовог модела. Подобност руте је пресек могућности протокола и инфраструктуре:

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

Ако ниједна рута не задовољава цео скуп, не успе пре слања захтева. Немојте испуштати бета функције да би рута била квалификована. Немојте аутоматски заменити другу верзију осим ако смернице закупца изричито не дефинишу то понашање.

Ово раздвајање је важно за мрежне пролазе који обједињују акредитиве, подржавају кључеве које је доставио корисник или раде у различитим регионима. Две руте до истог модела могу имати различите приступе функцијама, ограничења боравка или ограничења стопе.

Очувајте семантику изворног одговора

Чињеница: Anthropic Одговори на поруке могу да се заврше разлозима укључујући коришћење алата, ограничења токена, ограничења контекстног прозора, паузирана скретања и одбијања. Стримовани одговори користе именоване догађаје које шаље сервер, а упутства за компатибилност Anthropic захтевају од клијената да толеришу нове типове догађаја.

Препорука: Немојте сажимати сва успешна терминална стања у „завршено“. Сачувајте разлог заустављања узводно у изворном одговору и у телеметрији мрежног пролаза. Апликације ће можда морати да изврше алатку, наставе са паузираним скретањем, смање контекст или изнесу одбијање.

Прокси за стрим треба да препозна догађаје потребне за рачуноводство и управљање животним циклусом, а да остане компатибилан за даље:

• Проследите непознате типове догађаја када смернице закупца дозвољавају изворни пролаз.
• Задржите назив необрађеног догађаја и позицију секвенце у ограниченим дијагностичким метаподацима.
• Не користите исцрпан енум који затвара стрим на непознатом адитивном догађају.
• Разликујте догађај грешке узводно од прекида везе у транспорту и отказивања клијента.
• Заврши коришћење само из овлашћених поља; означи непотпуне стримове као привремене када коначно коришћење није доступно.

Ако мрежни пролаз такође излаже крајњу тачку у облику OpenAI, држите тај адаптер одвојено од матичне путање порука. Слој компатибилности Anthropic OpenAI има документована ограничења поља и функција. Уобичајени интерни омот може помоћи при рутирању, али не сме да одбаци редослед блокирања садржаја, контроле кеша, потписе размишљања, стање алата или разлоге заустављања специфичне за добављача.

Учините рачуноводствену верзију свесном

Чињеница: Употреба брзе кеш меморије одваја обичне улазне токене, улазне токене за креирање кеша и улазне токене за читање кеша. Укупна потрошња инпута мора да обухвата све применљиве категорије.

Промена верзије или бета верзије може да промени услове за кеширање, приказ садржаја или поља за враћено коришћење. Према томе, сваки догађај коришћења треба да садржи:

• Затражена и ефективна API верзија.
• Затражени и прихваћени бета сетови.
• Закупац, API кључ, смерница, рута, модел, регион и ИД захтева узводно.
• Статус, разлог заустављања, стање завршетка стрима и приписивање грешке.
• Категорије токена за унос, излаз, креирање кеша и читање кеша.
• Верзија каталога цена и стање привремених или финалних трошкова.

Ове димензије омогућавају обједињени АИ API обрачун да објасни зашто су иначе слични захтеви произвели различите трошкове. Избегавајте наплату из једног комбинованог броја токена када добављач излаже категорије са различитим ценама.

Тестирајте пре него што омогућите верзију или бета верзију

Креирајте распореде уговора за обичан текст, стримовање текста, позиве алатки, структурирани излаз, одбијања, скраћивање токена, исцрпљивање контекстног прозора, паузирана скретања, брзо кеширање, погрешно обликоване захтеве, ограничења брзине и грешке у току тока.

За сваки уређај, упоредите више од HTTP статуса. Снимите тип и ред блока садржаја, разлог заустављања, идентификаторе алата и аргументе, секвенцу догађаја, присуство поља употребе, категорије кеша и облик грешке. Чувајте одобрена структурна очекивања, а не тачан прозни резултат.

Користите захтеве за сенку само када је дупло извршавање безбедно. Захтеви са алатима, спољним нежељеним ефектима, осетљивим подацима или трошковима материјала могу бити неприкладни. За та радна оптерећења, поново репродукујте дезинфициране уређаје у контролисаном окружењу.

Предвиђање: Нове верзије и бета функције ће наставити да додају варијанте одговора и догађаје. Гатеваи дизајниран око записа о могућностима и адитивног рашчлањивања обично ће апсорбовати те промене са мање хитних послова него онај који је изграђен око фиксних енума и глобалних подразумеваних вредности.

Безбедно увести и повући могућности

Промовишите могућност кроз тестирање, интерно, укључено, канарско, доступно, застарело и блокирано стање. Током цанариинга, упоредите дистрибуције статуса, разлоге за заустављање, секвенце блокова садржаја, понашање алата, поља коришћења, кашњење и исходе кеша. Дефинишите прагове враћања пре него што саобраћај почне.

Пензионисање би требало да се одвија у фазама:

1. Блокирајте усвајање новог станара док се постојећи задаци настављају.
2. Идентификујте погођене станаре, кључеве, моделе и недавне обрасце захтева.
3. Наведите извештај о компатибилности или крајњу тачку тестирања за замену.
4. Упозорите на прихваћене захтеве и објавите чврсту граничну вредност.
5. Захтевају експлицитне изузетке са власницима и датумима истека.
6. Блокирајте могућност и задржите евиденцију регистра за историјску ревизију и тумачење обрачуна.

Кадовање повећава поновљивост, али проширује тестну матрицу. Верзија за читав пролаз смањује оперативне варијанте, али спаја неповезане станаре у један распоред миграције. Широки бета пролаз убрзава приступ функцијама, али слаби гаранције трошкова, боравка и подршке. За услугу са више закупаца, експлицитна политика по закупцима је обично средина која се може одбранити.

Контролна листа за имплементацију

• Захтевајте смернице за верзију за сваког корисника или кључ API.
• Одржавајте записе о тестираној верзији и бета могућностима.
• Одбијте погрешне, непознате или неовлашћене могућности пре слања.
• Изаберите руте тек након што решите комплетан захтев за протокол.
• Очувајте изворне блокове садржаја, разлоге за заустављање, поља коришћења и стримове.
• Безбедно проследите догађаје адитивног стрима и задржите њихове називе догађаја.
• Снимите тражене и ефективне вредности протокола о коришћењу и догађајима ревизије.
• Покрени уговоре и контролисане канаринце пре него што промениш подразумеване вредности.
• Откажите старе могућности кроз мерене контроле усвајања, а не тихо преписивање.

Кључна одлука о дизајну је једноставна: верзија и бета заглавља су улази у политику. Једном када мрежни пролаз прихвати, усмерава, тестира и мери их као могућности, компатибилност урођене API постаје подесива без претварања да је експериментално понашање обични HTTP метаподаци.

Повезано читање

• обрачунавање канте за коначну употребу, стриминг и део одговори