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 provider LLM non è solo un segnale di nuovo tentativo. In fase di produzione, è spesso evidente che la tua domanda ha già perso il controllo sull'ammissione, sull'equità del locatario, sulla latenza o sulla contabilità delle quote specifiche del fornitore.

La soluzione comune, ovvero il backoff esponenziale, è necessaria ma incompleta. Il backoff reagisce dopo che il provider rifiuta il traffico. Un gateway API AI sensibile ai limiti di velocità dovrebbe modellare il traffico prima che le richieste lascino il tuo 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 delle quote del gateway per i team che inviano carichi di lavoro di produzione a più provider LLM tramite un'API unificata.

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, quindi brevi raffiche possono fallire anche quando il minuto medio sembra sicuro.
• La quota di Azure OpenAI viene assegnata in base a sottoscrizione, area, modello e 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 dei token di fatturazione finali.
• I documenti Anthropic 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 modelli Claude, i documenti Anthropic che leggono nella cache i token di input 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 velocità dell'API Google Gemini sono legati ai livelli di utilizzo del progetto, con livelli più alti che 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 di quota compatibile con OpenAI. Un gateway multi-provider necessita di un modello di quote interno più ricco di "riprova se 429".

Obiettivo della 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 concorrenza potrebbe consumare?
3. Quale tenant, team, chiave API, 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.

Costruisci un modello di quote normalizzato

Inizia definendo le dimensioni del limitatore interno che possono 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.
• Output TPM: 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 lavori in volo.
• Durata dello streaming: i flussi 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, area di lavoro/classe di modello Anthropic, progetto/livello Google o organizzazione/progetto/gruppo di modelli OpenAI.

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

{
  "fornitore": "fornitore_a",
  "model_profile": "chat veloce",
  "ambito_provider": {
    "progetto": "prod",
    "regione": "noi-est",
    "distribuzione": "chat-large-01"
  },
  "limiti": {
    "giri/min": 1200,
    "input_tpm": 800000,
    "output_tpm": 250000,
    "concorrenza": 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 provider 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 preliminare

• Prompt 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.
• Rapporto 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.
• Contrassegna streaming e durata prevista dello streaming.

Spesso è sufficiente una semplice regola di prenotazione per iniziare:

estimated_input_tokens = tokenize(request_messages) + model_overhead
gettoni_output_stimati = min(
  max_completion_tokens,
  p95_historical_output_tokens_for_route
)
token_totali_riservati = token_input_stimati + token_output_stimati

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

Prenota, quindi riconcilia

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

1. Citazione: stimare la pressione in ingresso e in uscita.
2. Riserva: detrarre dai relativi bucket di token prima della spedizione.
3. Calcola: 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 nella finestra successiva, se necessario.

Ciò è 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 uscita riduce i guasti a metà flusso e il rischio di stallo.

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

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

Utilizza contenitori di token gerarchici:

organizzazione
  └── inquilino
      └── squadra
          └── api_key
              └── profilo_modello
                  └── provider_deployment

Una richiesta deve superare ciascun bucket pertinente. Ciò ti consente di applicare più policy 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: utilizzare un'equa condivisione 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à: i dashboard devono mostrare cosa è stato garantito, cosa è stato preso in prestito e quando il prestito è stato revocato.

Una regola pratica:

• Offri a ciascun inquilino una linea di base garantita.
• Consenti prestiti rapidi 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.

Separare 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 lavoro 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, i provider 429 continueranno a verificarsi. I limiti possono cambiare, le stime del fornitore possono differire dalle tue e il traffico può arrivare a raffiche più intense del previsto.

Normalizza ogni provider 429 in un oggetto errore gateway:

{
  "errore": {
    "tipo": "tariffa_limitata",
    "limitatore": "output_tpm",
    "fornitore": "fornitore_a",
    "model_profile": "chat veloce",
    "provider_model": "modello-x",
    "riprova_dopo_ms": 2400,
    "tenant_id": "tenant_123",
    "api_key_id": "chiave_456",
    "request_class": "interattivo",
    "estimated_input_tokens": 4200,
    "estimated_output_tokens": 800,
    "gateway_decision": "ammesso_then_provider_rejected",
    "fallback_allowed": falso,
    "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 una protezione intenzionale.

Adattarsi alle intestazioni del provider, ma non dipendere da esse

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

Raccomandazione: le intestazioni dei fornitori dovrebbero adattare 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 limitatrici.
• 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 dei bucket locali e i tempi di recupero in base alle intestazioni, applicando comunque limiti di distribuzione di tenant, chiave API, classe di traffico e provider all'interno del gateway.

Aggiungi regolatori di rampa per migrazioni e lavori 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 politica 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 successive.
• Lunghezza del contesto.
• Comportamento di chiamata allo strumento.
• Affidabilità dell'output strutturato.
• Posizione di conservazione e residenza dei dati.
• 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.

Esporre dashboard sulle 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 ritirati?
• 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.
• Endpoint API partner per la gestione delle quote dei rivenditori.

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

Lista di controllo per l'implementazione

Fase 1: osservare e classificare

• Registra provider, modello, distribuzione, regione, area di lavoro, progetto, tenant, chiave API e classe di richiesta per ogni chiamata.
• Acquisisci i provider 429 con metadati di errore non elaborato e riprova dopo.
• Registra separatamente i token di input/output stimati ed effettivi.
• Separare il traffico interattivo, batch, di valutazione e in background nella telemetria.

Fase 2: controllo di ammissione locale

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

Fase 3: equità e code

• Aggiungi bucket gerarchici dall'organizzazione alla distribuzione del provider.
• Assegnare quote garantite agli inquilini e prestiti controllati a raffica.
• 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 ricaricare le ipotesi.
• Aggiungi regolatori di rampa per migrazioni e lavori pianificati.
• Esporre 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 gateway API AI 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
• prompt cache accounting e analisi dei riscontri nella cache
• policy di routing di fallback compatibili