Gateway API AI sensibili ai limiti di velocità: modella RPM, TPM, burst ed equità dei tenant prima che colpiscano i 429

Un 429 da un fornitore LLM non è solo un segnale di nuovo tentativo. Nella produzione, è spesso evidente che la tua applicazione ha già perso il controllo sull'ammissione, sull'equità del tenant, sulla latenza o sulla contabilità delle quote specifiche del provider.

La soluzione comune, ovvero il backoff esponenziale, è necessaria ma incompleta. Il backoff reagisce dopo che il provider rifiuta il traffico. Un AI API gateway sensibile ai limiti di velocità dovrebbe modellare il traffico prima che le richieste lascino il sistema: stimare la pressione dei token, riservare la quota, isolare i tenant, mettere in coda il lavoro giusto, rifiutare il lavoro sbagliato e adattarsi quando cambiano i limiti del provider.

Questo articolo descrive un pratico regolatore della quota del gateway per i team che inviano carichi di lavoro di produzione a più provider LLM tramite un API.

Il problema del lettore: i 429 sono multidimensionali

Molti team trattano i limiti di velocità come se fossero un unico numero di richieste al minuto. Questo presupposto si rompe rapidamente con le API LLM.

Fatti dalla documentazione attuale del fornitore:

• OpenAI documenta che i limiti possono essere applicati su finestre più brevi rispetto al limite al minuto pubblicizzato, pertanto i burst brevi possono fallire anche quando il minuto medio sembra sicuro.
La quota di
• Azure OpenAI viene assegnata in base alla sottoscrizione, all'area geografica, al modello e al tipo di distribuzione in token al minuto. L'assegnazione di TPM a una distribuzione determina anche i limiti RPM di inferenza applicati e i rapporti RPM/TPM variano in base al modello.
• Azure OpenAI rileva inoltre che i calcoli dei token del limite di velocità vengono stimati al momento della ricezione della richiesta e non corrispondono ai conteggi finali dei token di fatturazione.
• Anthropic documenti separano i limiti di richieste al minuto, token di input al minuto e token di output al minuto. Il superamento dei limiti restituisce un 429 con un'intestazione retry-after.
• Anthropic avverte che i forti aumenti del traffico possono raggiungere i limiti di accelerazione e consiglia un aumento graduale.
• Per la maggior parte dei Claude modelli, Anthropic documenti che i token di input letti nella cache non vengono conteggiati ai fini dei limiti di token di input al minuto, il che significa che la memorizzazione nella cache dei prompt può modificare il margine effettivo.
I limiti di tariffa
• Google Gemini API sono legati ai livelli di utilizzo del progetto, mentre i livelli più alti dipendono dalla configurazione della fatturazione, dalla spesa cumulativa e dal tempo trascorso dopo i traguardi di pagamento.

La lezione operativa è chiara: una forma di richiesta compatibile con OpenAI non implica un comportamento della quota compatibile con OpenAI. Un gateway multi-provider necessita di un modello di quote interno più ricco di "riprova se 429".

Obiettivo di progettazione: rendere il controllo dell'ammissione una responsabilità del gateway

Un gateway in grado di riconoscere i limiti di velocità dovrebbe rispondere a cinque domande prima di inviare una richiesta:

1. Quale provider, modello, distribuzione, regione, progetto o area di lavoro riceverà la richiesta?
2. Quanta capacità di richieste, token di input, token di output e simultaneità potrebbe consumare?
3. Quale tenant, team, API chiave, cliente o classe di carico di lavoro deve essere addebitato sulla capacità condivisa?
4. La richiesta deve essere ammessa adesso, messa in coda brevemente, declassata, instradata altrove o rifiutata?
5. Come deve essere riconciliata la prenotazione dopo che il fornitore restituisce l'utilizzo effettivo?

Il gateway diventa un regolatore della quota. Non sostituisce i limiti del fornitore. Rende i limiti del fornitore visibili, prevedibili ed equi all'interno del tuo sistema.

Crea un modello di quote normalizzate

Inizia definendo dimensioni limite interne che possano rappresentare i principali fornitori senza forzarli in un unico intervallo fuorviante.

Dimensioni del limitatore consigliate

