Utilizzo dei semafori per limitare le richieste concorrenti
In questa pagina
Il problema della concorrenza incontrollata
Inviare tutte le richieste in parallelo senza limiti è un errore comune. Se devi elaborare 200 domande e le lanci tutte simultaneamente, raggiungerai i limiti di frequenza (rate limits) delle API, riceverai errori HTTP 429 e rischi il blocco temporaneo della tua chiave API.
Il semaforo è la soluzione standard per controllare il numero di richieste concorrenti. Si tratta di un contatore che consente a un numero massimo di coroutine di essere eseguite in parallelo.
Come funzionano i semafori
asyncio.Semaphore agisce come un blocco contatore. Quando una coroutine entra nel blocco async with semaphore, il contatore diminuisce. Quando ne esce, il contatore aumenta. Se il contatore raggiunge zero, le coroutine successive attendono fino a quando non si libera uno slot.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # massimo 5 richieste simultanee
async def process_request(request: str):
async with semaphore:
# Questa sezione è limitata a 5 esecuzioni parallele
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
In questo esempio, anche se lanci 100 coroutine con asyncio.gather, solo 5 verranno eseguite simultaneamente. Le altre 95 aspetteranno il loro turno.
Pattern completo con l’SDK OpenAI
Ecco lo stesso pattern utilizzando AsyncOpenAI, spesso preferito per la compatibilità:
from openai import AsyncOpenAI
import httpx
client = AsyncOpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
timeout=httpx.Timeout(3600.0)
)
async def send_request(sem: Semaphore, request: str) -> dict:
async with sem:
return await client.chat.completions.create(
model="grok-4.20-0309-reasoning",
messages=[{"role": "user", "content": request}]
)
async def process_all(requests: list[str], max_concurrent: int = 5):
sem = Semaphore(max_concurrent)
tasks = [send_request(sem, r) for r in requests]
return await asyncio.gather(*tasks)
Il parametro max_concurrent è configurabile. Impostalo in base ai tuoi limiti di frequenza (lezione 7).
Scelta del valore corretto del semaforo
Calcola il valore ottimale partendo dai tuoi limiti di frequenza, ma non direttamente: devi considerare la durata della richiesta. Se il tuo piano tariffario consente 60 RPM e ogni richiesta richiede circa 10 secondi, un semaforo di valore 5 produce al massimo 5 richieste simultanee, ovvero circa 30 richieste al minuto, restando comodamente sotto il limite. Applica questo ragionamento (limite RPM × durata media ÷ 60) al tuo caso specifico. Questo spiega perché i modelli di ragionamento richiedono un semaforo con valore più basso: le loro richieste durano più a lungo, quindi a parità di concorrenza, il throughput al minuto diminuisce e aumenta il rischio di saturazione momentanea. In caso di dubbio, l’approccio empirico è il più sicuro: inizia con un valore basso, tra 3 e 5, osserva il tasso di errore 429 e aumenta gradualmente fino a trovare l’equilibrio tra throughput e stabilità.
Calcolo approssimativo
Richieste al minuto = semaforo * (60 / durata_media_secondi)
Esempio: semaforo=5, durata=10s → 5 * (60/10) = 30 RPM
Esempio: semaforo=10, durata=5s → 10 * (60/5) = 120 RPM
Errore comune: semaforo globale vs locale
# SBAGLIATO: nuovo semaforo a ogni chiamata
async def bad_request(request: str):
sem = Semaphore(5) # ogni chiamata crea il proprio semaforo
async with sem:
return await client.chat.completions.create(...)
# CORRETTO: semaforo condiviso tra tutte le chiamate
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Il semaforo deve essere condiviso tra tutte le coroutine. Se lo crei localmente all’interno di ogni funzione, ogni coroutine avrà il proprio semaforo e il limite non funzionerà.
Punti chiave
- Un semaforo limita il numero di richieste API simultanee per rispettare i limiti di frequenza
- Usa
async with semaphoreper proteggere le chiamate API - Inizia con un valore tra 3 e 5 e regolalo in base ai tuoi limiti RPM
- Il semaforo deve essere condiviso (globale o passato come parametro), mai creato localmente
- La formula
RPM = semaforo * (60 / durata_media)aiuta a dimensionare il valore