Gestisci Anthropic API versioni e intestazioni beta in un gateway multi-tenant

Un gateway API compatibile con Anthropic non dovrebbe trattare anthropic-version e anthropic-beta come normali intestazioni pass-through. Selezionano il comportamento del protocollo e le funzionalità sperimentali che possono modificare le regole di convalida, i blocchi di risposta, gli eventi di streaming, la disponibilità, i prezzi e l'accounting della cache.

Il problema pratico è preservare il comportamento nativo Claude senza consentire alle intestazioni delle richieste di un tenant di ignorare i criteri della piattaforma. La soluzione è rendere l'ammissione al protocollo una decisione gateway di prima classe: autenticare il chiamante, risolvere la sua politica di versione, convalidare le funzionalità beta richieste, selezionare un percorso compatibile e registrare esattamente ciò che è stato inviato a monte.

Definire il limite delle norme

Fatto: Le richieste dirette Claude API richiedono un'intestazione anthropic-version, sebbene gli SDK ufficiali normalmente la forniscano. Anthropic funzionalità beta sono richieste tramite anthropic-beta o un parametro beta specifico per SDK.

Raccomandazione: interpreta entrambi i valori come funzionalità richieste, non come istruzioni di routing attendibili. Un cliente può richiedere una versione o una beta, ma il gateway decide se tale combinazione è supportata per tenant, chiave API, modello, regione e credenziali upstream.

Non rimuovere silenziosamente una versione beta non approvata. Ciò può trasformare una richiesta esplicita in una chiamata riuscita con semantica diversa. Rifiutalo prima dell'invio con un errore gateway stabile che identifica la funzionalità non supportata senza esporre le credenziali upstream o i dettagli del percorso interno.

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

Restituisce una risposta 4xx per gli errori di ammissione e riserva risposte 5xx per gli errori gateway o upstream. Mantieni stabile lo schema dell'errore anche se Anthropic cambia il proprio formato di errore.

Crea un registro delle versioni e delle funzionalità

Una stringa di versione a forma di data è facile da convalidare sintatticamente ma impossibile da gestire solo dalla sintassi. Il gateway necessita di un registro contenente le versioni e le funzionalità beta effettivamente testate.

Record di versione

Ogni record di versione deve includere:

• Identificatore di versione canonico e stato del ciclo di vita: test, disponibile, predefinito, obsoleto o bloccato.
• Campi di richiesta supportati, blocchi di contenuti, motivi di interruzione, campi di utilizzo ed eventi di streaming noti.
• Modelli compatibili, piattaforme upstream, regioni e pool di credenziali.
• Risultati delle partite contrattuali e data dell'ultimo test riuscito.
• Compatibilità con il catalogo dei prezzi ed eventuali implicazioni note sulla contabilità della cache.
• Limitazioni di adozione, date di ritiro e indicazioni sulla sostituzione.

Record beta

Le funzionalità beta necessitano di record separati perché la loro disponibilità e il rischio operativo possono differire dalla versione base API. Registra il nome canonico della beta, le versioni e i modelli compatibili, le regioni consentite, i campi di richiesta obbligatori, i possibili blocchi di risposta, gli eventi di streaming, il trattamento dei prezzi, la classe con limite di tariffa e lo stato di implementazione.

Modellalo come dati anziché come condizionali dell'applicazione. Un valutatore politico può quindi rispondere a una domanda concreta: “La chiave K può utilizzare la versione V con il set beta B sul percorso R?” Lo stesso catalogo può supportare un gateway multimodello API per i team senza forzare ogni adattatore a implementare le proprie regole tenant.

Fornisci a ogni tenant una policy di versione esplicita

Supporta tre modalità di criteri:

1. Bloccato: Il tenant o la chiave devono utilizzare una versione esatta. Rifiuta valori mancanti o diversi.
2. Gateway corrente: Un'intestazione mancante si risolve nell'impostazione predefinita testata del gateway. Un valore client esplicito è ancora convalidato.
3. Intervallo approvato: Il client può scegliere da un elenco limitato di versioni testate.

Evita di interpretare "intervallo" come qualsiasi data compresa tra due endpoint. Le versioni Anthropic sono identificatori, non una sequenza continua di versioni semantiche. Memorizza un insieme esplicito di valori ammessi.

Risolvi la versione effettiva prima di selezionare un percorso a monte:

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)

Mantieni separati i valori richiesti ed effettivi. Possono differire quando una policy fornisce un valore predefinito, ma un record di controllo deve rendere visibile tale sostituzione.

