Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Utilizzo dei semafori per limitare le richieste concorrenti

Lezione 4 di 12 Aggiornata il 30 luglio 2026 Avanzato
In questa pagina
  1. Il problema della concorrenza incontrollata
  2. Come funzionano i semafori
  3. Pattern completo con l’SDK OpenAI
  4. Scelta del valore corretto del semaforo
  5. Errore comune: semaforo globale vs locale
  6. Punti chiave

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.

5
Richieste parallele consigliate
429
Errore di limite di frequenza HTTP
RPM
Richieste al minuto
TPM
Token al minuto

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 semaphore per 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