Zarządzaj wersjami Anthropic API i nagłówkami Beta w bramie obsługującej wielu dzierżawców

Brama API zgodna z Anthropic nie powinna traktować anthropic-version i anthropic-beta jako zwykłych nagłówków tranzytowych. Wybierają zachowanie protokołu i możliwości eksperymentalne, które mogą zmieniać reguły sprawdzania poprawności, bloki odpowiedzi, zdarzenia przesyłania strumieniowego, dostępność, ceny i rozliczanie pamięci podręcznej.

Praktyczny problem polega na zachowaniu natywnego zachowania Claude bez zezwolenia nagłówkom żądań jednego dzierżawcy na ominięcie zasad platformy. Rozwiązaniem jest przyjęcie protokołu jako pierwszorzędnej decyzji dotyczącej bramy: uwierzytelnij osobę wywołującą, ustal zasady dotyczące jej wersji, zatwierdź żądane funkcje wersji beta, wybierz zgodną trasę i zapisz dokładnie to, co zostało przesłane wcześniej.

Określ granicę zasad

Fakt: Żądania bezpośrednie Claude API wymagają nagłówka anthropic-version, chociaż oficjalne pakiety SDK zwykle go dostarczają. Anthropic funkcji beta żąda się za pomocą anthropic-beta lub parametru beta specyficznego dla SDK.

Zalecenie: Zinterpretuj obie wartości jako żądane możliwości, a nie zaufane instrukcje routingu. Klient może poprosić o wersję lub wersję beta, ale brama decyduje, czy ta kombinacja jest obsługiwana dla dzierżawy, API klucza, modelu, regionu i poświadczeń nadrzędnych.

Nie usuwaj po cichu niezatwierdzonej wersji beta. Może to zamienić wyraźne żądanie w udane wywołanie z inną semantyką. Odrzuć go przed wysłaniem z powodu błędu stabilnej bramy, który identyfikuje nieobsługiwaną funkcję bez ujawniania poświadczeń nadrzędnych lub szczegółów trasy wewnętrznej.

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

Zwróć odpowiedź 4xx w przypadku niepowodzeń przyjęcia i zarezerwuj odpowiedzi 5xx w przypadku awarii bramy lub łącza nadrzędnego. Zachowaj stabilność schematu błędów, nawet jeśli Anthropic zmieni swój własny format błędu.

Utwórz rejestr wersji i możliwości

Ciąg wersji w kształcie daty można łatwo zweryfikować pod względem składniowym, ale nie da się nim zarządzać na podstawie samej składni. Brama potrzebuje rejestru zawierającego wersje i funkcje beta, które faktycznie przetestowała.

Rekordy wersji

Każdy rekord wersji powinien zawierać:

• Identyfikator wersji kanonicznej i stan cyklu życia: testowanie, dostępne, domyślne, przestarzałe lub zablokowane.
• Obsługiwane pola żądań, bloki treści, przyczyny zatrzymania, pola użycia i znane zdarzenia przesyłania strumieniowego.
• Zgodne modele, platformy nadrzędne, regiony i pule danych uwierzytelniających.
• Wyniki kontraktu i data ostatniego pomyślnego testu.
• Zgodność z katalogiem cenowym i wszelkie znane implikacje dotyczące księgowania pamięci podręcznej.
• Ograniczenia wdrożenia, daty wycofania i wskazówki dotyczące wymiany.

Rekordy wersji beta

Funkcje Beta wymagają osobnych zapisów, ponieważ ich dostępność i ryzyko operacyjne mogą różnić się od wersji podstawowej API. Zapisz kanoniczną nazwę wersji beta, kompatybilne wersje i modele, dozwolone regiony, wymagane pola żądań, możliwe bloki odpowiedzi, zdarzenia dotyczące transmisji strumieniowej, zasady ustalania cen, klasę limitu stawek i stan wdrożenia.

