Limiti e quote
Quante richieste e quanti token al minuto, quanto può essere grande una chiamata, cosa riprovare
Una chiamata API può essere fermata per tre motivi: troppe richieste in poco tempo, una richiesta troppo grande, oppure credito o budget finiti. Il terzo è spiegato in Costi, budget e analytics; qui ci sono gli altri due, e come scrivere un client che li regge.
Limiti di frequenza
I limiti valgono per area di lavoro e per modello, sommando tutte le chiavi: creare una chiave in più non li raddoppia, mentre due modelli diversi hanno due contatori separati.
Il minuto è una finestra che scorre, non si azzera allo scoccare del minuto.
Il limite che si incontra per primo è quasi sempre quello sui token, per come
vengono contati. Quando una chiamata parte, Userbot prenota i token che
potrebbe usare: una stima del testo che mandi più il tetto della risposta, cioè
max_tokens o, se non lo indichi, 16.384. A risposta finita la prenotazione
viene corretta con i token davvero usati.
In pratica, senza max_tokens ogni chiamata prenota più di 16.000 token, e sullo
stesso modello ne stanno in volo poco più di tre alla volta. Indicare un
max_tokens realistico per il tuo compito è il modo più semplice per farne
passare molte di più.
Oltre il limite ricevi 429 con questo corpo:
Le risposte non portano header X-RateLimit-* né Retry-After: il tuo client
deve gestire l’attesa da solo, come spiegato più sotto.
Limiti di dimensione
Tutti i messaggi che mandi, più la risposta da generare, devono stare nella finestra di contesto del modello: oltre, la richiesta fallisce. Se lavori su documenti lunghi, spezzali e chiama più volte.
Quando la risposta si ferma al tetto, finish_reason vale length: controllalo
prima di usare il testo, perché vuol dire che è tagliato.
Il limite anti-spam della chat, i 250 messaggi ogni 3 ore per persona, non vale per l’API.
Riprovare quando qualcosa va storto
Distingui il temporaneo dal definitivo
Si riprovano il 429 senza code (frequenza), il 500 e il 503. Non si
riprovano 400, 401, 402, 403, 451 e i 429 con un code di
budget: sono un corpo da correggere, una chiave da sistemare o un credito da
ricaricare, e aspettare non serve.
Progettare per stare dentro i limiti
Accoda invece di parallelizzare. Manda le richieste da una coda con un numero fisso di processi, non aprendo una chiamata per ogni riga di un file.
Indica sempre max_tokens. È quello che decide quante chiamate stanno in
volo insieme.
Raggruppa il lavoro. Dieci frasi da classificare stanno in una richiesta sola, con la risposta chiesta in elenco. Per gli embedding, manda una lista di testi in una chiamata.
Distribuisci sui modelli. I contatori sono per modello: due flussi di lavoro diversi su due modelli non si rubano spazio.
Metti in cache le risposte stabili. Se la stessa domanda torna uguale, la seconda volta non serve chiamare.
Separa gli ambienti. Staging e produzione con chiavi diverse ti dicono chi ha consumato cosa nelle analytics.
Se il tuo carico richiede limiti più alti, scrivi a support@userbot.ai indicando le richieste e i token al minuto che ti servono, e su quali modelli.