Управлявайте Anthropic API версии и бета заглавки в шлюз с множество клиенти

Anthropic-съвместим API шлюз не трябва да третира anthropic-version и anthropic-beta като обикновени заглавки за преминаване. Те избират поведение на протокола и експериментални възможности, които могат да променят правилата за валидиране, блокове за отговор, поточни събития, наличност, ценообразуване и отчитане на кеша.

Практическият проблем е запазването на родното Claude поведение, без да се позволява на заглавките на заявката на един клиент да заобикалят политиката на платформата. Решението е да превърнете приемането на протокол в първокласно решение за шлюз: удостоверете повикващия, разрешите неговата политика за версията, потвърдете заявените бета функции, изберете съвместим маршрут и запишете точно какво е изпратено нагоре.

Определяне на границата на правилата

Факт: Директните Claude API заявки изискват anthropic-version заглавка, въпреки че официалните SDK обикновено го предоставят. 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"
  }
}

Връщане на отговор 4xx за грешки при допускане и резервиране на отговори 5xx за грешки на шлюза или нагоре по веригата. Поддържайте схемата за грешка стабилна, дори ако Anthropic промени своя собствен формат на грешка.

Създаване на регистър на версиите и възможностите

Версионен низ с форма на дата се проверява лесно синтактично, но е невъзможно да се управлява само от синтаксиса. Шлюзът се нуждае от регистър, съдържащ версиите и бета функциите, които действително е тествал.

Записи на версиите

Всеки запис на версия трябва да включва:

• Идентификатор на канонична версия и състояние на жизнения цикъл: тестване, налично, по подразбиране, отхвърлено или блокирано.
• Поддържани полета за заявки, блокове на съдържание, причини за спиране, полета за използване и известни поточни събития.
• Съвместими модели, платформи нагоре по веригата, региони и пулове от идентификационни данни.
• Резултати от договора и датата на последния успешен тест.
• Съвместимост с ценообразуване и каталог и всички известни последици за отчитане на кеша.
• Ограничения за приемане, дати на оттегляне и указания за замяна.

Бета записи

Бета функциите се нуждаят от отделни записи, тъй като тяхната наличност и оперативен риск могат да се различават от базовата API версия. Запишете името на каноничната бета версия, съвместимите версии и модели, разрешените региони, задължителните полета за заявка, възможните блокове за отговор, поточните събития, ценообразуването, класа на ограничение на скоростта и състоянието на разпространение.

Моделирайте това като данни, а не като условия на приложение. След това оценителят на политика може да отговори на конкретен въпрос: „Може ли ключ K да използва версия V с бета набор B по маршрут R?“ Същият каталог може да поддържа мултимоделен 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 има документирани ограничения на полета и функции. Общата вътрешна обвивка може да помогне при маршрутизирането, но не трябва да отхвърля реда на блокиране на съдържанието, контролите на кеша, мисловните подписи, състоянието на инструмента или специфичните за доставчика причини за спиране.

Направете счетоводна версия осведомена

Факт: Използването на Prompt-cache разделя обикновените входни маркери, входни маркери за създаване на кеш и входни маркери за четене на кеш. Общото потребление на суровини трябва да отчита всички приложими категории.

Версия или бета промяна може да промени допустимостта на кеша, представянето на съдържанието или върнатите полета за използване. Следователно всяко събитие на използване трябва да включва:

• Заявена и ефективна API версия.
• Заявени и допуснати бета комплекти.
• Наемател, API ключ, политика, маршрут, модел, регион и ID на заявка нагоре.
• Състояние, причина за спиране, състояние на завършване на потока и приписване на грешка.
• Категории маркери за въвеждане, извеждане, създаване на кеш и четене на кеша.
• Версия на ценообразуващ каталог и временно или окончателно състояние на разходите.

Тези измерения позволяват на унифицираното AI API таксуване да обясни защо иначе сходните заявки водят до различни разходи. Избягвайте таксуването от един комбиниран брой токени, когато доставчикът излага категории с различни тарифи.

Тествайте, преди да активирате версия или бета

Създаване на фиксирани договори за обикновен текст, поточен текст, извиквания на инструменти, структуриран изход, откази, съкращаване на токени, изчерпване на контекстния прозорец, поставени на пауза редове, бързо кеширане, неправилно формирани заявки, ограничения на скоростта и грешки в средата на потока.

За всеки мач сравнете повече от HTTP състояние. Уловете типа и реда на блока на съдържанието, причината за спиране, идентификаторите и аргументите на инструмента, последователността на събитията, присъствието на полето за използване, категориите на кеша и формата на грешката. Съхранявайте одобрени структурни очаквания, а не точен прозаичен резултат.

Използвайте скритите заявки само когато дублираното изпълнение е безопасно. Заявки с инструменти, външни странични ефекти, чувствителни данни или разходи за материали може да са неподходящи. За тези натоварвания възпроизвеждайте дезинфекцирани тела в контролирана среда.

Прогноза: Нови версии и бета функции ще продължат да добавят варианти на отговор и събития. Шлюз, проектиран около записи на възможности и адитивно анализиране, обикновено ще поеме тези промени с по-малко спешна работа от този, изграден около фиксирани enum и глобални настройки по подразбиране.

Безопасно разгръщане и оттегляне на способности

Насърчаване на възможност чрез състояния на тестване, вътрешно, включване, канари, налично, отхвърлено и блокирано. По време на canarying сравнете разпределенията на състоянието, причините за спиране, последователностите на блокове на съдържание, поведението на инструмента, полетата за използване, латентността и резултатите от кеша. Дефинирайте праговете за връщане преди да започне трафикът.

Пенсионирането трябва да става на етапи:

1. Блокирайте приемането на нов наемател, докато съществуващите назначения продължават.
2. Идентифицирайте засегнатите наематели, ключове, модели и модели на скорошни заявки.
3. Предоставете отчет за съвместимост или тествайте крайна точка за замяната.
4. Предупреждавайте за допуснати заявки и публикувайте твърдо прекъсване.
5. Изискване на изрични изключения със собственици и дати на изтичане.
6. Блокирайте възможността и запазете записа в регистъра за исторически одит и тълкуване на таксуването.

Фиксирането увеличава възпроизводимостта, но разширява тестовата матрица. Версия за целия шлюз намалява оперативните варианти, но обединява несвързани наематели в един график за миграция. Широкото бета преминаване ускорява достъпа до функциите, но отслабва гаранциите за цена, пребиваване и поддръжка. За услуга с множество наематели изричната политика за всеки наемател обикновено е защитимата средна позиция.

Контролен списък за внедряване

• Изискване на политика за версия за всеки клиент или API ключ.
• Поддържайте записи за тествани версии и бета възможности.
• Отхвърлете деформирани, неизвестни или неоторизирани възможности преди изпращане.
• Избирайте маршрути само след разрешаване на пълната заявка за протокол.
• Запазване на блокове с естествено съдържание, причини за спиране, полета за използване и потоци.
• Препращайте по безопасен начин допълнителни събития от потока и запазвайте имената им.
• Записване на заявени и ефективни стойности на протокола за използване и одитни събития.
• Пускане на договорени програми и контролирани канарчета, преди да промените настройките по подразбиране.
• Изтеглете старите възможности чрез премерени контроли за приемане, а не безшумно презаписване.

Ключовото дизайнерско решение е просто: версията и бета заглавките са въведени данни за правилата. След като шлюзът ги приеме, маршрутизира, тества и ги измерва като възможности, естествената API съвместимост става управляема, без да се преструва, че експерименталното поведение е обикновени HTTP метаданни.

Свързано четене

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