Modeluj to jako dane, a nie warunki aplikacji. Osoba oceniająca politykę może następnie odpowiedzieć na konkretne pytanie: „Czy klucz K może używać wersji V z zestawem beta B na trasie R?” Ten sam katalog może obsługiwać wielomodelową API bramę dla zespołów bez zmuszania każdego adaptera do implementowania własnych reguł dzierżawy.

Nadaj każdemu najemcy wyraźną politykę dotyczącą wersji

Obsługa trzech trybów zasad:

1. Przypięte: Dzierżawca lub klucz musi używać jednej dokładnej wersji. Odrzuć brakujące lub inne wartości.
2. Bieżąca bramka: Brakujący nagłówek jest rozpoznawany jako testowana wartość domyślna bramy. Wyraźna wartość klienta jest nadal sprawdzana.
3. Zatwierdzony zakres: Klient może wybrać wersję z ograniczonej listy dozwolonych testowanych wersji.

Unikaj interpretowania „zakresu” jako każdej daty pomiędzy dwoma punktami końcowymi. Anthropic wersji to identyfikatory, a nie ciągła sekwencja wersji semantycznych. Przechowuj jawny zestaw dopuszczonych wartości.

Rozwiąż obowiązującą wersję przed wybraniem trasy nadrzędnej:

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)

Trzymaj wartości żądane i efektywne oddzielnie. Mogą się różnić, jeśli zasada przewiduje ustawienie domyślne, ale zapis audytu musi uwidocznić to zastąpienie.

Przeanalizuj strukturalnie nagłówki wersji beta

Nie autoryzuj funkcji beta z dopasowywaniem podciągów lub równością ciągów surowych. Przeanalizuj nagłówek zgodnie ze składnią zaakceptowaną przez źródło API, odrzuć odpowiednio zniekształcone lub zduplikowane wpisy i porównaj kanoniczne identyfikatory cech.

Porządkowanie kanoniczne jest przydatne w przypadku kluczy pamięci podręcznej zasad i wymiarów telemetrycznych:

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

Zachowaj wystarczającą ilość metadanych żądania do debugowania, ale nie przechowuj nieprzetworzonych nagłówków przez czas nieokreślony, jeśli wystarczą znormalizowane identyfikatory. Dzienniki nagłówków mogą zawierać niepotrzebne metadane klienta, a ich przechowywanie zwiększa zakres przechowywania i kontroli dostępu.

Autoryzacja wersji beta powinna mieć zasięg dzierżawcy, a najlepiej klucza. Klucz programistyczny może otrzymać możliwość eksperymentalną bez automatycznego przyznawania jej obciążeniom produkcyjnym. Zmiany na listach dozwolonych powinny generować zdarzenia kontroli płaszczyzny kontrolnej zawierające aktora, przyczynę, poprzedni stan, nowy stan i czas obowiązywania.

Oddzielne wejście od routingu

Żądania nie można routować tylko dlatego, że istnieje nazwa jego modelu. Kwalifikowalność trasy to skrzyżowanie możliwości protokołu i infrastruktury:

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

Jeśli żadna trasa nie spełnia pełnego zestawu, wysłanie żądania zakończy się niepowodzeniem. Nie rezygnuj z funkcji beta, aby trasa kwalifikowała się. Nie zastępuj automatycznie innej wersji, chyba że zasady dzierżawy wyraźnie określają takie zachowanie.

To oddzielenie ma znaczenie w przypadku bram, które łączą dane uwierzytelniające, obsługują klucze dostarczone przez klienta lub działają w różnych regionach. Dwie trasy do tego samego modelu mogą mieć inny dostęp do funkcji, ograniczenia dotyczące miejsca zamieszkania lub limity stawek.

Zachowaj natywną semantykę odpowiedzi

Fakt: Anthropic Odpowiedzi na wiadomości mogą kończyć się z przyczyn takich jak użycie narzędzia, limity tokenów, limity okna kontekstowego, wstrzymane zwroty i odmowy. Odpowiedzi przesyłane strumieniowo korzystają z nazwanych zdarzeń wysyłanych przez serwer, a wskazówki dotyczące zgodności Anthropic wymagają, aby klienci tolerowali nowe typy zdarzeń.