Analizza strutturalmente le intestazioni beta

Non autorizzare funzionalità beta con corrispondenza di sottostringhe o uguaglianza di stringhe non elaborate. Analizza l'intestazione in base alla sintassi accettata dall'upstream API, rifiuta le voci con formato errato o duplicato a seconda dei casi e confronta gli identificatori di funzionalità canonici.

L'ordinamento canonico è utile per le chiavi della policy cache e le dimensioni di telemetria:

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

Preserva un numero sufficiente di metadati della richiesta per il debug, ma non conservare le intestazioni non elaborate a tempo indeterminato quando gli identificatori normalizzati sono sufficienti. I log di intestazione possono contenere metadati client non necessari e la loro archiviazione aumenta l'ambito della conservazione e dei controlli di accesso.

L'autorizzazione beta deve avere un ambito tenant e preferibilmente una chiave. Una chiave di sviluppo può ricevere una funzionalità sperimentale senza concederla automaticamente ai carichi di lavoro di produzione. Le modifiche alle liste consentite dovrebbero produrre eventi di controllo del piano di controllo con attore, motivo, stato precedente, nuovo stato e tempo di validità.

Ingresso separato dal percorso

Una richiesta non è instradabile semplicemente perché esiste il nome del suo modello. L'idoneità del percorso è l'intersezione tra le capacità del protocollo e dell'infrastruttura:

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

Se nessun percorso soddisfa l'intero set, fallisci prima di inviare la richiesta. Non eliminare le funzionalità beta per rendere idoneo un percorso. Non sostituire automaticamente un'altra versione a meno che la politica del tenant non definisca esplicitamente tale comportamento.

Questa separazione è importante nei gateway che mettono in comune le credenziali, supportano le chiavi fornite dal cliente o operano in più regioni. Due percorsi verso lo stesso modello possono avere accesso a funzionalità, vincoli di residenza o limiti di velocità diversi.

Preserva la semantica della risposta nativa

Fatto: Anthropic Le risposte ai messaggi possono terminare con motivi quali utilizzo dello strumento, limiti dei token, limiti della finestra di contesto, turni in pausa e rifiuti. Le risposte in streaming utilizzano eventi inviati dal server denominati e le indicazioni sulla compatibilità di Anthropic richiedono che i client tollerino nuovi tipi di eventi.

Raccomandazione: non comprimere tutti gli stati terminali riusciti in "completato". Conserva il motivo dell'arresto upstream nella risposta nativa e nella telemetria del gateway. Potrebbe essere necessario che le applicazioni eseguano uno strumento, continuino una svolta in pausa, riducano il contesto o emergano un rifiuto.

Il proxy del flusso dovrebbe riconoscere gli eventi richiesti per la contabilità e la gestione del ciclo di vita pur rimanendo compatibile con le versioni future:

• Inoltra tipi di eventi sconosciuti quando la policy del tenant consente il pass-through nativo.
• Conserva il nome dell'evento non elaborato e la posizione della sequenza nei metadati diagnostici limitati.
• Non utilizzare un'enumerazione esaustiva che chiuda lo stream in caso di evento additivo sconosciuto.
• Distingui un evento di errore upstream da una disconnessione del trasporto e da un annullamento del client.
• Finalizza l'utilizzo solo dai campi autorevoli; contrassegna gli stream incompleti come provvisori quando l'utilizzo finale non è disponibile.

Se il gateway espone anche un endpoint a forma di OpenAI, mantieni l'adattatore separato dal percorso nativo dei messaggi. Il livello di compatibilità OpenAI di Anthropic presenta limitazioni documentate di campi e funzionalità. Una busta interna comune può aiutare con il routing, ma non deve ignorare l'ordine di blocco dei contenuti, i controlli della cache, le firme pensanti, lo stato dello strumento o i motivi di arresto specifici del provider.

Rendi la contabilità compatibile con la versione

Fatto: L'utilizzo della cache dei prompt separa i token di input ordinari, i token di input per la creazione della cache e i token di input per la lettura della cache. Il consumo totale di input deve tenere conto di tutte le categorie applicabili.

Una modifica alla versione o alla versione beta può alterare l'idoneità della cache, la rappresentazione dei contenuti o i campi di utilizzo restituiti. Pertanto, ogni evento di utilizzo dovrebbe includere:

• Versione API richiesta ed effettiva.
• Set beta richiesti e ammessi.
• Tenant, API chiave, policy, percorso, modello, regione e ID richiesta upstream.
• Stato, motivo dell'interruzione, stato di completamento dello streaming e attribuzione dell'errore.
• Categorie di token di input, output, creazione della cache e lettura della cache.
• Versione del catalogo prezzi e stato dei costi provvisori o definitivi.

