Limiti di frequenza, quote e livelli
In questa pagina
Limiti di frequenza, quote e livelli
I limiti di frequenza definiscono quante richieste puoi inviare all’API al minuto. Comprendere e gestire questi limiti è fondamentale per evitare interruzioni del servizio in produzione. Lo scenario da incubo è sempre lo stesso: un’integrazione che funzionava perfettamente in sviluppo, dove inviavi tre richieste al minuto, va in produzione e improvvisamente deve elaborare una coda di diverse migliaia di documenti. Gli errori 429 arrivano a valanga e metà dell’elaborazione va persa perché il throughput non era stato previsto.
Il sistema a livelli
OpenAI organizza i limiti in livelli (tier) basati sulla tua cronologia di fatturazione. Non scegli il tuo livello; lo sblocchi accumulando spesa e attendendo il trascorrere di una finestra temporale. Questa progressione ha un’importante conseguenza pratica: un account creato solo per una demo cliente non avrà la stessa capacità del tuo account di produzione, anche se il codice è identico.
# I livelli determinano i tuoi limiti
# Livello 1: Dopo il primo pagamento riuscito
# Livello 2: Dopo $50 di spesa cumulativa + 7 giorni
# Livello 3: Dopo $100 di spesa cumulativa + 7 giorni
# Livello 4: Dopo $250 di spesa cumulativa + 14 giorni
# Livello 5: Dopo $1000 di spesa cumulativa + 30 giorni
# I limiti aumentano significativamente con ogni livello
Tipi di limiti di frequenza
Tre contatori si applicano simultaneamente e il primo che raggiungi ti blocca. L’elaborazione di testi brevi saturerà gli RPM (Richieste Per Minuto) molto prima degli TPM (Token Per Minuto); al contrario, l’analisi di documenti lunghi esaurirà gli TPM anche se hai inviato solo poche decine di richieste. Controlla sempre l’ordine di grandezza dei tuoi prompt prima di dimensionare il tuo parallelismo.
# 1. RPM — Richieste Per Minuto
# 2. TPM — Token Per Minuto
# 3. RPD — Richieste Per Giorno
# Ordine di grandezza per il Livello 3 (verifica i tuoi limiti effettivi
# su platform.openai.com > Settings > Limits):
# RPM: 5.000 richieste/minuto
# TPM: 2.000.000 token/minuto
# RPD: 10.000 richieste/giorno
Lettura degli header dei limiti di frequenza
Non devi indovinare il tuo consumo: ogni risposta lo riporta nei suoi header HTTP. L’SDK li nasconde di default per restituire solo l’oggetto analizzato, ma with_raw_response ti dà accesso alla risposta grezza e parse() ricostruisce l’oggetto usuale. Una dashboard alimentata da questi valori ti avvisa mentre ti avvicini al tetto invece di farti scoprirlo tramite un errore.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
# Accesso agli header tramite la risposta HTTP grezza
# Utilizzo della modalità with_raw_response
raw = client.responses.with_raw_response.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(f"Limite RPM: {raw.headers.get('x-ratelimit-limit-requests')}")
print(f"RPM rimanenti: {raw.headers.get('x-ratelimit-remaining-requests')}")
print(f"Limite TPM: {raw.headers.get('x-ratelimit-limit-tokens')}")
print(f"TPM rimanenti: {raw.headers.get('x-ratelimit-remaining-tokens')}")
print(f"Reset tra: {raw.headers.get('x-ratelimit-reset-requests')}")
response = raw.parse()
print(f"Risposta: {response.output_text}")
Limitazione della frequenza lato client
È meglio rallentare da soli che essere rifiutati. Due implementazioni coprono la maggior parte delle esigenze.
Limitazione del throughput con un semaforo
La prima combina un semaforo, che limita il numero di chiamate simultanee, con un ritardo calcolato in base al throughput target. Nell’esempio, cinquanta riassunti vengono lanciati tutti insieme ma solo cinque procedono in parallelo, spaziati dal ritardo corrispondente a 100 richieste al minuto. Il codice chiamante rimane un semplice asyncio.gather: tutta la disciplina è incapsulata nella classe.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
class RateLimiter:
"""Limita il numero di richieste simultanee."""
def __init__(self, max_concurrent: int = 10, rpm: int = 500):
self.semaphore = asyncio.Semaphore(max_concurrent)
self.rpm = rpm
self.delay = 60.0 / rpm # Ritardo tra ogni richiesta
async def call(self, prompt: str) -> str:
async with self.semaphore:
await asyncio.sleep(self.delay)
response = await async_client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
return response.output_text
async def batch_processing():
limiter = RateLimiter(max_concurrent=5, rpm=100)
prompts = [f"Riassumi il concetto {i}" for i in range(50)]
tasks = [limiter.call(p) for p in prompts]
results = await asyncio.gather(*tasks)
for i, r in enumerate(results):
print(f"Risultato {i}: {r[:50]}...")
# asyncio.run(batch_processing())
Semplice token bucket
Il token bucket è più flessibile perché consente burst di traffico. Il secchio si riempie a una velocità costante e si svuota a ogni chiamata: se la tua applicazione è stata inattiva per un minuto, può ripartire a piena velocità per cinquanta richieste, per poi tornare naturalmente alla velocità di riempimento. Questo è esattamente il comportamento desiderato per un servizio che alterna picchi e momenti di calma, e funziona in ambienti multithread grazie al lock.
import time
import threading
class TokenBucket:
"""Limitatore di frequenza basato sull'algoritmo del token bucket."""
def __init__(self, tokens_per_second: float, max_capacity: int):
self.tokens_per_second = tokens_per_second
self.max_capacity = max_capacity
self.tokens = max_capacity
self.last_refill = time.monotonic()
self.lock = threading.Lock()
def wait(self, tokens_needed: int = 1):
"""Attende finché non sono disponibili abbastanza token."""
while True:
with self.lock:
now = time.monotonic()
elapsed = now - self.last_refill
self.tokens = min(
self.max_capacity,
self.tokens + elapsed * self.tokens_per_second
)
self.last_refill = now
if self.tokens >= tokens_needed:
self.tokens -= tokens_needed
return
time.sleep(0.1)
# Utilizzo: max 50 richieste al minuto
bucket = TokenBucket(tokens_per_second=50/60, max_capacity=50)
def limited_call(prompt: str) -> str:
bucket.wait(1)
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
return response.output_text
Strategie per volumi elevati
1. Distribuire su più progetti
Ogni progetto ha i propri limiti di frequenza. Se raggiungi il tuo tetto essendo già su un livello alto, distribuire le chiamate su più progetti moltiplica meccanicamente la capacità disponibile. Il round-robin sottostante illustra il principio; in produzione, sposta il ciclo fuori dalla funzione affinché persista tra le chiamate.
from openai import OpenAI
# Ogni progetto ha i propri limiti di frequenza
clients = [
OpenAI(project="proj-aaaa"), # Progetto 1
OpenAI(project="proj-bbbb"), # Progetto 2
OpenAI(project="proj-cccc"), # Progetto 3
]
def round_robin_call(prompt: str, clients: list) -> str:
"""Distribuisce le chiamate su più progetti."""
import itertools
client_cycle = itertools.cycle(clients)
client = next(client_cycle)
return client.responses.create(
model="gpt-5.6-terra",
input=prompt
).output_text
2. Usare il modello giusto per il volume giusto
La scelta del modello è anche una decisione di capacità, non solo di qualità. Riservare i modelli più pesanti per compiti critici e instradare il volume verso un modello con limiti più alti libera throughput dove ne hai effettivamente bisogno.
# I modelli economici (gpt-5.6-luna) hanno i limiti più alti
# Usali per compiti ad alto volume
# Il modello di punta (gpt-5.6-sol) ha i limiti più bassi
# Riservalo per compiti critici
3. Code (Queuing)
Infine, l’uso di code disaccoppia la produzione delle richieste dal loro consumo. Un singolo thread preleva dalla coda a un ritmo fisso mentre il resto dell’applicazione invia liberamente; il chiamante si blocca su un evento finché il suo risultato non arriva. Questo schema assorbe i picchi senza superare mai il throughput configurato.
import queue
import threading
class APIQueue:
"""Coda per le chiamate API."""
def __init__(self, rpm: int = 100):
self.queue = queue.Queue()
self.delay = 60.0 / rpm
self.running = True
self.worker = threading.Thread(target=self._process, daemon=True)
self.worker.start()
def _process(self):
while self.running:
try:
prompt, future = self.queue.get(timeout=1)
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
future["result"] = response.output_text
future["event"].set()
time.sleep(self.delay)
except queue.Empty:
continue
def submit(self, prompt: str) -> str:
future = {"result": None, "event": threading.Event()}
self.queue.put((prompt, future))
future["event"].wait()
return future["result"]
Punti chiave
- I limiti di frequenza si applicano simultaneamente per RPM, TPM e RPD
- Il tuo livello determina i tuoi limiti: aumenta con la tua spesa cumulativa
- Leggi gli header
x-ratelimit-*per conoscere il tuo consumo in tempo reale - Implementa un limitatore di frequenza lato client per evitare errori 429
- Distribuisci il carico su più progetti per volumi elevati
- Luna offre i limiti di frequenza più alti per l’elaborazione in blocco