• RPM: richieste al minuto.
• TPM di input: token di prompt, messaggio, strumento e contesto al minuto.
• TPM di output: token di completamento al minuto, riservati separatamente per streaming e generazioni lunghe.
• TPM totale: utile per provider o distribuzioni che espongono la pressione combinata dei token.
• Concorrenza: richieste attive, flussi attivi o processi in volo.
• Durata dello streaming: gli streaming di lunga durata possono occupare spazio per la connessione e il token di output anche quando l'RPM è basso.
• Ambito specifico del provider: sottoscrizione/regione/distribuzione di Azure, Anthropic area di lavoro/classe di modello, Google progetto/livello o OpenAI organizzazione/progetto/gruppo di modelli.

Non nascondere le dimensioni specifiche del fornitore. Normalizzali in uno schema comune, ma conserva dettagli sufficienti per spiegare un rifiuto in un secondo momento.

{
  "provider": "provider_a",
  "model_profile": "fast-chat",
  "provider_scope": {
    "project": "prod",
    "region": "us-east",
    "deployment": "chat-large-01"
  },
  "limits": {
    "rpm": 1200,
    "input_tpm": 800000,
    "output_tpm": 250000,
    "concurrency": 200
  }
}

Questo oggetto interno deve essere configurato in modo esplicito, non dedotto solo dai nomi dei modelli. I dashboard dei fornitori, i livelli di account, le distribuzioni regionali e le impostazioni dell'area di lavoro possono modificare la capacità effettiva della stessa famiglia di modelli.

Stima la pressione dei token prima dell'invio

La limitazione della tariffa da parte del fornitore spesso viene applicata prima che sia noto l'utilizzo della fatturazione finale. Il tuo gateway dovrebbe effettuare lo stesso tipo di stima conservativa prima di inviare traffico.

Input per la prenotazione pre-volo

• Messaggio serializzato e lunghezza del messaggio.
• Tokenizzazione specifica del modello e sovraccarico per ruoli, strumenti, immagini o istruzioni di output strutturato.
• max_completion_tokens o limite di output equivalente.
• Percentuale di completamento storico per questo endpoint, tenant, profilo del modello e classe di richiesta.
• Token di lettura della cache previsti se la memorizzazione nella cache dei prompt è disponibile e misurabile.
• Segnale di streaming e durata prevista dello streaming.

Spesso è sufficiente una semplice regola di prenotazione per iniziare:

estimated_input_tokens = tokenize(request_messages) + model_overhead
estimated_output_tokens = min(
  max_completion_tokens,
  p95_historical_output_tokens_for_route
)
reserved_total_tokens = estimated_input_tokens + estimated_output_tokens

Per percorsi sconosciuti, utilizza un valore predefinito conservativo. Per percorsi di produzione stabili, aggiorna continuamente le stime in base all'utilizzo effettivo.

Prenota e riconcilia

Le prenotazioni delle quote non devono diventare addebiti permanenti. Trattali come prenotazioni:

1. Citazione: stima la pressione in ingresso e in uscita.
2. Riserva: deduci dai bucket di token pertinenti prima della spedizione.
3. Paga: sostituisci la stima con l'utilizzo riportato dal fornitore, quando disponibile.
4. Rimborso o addebito: restituisce la capacità riservata non utilizzata o addebita le eccedenze alla finestra successiva, se necessario.

Questo è particolarmente importante per le chiamate in streaming e con contesto lungo. Se controlli solo il TPM di input prima dell'invio, un flusso può avviarsi correttamente e quindi subire una pressione del token di output in un secondo momento. Riservare separatamente l'headroom di output riduce i guasti a metà flusso e il rischio di stallo.

Utilizza bucket di token gerarchici per l'equità del tenant

Un singolo limitatore globale protegge l'account del fornitore ma non protegge i tenant gli uni dagli altri. Un processo batch a contesto lungo può utilizzare il TPM condiviso e causare il fallimento delle richieste interattive di altri team.

Utilizza bucket di token gerarchici:

organization
  └── tenant
      └── team
          └── api_key
              └── model_profile
                  └── provider_deployment

Una richiesta deve superare ogni bucket pertinente. Ciò ti consente di applicare più norme contemporaneamente:

• L'organizzazione non può superare la capacità del fornitore.
• Un inquilino non può consumare più della quota contrattata.
• Una chiave API non può superare il limite dell'ambiente o dell'applicazione previsto.
• Un profilo del modello batch non può affamare un profilo del modello interattivo.
• Non è possibile sovraccaricare una distribuzione del provider anche se un'altra distribuzione dispone di una quota di riserva.

Condivisione equa rispetto all'utilizzo

Raccomandazione: utilizza la condivisione equa ponderata con prestiti a raffica controllati.