Zalecenie: Nie zwijaj wszystkich pomyślnie zakończonych stanów końcowych do „ukończone”. Zachowaj przyczynę zatrzymania nadrzędnego w odpowiedzi natywnej i telemetrii bramy. Aplikacje mogą wymagać uruchomienia narzędzia, kontynuowania wstrzymanego działania, ograniczenia kontekstu lub ujawnienia odmowy.

Proxy strumieniowe powinno rozpoznawać zdarzenia wymagane do rozliczania i zarządzania cyklem życia, zachowując jednocześnie kompatybilność z przyszłymi wersjami:

• Przekazuj nieznane typy zdarzeń, gdy zasady dzierżawcy zezwalają na natywne przekazywanie.
• Zachowaj surową nazwę zdarzenia i pozycję w sekwencji w ograniczonych metadanych diagnostycznych.
• Nie używaj wyczerpującego wyliczenia, które zamyka strumień w przypadku nieznanego zdarzenia dodatku.
• Odróżnij zdarzenie błędu poprzedzającego od rozłączenia transportu i anulowania klienta.
• Finalizuj użycie tylko z autorytatywnych pól; oznaczaj niekompletne strumienie jako tymczasowe, gdy ostateczne wykorzystanie jest niedostępne.

Jeśli brama udostępnia również punkt końcowy w kształcie OpenAI, trzymaj ten adapter oddzielnie od natywnej ścieżki Messages. Warstwa zgodności Anthropic OpenAI ma udokumentowane ograniczenia dotyczące pól i funkcji. Wspólna koperta wewnętrzna może pomóc w routingu, ale nie może odrzucać kolejności bloków treści, kontroli pamięci podręcznej, podpisów myślenia, stanu narzędzia ani powodów zatrzymania specyficznych dla dostawcy.

Udostępnij wersję księgową

Fakt: użycie pamięci podręcznej podpowiedzi oddziela zwykłe tokeny wejściowe, tokeny wejściowe tworzenia pamięci podręcznej i tokeny wejściowe odczytu pamięci podręcznej. Całkowite zużycie środków wejściowych musi uwzględniać wszystkie odpowiednie kategorie.

Zmiana wersji lub wersji beta może zmienić uprawnienia pamięci podręcznej, reprezentację treści lub zwracane pola użycia. Dlatego każde zdarzenie użycia powinno obejmować:

• Wymagana i obowiązująca wersja API.
• Wysłane i przyjęte zestawy beta.
• Dzierżawa, API klucz, zasada, trasa, model, region i identyfikator żądania nadrzędnego.
• Stan, przyczyna zatrzymania, stan zakończenia strumienia i przypisanie błędu.
• Kategorie tokenów wejściowych, wyjściowych, tworzenia pamięci podręcznej i odczytu pamięci podręcznej.
• Wersja katalogu cenowego i tymczasowy lub ostateczny stan kosztów.

Te wymiary pozwalają ujednoliconej sztucznej inteligencji API rozliczeniowej wyjaśnić, dlaczego w przeciwnym razie podobne żądania generowały różne koszty. Unikaj naliczania opłat za jedną łączną liczbę tokenów, gdy dostawca udostępnia kategorie z różnymi stawkami.

Przetestuj przed włączeniem wersji lub wersji beta

Twórz elementy kontraktu dla zwykłego tekstu, tekstu przesyłanego strumieniowo, wywołań narzędzi, danych wyjściowych ustrukturyzowanych, odmów, obcinania tokenów, wyczerpania okna kontekstowego, wstrzymanych obrotów, buforowania podpowiedzi, zniekształconych żądań, limitów szybkości i błędów w trakcie strumienia.

Dla każdego urządzenia porównaj status więcej niż HTTP. Przechwytuj typ i kolejność bloków treści, przyczynę zatrzymania, identyfikatory i argumenty narzędzi, sekwencję zdarzeń, obecność pola użycia, kategorie pamięci podręcznej i kształt błędu. Przechowuj zatwierdzone oczekiwania strukturalne, a nie dokładne wyniki prozy.