Queste dimensioni consentono all'AI unificata API fatturazione di spiegare perché altrimenti richieste simili avrebbero prodotto costi diversi. Evita la fatturazione in base a un singolo conteggio di token combinato quando il fornitore espone categorie con tariffe diverse.

Testa prima di abilitare una versione o una beta

Crea strutture contrattuali per testo ordinario, testo in streaming, chiamate a strumenti, output strutturato, rifiuti, troncamento di token, esaurimento della finestra di contesto, turni in pausa, memorizzazione nella cache dei prompt, richieste non valide, limiti di velocità ed errori mid-stream.

Per ogni incontro, confronta più di HTTP stato. Cattura il tipo e l'ordine dei blocchi di contenuto, il motivo dell'interruzione, gli identificatori e gli argomenti dello strumento, la sequenza degli eventi, la presenza dei campi di utilizzo, le categorie della cache e la forma dell'errore. Conserva le aspettative strutturali approvate anziché l'esatto risultato in prosa.

Utilizza le richieste shadow solo quando l'esecuzione duplicata è sicura. Le richieste con strumenti, effetti collaterali esterni, dati sensibili o costi materiali potrebbero non essere idonee. Per questi carichi di lavoro, riproduci gli impianti disinfettati in un ambiente controllato.

Previsione: Le nuove versioni e funzionalità beta continueranno ad aggiungere varianti ed eventi di risposta. Un gateway progettato attorno ai record di capacità e all'analisi additiva in genere assorbirà tali modifiche con meno interventi di emergenza rispetto a uno costruito attorno a enumerazioni fisse e valori predefiniti globali.

Implementa e ritira le funzionalità in tutta sicurezza

Promuovere una funzionalità tramite gli stati test, interno, di attivazione, canary, disponibile, deprecato e bloccato. Durante il canarying, confronta le distribuzioni dello stato, i motivi dell'interruzione, le sequenze di blocchi di contenuto, il comportamento dello strumento, i campi di utilizzo, la latenza e i risultati della cache. Definisci le soglie di rollback prima che inizi il traffico.

Il pensionamento dovrebbe avvenire per fasi:

1. Blocca l'adozione di nuovi tenant mentre continuano le assegnazioni esistenti.
2. Identifica tenant, chiavi, modelli e modelli di richiesta recenti interessati.
3. Fornisci un report di compatibilità o esegui un test dell'endpoint per la sostituzione.
4. Avvisa sulle richieste ammesse e pubblica un limite definitivo.
5. Richiedi eccezioni esplicite con proprietari e date di scadenza.
6. Blocca la funzionalità e conserva il record del registro per il controllo storico e l'interpretazione della fatturazione.

Il blocco aumenta la riproducibilità ma espande la matrice del test. Una versione a livello di gateway riduce le varianti operative ma associa tenant non correlati a un'unica pianificazione di migrazione. L'ampio pass-through beta accelera l'accesso alle funzionalità ma indebolisce le garanzie di costi, residenza e supporto. Per un servizio multi-tenant, la politica esplicita per-tenant rappresenta solitamente la via di mezzo difendibile.

Elenco di controllo per l'implementazione

• Richiedi una policy di versione per ogni tenant o API chiave.
• Conserva i record delle versioni testate e delle funzionalità beta.
• Rifiuta funzionalità non valide, sconosciute o non autorizzate prima dell'invio.
• Seleziona i percorsi solo dopo aver risolto la richiesta di protocollo completa.
• Preserva i blocchi di contenuti nativi, i motivi dell'interruzione, i campi di utilizzo e gli stream.
• Inoltra gli eventi di streaming additivi in modo sicuro e conserva i nomi degli eventi.
• Registra i valori di protocollo richiesti ed effettivi sugli eventi di utilizzo e di controllo.
• Esegui dispositivi di contratto e canarini controllati prima di modificare le impostazioni predefinite.
• Ritirare le vecchie funzionalità attraverso controlli di adozione misurati, non riscritture silenziose.

La decisione chiave in termini di progettazione è semplice: le intestazioni versione e beta sono input di policy. Una volta che il gateway li ammette, li instrada, li testa e li misura come capacità, la compatibilità API nativa diventa governabile senza fingere che il comportamento sperimentale sia un normale HTTP metadato.

Lettura correlata

• che tiene conto dell'utilizzo finale, delle cancellazioni e delle risposte parziali allo streaming