I limiti rigorosi per tenant sono facili da spiegare, ma possono bloccare la capacità inutilizzata. Il prestito accelerato migliora l'utilizzo consentendo a un tenant di utilizzare temporaneamente la quota inattiva da un pool condiviso. Il compromesso è la complessità: le dashboard devono mostrare cosa è stato garantito, cosa è stato preso in prestito e quando il prestito è stato revocato.

Una regola pratica:

• Offri a ciascun inquilino un riferimento garantito.
• Consenti il prestito accelerato dalla capacità condivisa inutilizzata.
• Recupera la capacità presa in prestito quando viene visualizzato traffico con priorità più alta o garantito.
• Non lasciare mai che il traffico preso in prestito crei 429 a livello di provider per traffico garantito.

Separa le classi di traffico prima che si contendano

Non tutte le richieste meritano lo stesso comportamento in coda. Inserisci il traffico nei profili del modello con code e pool di quote separati.

L'accodamento migliora la percentuale di successo ma aumenta la latenza della coda. Un gateway dovrebbe rendere esplicito questo compromesso. Ad esempio, una richiesta interattiva potrebbe attendere fino a 300 millisecondi per la quota, quindi eseguire il fallback o fallire. Un processo batch notturno potrebbe attendere 20 minuti ed essere comunque considerato riuscito.

Normalizza i 429 in un unico schema di errore

Anche con un buon controllo dell'ammissione, si verificheranno comunque casi 429 del provider. I limiti possono cambiare, le stime del fornitore possono differire dalle tue e il traffico può arrivare con picchi più rapidi del previsto.

Normalizza ogni provider 429 in un oggetto di errore del gateway:

{
  "error": {
    "type": "rate_limited",
    "limiter": "output_tpm",
    "provider": "provider_a",
    "model_profile": "fast-chat",
    "provider_model": "model-x",
    "retry_after_ms": 2400,
    "tenant_id": "tenant_123",
    "api_key_id": "key_456",
    "request_class": "interactive",
    "estimated_input_tokens": 4200,
    "estimated_output_tokens": 800,
    "gateway_decision": "admitted_then_provider_rejected",
    "fallback_allowed": false,
    "trace_id": "trace_abc"
  }
}

Il campo chiave è gateway_decision. Un 429 dopo che il gateway ha ammesso la richiesta è diverso da una richiesta che il gateway ha rifiutato localmente prima dell'invio. Il primo indica un problema di calibrazione del limitatore. Il secondo indica protezione intenzionale.

Adatta alle intestazioni del provider, ma non dipende da esse

Alcuni fornitori restituiscono intestazioni utili come gli indicatori di riprova dopo o di capacità rimanente. Usali quando disponibili.

Raccomandazione: le intestazioni dei provider dovrebbero ottimizzare il governatore locale, non sostituirlo.

Motivi:

• La disponibilità dell'intestazione varia in base al provider e all'endpoint.
• Le intestazioni potrebbero non esporre tutte le dimensioni limite.
• Riprova dopo indica quando riprovare, non quale tenant dovrebbe ottenere la capacità successiva.
• Le stime dei token lato fornitore potrebbero differire dalla fatturazione o dalla contabilità interna.

Un'implementazione solida aggiorna i tassi di ricarica del bucket locale e i tempi di recupero in base alle intestazioni, applicando comunque i limiti di distribuzione di tenant, API chiave, classe di traffico e provider all'interno del gateway.

Aggiungi regolatori di rampa per migrazioni e job pianificati

Molti incidenti legati ai limiti di frequenza si verificano durante le modifiche pianificate: passaggio da un modello a un altro, cambio di fornitori, attivazione di un nuovo flusso di lavoro dell'agente o avvio di un'esecuzione di valutazione pianificata.

Raccomandazione: considera la crescita del traffico come un'implementazione controllata.

• Migrazioni di modelli di flag di funzionalità per tenant, percorso o percentuale di traffico.
• Imposta limiti di crescita al minuto per le implementazioni di nuovi fornitori.
• Riscalda il traffico gradualmente nel corso delle ore invece di commutare tutto il traffico all'istante.
• Sospendi l'implementazione quando la frequenza 429, la frequenza di downgrade, la profondità della coda o la latenza p95 supera una soglia.
• Mantieni un percorso di ripristino di emergenza con una policy di compatibilità, non solo con un modello di riserva.

Previsione: man mano che le modalità di routing dei fornitori, i livelli di priorità e i controlli a livello di area di lavoro diventano più comuni, la governance di rampa diventerà una funzionalità gateway standard anziché uno script di risposta agli incidenti.