Używaj żądań w tle tylko wtedy, gdy wykonanie duplikatu jest bezpieczne. Żądania dotyczące narzędzi, zewnętrznych skutków ubocznych, wrażliwych danych lub kosztów materiałów mogą być nieodpowiednie. W przypadku takich zadań odtwarzaj oczyszczone spotkania w kontrolowanym środowisku.

Przewidywanie: Nowe wersje i funkcje beta będą nadal dodawać warianty odpowiedzi i zdarzenia. Brama zaprojektowana w oparciu o rekordy możliwości i analizę addytywną zazwyczaj wchłonie te zmiany przy mniejszej liczbie pracy awaryjnej niż brama zbudowana w oparciu o stałe wyliczenia i globalne wartości domyślne.

Bezpieczne wdrażanie i wycofywanie funkcji

Promuj możliwości poprzez stany: testowanie, stan wewnętrzny, możliwość wyrażenia zgody, kanaryjski, dostępny, przestarzały i zablokowany. Podczas kanaryzacji porównaj rozkłady statusów, przyczyny zatrzymania, sekwencje bloków treści, zachowanie narzędzi, pola użycia, opóźnienia i wyniki pamięci podręcznej. Zdefiniuj progi wycofywania przed rozpoczęciem ruchu.

Odejście na emeryturę powinno odbywać się etapami:

1. Blokuj przyjęcie nowych dzierżawców, dopóki istniejące przypisania będą kontynuowane.
2. Zidentyfikuj dzierżawców, klucze, modele i najnowsze wzorce żądań, których to dotyczy.
3. Dostarcz raport zgodności lub przetestuj punkt końcowy dla zamiennika.
4. Ostrzegaj o zaakceptowanych prośbach i publikuj ostateczne terminy.
5. Wymagaj wyraźnych wyjątków dotyczących właścicieli i dat wygaśnięcia.
6. Zablokuj tę możliwość i zachowaj zapis rejestru na potrzeby audytu historycznego i interpretacji rozliczeń.

Przypinanie zwiększa powtarzalność, ale rozszerza macierz testową. Wersja obejmująca całą bramę ogranicza warianty operacyjne, ale łączy niepowiązanych dzierżawców w jeden harmonogram migracji. Szerokie przejście w wersję beta przyspiesza dostęp do funkcji, ale osłabia koszty, trwałość i gwarancje wsparcia. W przypadku usługi obejmującej wielu dzierżawców jasne zasady dotyczące poszczególnych dzierżawców są zazwyczaj możliwym do obrony środkiem.

Lista kontrolna wdrożenia

• Wymagaj zasad wersji dla każdego dzierżawcy lub API klucza.
• Prowadź zapisy dotyczące testowanych wersji i wersji beta.
• Przed wysyłką odrzuć zniekształcone, nieznane lub nieautoryzowane możliwości.
• Wybierz trasy dopiero po rozpatrzeniu pełnego żądania protokołu.
• Zachowaj bloki treści natywnych, przyczyny zatrzymania, pola użytkowania i strumienie.
• Bezpiecznie przesyłaj dodatkowe zdarzenia strumieniowe i zachowaj ich nazwy.
• Rejestracja żądanych i skutecznych wartości protokołu w przypadku zdarzeń użytkowania i audytu.
• Przed zmianą ustawień domyślnych uruchamiaj mecze kontraktowe i kontrolowaj kanarki.
• Wycofaj stare możliwości poprzez wyważoną kontrolę wdrożenia, a nie ciche przepisywanie.

Kluczowa decyzja dotycząca projektu jest prosta: nagłówki wersji i wersji beta stanowią dane wejściowe polityki. Gdy brama dopuści, przekieruje, przetestuje i zmierzy je jako możliwości, natywna API zgodność stanie się możliwa do zarządzania bez udawania, że ​​eksperymentalne zachowanie to zwykłe HTTP metadane.

Powiązane lektury

• uwzględnianie końcowego użycia, anulowania i częściowych odpowiedzi na przesyłanie strumieniowe