Il fallback è una decisione politica, non solo una decisione sulla capacità

Quando un provider restituisce un 429, l'instradamento a un altro provider potrebbe essere la risposta giusta. Potrebbe anche essere pericoloso.

Il fallback può cambiare:

• Qualità dell'output e istruzioni seguenti.
• Lunghezza del contesto.
• Comportamento di chiamata allo strumento.
• Affidabilità dell'output strutturato.
• Conservazione dei dati e atteggiamento di residenza.
• Costo e latenza.

Il regolatore della quota dovrebbe chiedere a un livello di compatibilità se è consentito il fallback per questa classe di richiesta. In caso contrario, dovrebbe accodarsi o fallire con una chiara risposta al limite di velocità locale anziché modificare silenziosamente la semantica.

Esponi dashboard delle quote che spiegano le decisioni

Un sistema di quote che nessuno può comprendere verrà aggirato. Crea dashboard attorno a domande operative:

• Quali tenant consumano più RPM, TPM di input e TPM di output?
• Quali profili di modello sono in coda, rifiutati o fallback?
• Quale ambito del provider rappresenta il collo di bottiglia: progetto, regione, distribuzione, area di lavoro, classe del modello o livello di account?
• Con quale frequenza le stime del gateway differiscono dall'utilizzo del provider?
• Qual è la distribuzione dei tentativi dopo per provider e tipo di limitatore?
• Quanto margine efficace viene creato dalle letture della cache dei prompt?
• Quali classi di traffico utilizzano la capacità burst?

Per i prodotti rivolti ai clienti o ai partner, esponi controlli sicuri:

• Limiti di velocità per chiave.
• Limiti di burst per squadra.
• Limiti giornalieri per cliente.
• Pausa di emergenza per un tenant o una chiave.
• Avvisi per picchi 429, crescita della coda e pressione anomala dei token.
• Partner API endpoint per la gestione delle quote dei rivenditori.

Ciò trasforma la limitazione della velocità da un errore misterioso del provider in una parte verificabile della governance del team API.

Elenco di controllo per l'implementazione

Fase 1: osservare e classificare

• Provider di log, modello, distribuzione, regione, area di lavoro, progetto, tenant, chiave API e classe di richiesta per ogni chiamata.
• Acquisisci i provider 429 con metadati Retry-After e errori non elaborati.
• Registra separatamente i token di input/output stimati ed effettivi.
• Separa il traffico interattivo, batch, di valutazione e in background nella telemetria.

Fase 2: controllo dell'ammissione locale

• Crea oggetti limitatori interni per RPM, TPM di input, TPM di output, TPM totale e concorrenza.
• Aggiungi la stima dei token di verifica preliminare.
• Prenota la quota prima dell'invio e riconcilia dopo l'arrivo dell'utilizzo del provider.
• Rifiuta localmente quando una richiesta non può adattarsi al suo tenant o al bucket del provider.

Fase 3: equità e code

• Aggiungi bucket gerarchici dall'organizzazione all'implementazione del provider.
• Assegna quote di locatario garantite e prestiti a raffica controllati.
• Crea code separate per classe di traffico.
• Imposta tempi di attesa massimi e regole di fallback specifici per classe.

Fase 4: adattamento e operazioni

• Utilizza le intestazioni del fornitore per regolare i tempi di recupero e le ipotesi di ricarica.
• Aggiungi regolatori di rampa per migrazioni e job pianificati.
• Esponi dashboard e avvisi sulle quote.
• Rivedi settimanalmente l'errore di stima e la quota bloccata.

Conclusione attuabile

Se il gateway riprova solo 429, funziona dopo l'errore. Un AI API gateway di livello produttivo dovrebbe prevenire la maggior parte degli errori relativi ai limiti di velocità decidendo chi è autorizzato a inviare cosa, quando e rispetto a quale quota del provider.

Inizia con un modello limitatore normalizzato, prenotazione di token preflight e code di classi di traffico. Quindi aggiungere l'equità gerarchica del tenant, l'adattamento dell'intestazione del provider e i regolatori della rampa. Il risultato non è solo un minor numero di 429. Si tratta di un'allocazione della capacità più chiara, una latenza più prevedibile, migrazioni più sicure e un comportamento in termini di limiti di velocità che i team tecnici, finanziari e di assistenza clienti possono effettivamente spiegare.

Leggi correlati

• prenotazione preflight e riconciliazione dell'utilizzo
• richiesta contabilità cache e cache-hit analisi
• criteri di routing di fallback compatibili