Semaphore nutzen, um gleichzeitige Anfragen zu begrenzen
Auf dieser Seite
Das Problem unkontrollierter Parallelität
Es ist ein häufiger Fehler, alle Anfragen ohne Begrenzung parallel zu starten. Wenn Sie beispielsweise 200 Fragen verarbeiten müssen und diese alle gleichzeitig absenden, stoßen Sie an die API-Rate-Limits, erhalten HTTP 429-Fehler und riskieren, dass Ihr API-Schlüssel vorübergehend gesperrt wird.
Ein Semaphore ist die Standardlösung zur Kontrolle der Anzahl gleichzeitiger Anfragen. Es handelt sich um einen Zähler, der die maximale Anzahl an Koroutinen erlaubt, die parallel ausgeführt werden können.
Funktionsweise von Semaphoren
asyncio.Semaphore fungiert als Zähler-Sperre. Wenn eine Koroutine den Bereich async with semaphore betritt, wird der Zähler verringert. Beim Verlassen des Bereichs wird der Zähler wieder erhöht. Wenn der Zähler bei Null liegt, warten nachfolgende Koroutinen, bis sich ein Slot freigibt.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # maximal 5 gleichzeitige Anfragen
async def process_request(request: str):
async with semaphore:
# Dieser Abschnitt ist auf maximal 5 parallele Ausführungen begrenzt
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
In diesem Beispiel werden selbst wenn Sie 100 Koroutinen mit asyncio.gather starten, nur 5 gleichzeitig ausgeführt. Die anderen 95 warten an der Reihe.
Vollständiges Muster mit dem OpenAI SDK
Hier ist das gleiche Muster unter Verwendung von AsyncOpenAI, was aufgrund der Kompatibilität oft bevorzugt wird:
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)
Der Parameter max_concurrent ist konfigurierbar. Stellen Sie ihn basierend auf Ihren Rate-Limits ein (siehe Lektion 7).
Die richtige Semaphore-Wert wählen
Berechnen Sie den optimalen Wert aus Ihren Rate-Limits, aber nicht direkt: Sie müssen die Dauer der Anfragen berücksichtigen. Wenn Ihr Tarif 60 RPM erlaubt und jede Anfrage etwa 10 Sekunden dauert, erzeugt ein Semaphore mit dem Wert 5 maximal 5 gleichzeitige Anfragen, also etwa 30 Anfragen pro Minute – das liegt komfortabel unter der Grenze. Wenden Sie diese Logik (RPM-Limit × durchschnittliche Dauer ÷ 60) auf Ihren eigenen Fall an. Dies erklärt, warum für Reasoning-Modelle ein niedrigerer Semaphore-Wert erforderlich ist: Ihre Anfragen dauern länger, sodass bei gleicher Parallelität die Durchsatzrate pro Minute sinkt und das Risiko einer momentanen Sättigung steigt. Wenn Sie unsicher sind, ist der empirische Ansatz am sichersten: Beginnen Sie mit einem niedrigen Wert zwischen 3 und 5, beobachten Sie die Rate der 429-Fehler und erhöhen Sie den Wert schrittweise, bis Sie das Gleichgewicht zwischen Durchsatz und Stabilität finden.
Näherungsweise Berechnung
Anfragen pro Minute = Semaphore * (60 / durchschnittliche_Dauer_in_Sekunden)
Beispiel: Semaphore=5, Dauer=10s → 5 * (60/10) = 30 RPM
Beispiel: Semaphore=10, Dauer=5s → 10 * (60/5) = 120 RPM
Häufiger Fehler: Globales versus lokales Semaphore
# SCHLECHT: Neues Semaphore bei jedem Aufruf
async def bad_request(request: str):
sem = Semaphore(5) # Jeder Aufruf erstellt sein eigenes Semaphore
async with sem:
return await client.chat.completions.create(...)
# GUT: Semaphore wird über alle Aufrufe geteilt
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Das Semaphore muss über alle Koroutinen hinweg geteilt werden. Wenn Sie es lokal innerhalb jeder Funktion erstellen, hat jede Koroutine ihr eigenes Semaphore und die Begrenzung funktioniert nicht.
Kernaussagen
- Ein Semaphore begrenzt die Anzahl gleichzeitiger API-Anfragen, um Rate-Limits einzuhalten.
- Verwenden Sie
async with semaphore, um API-Aufrufe zu schützen. - Beginnen Sie mit einem Wert zwischen 3 und 5 und passen Sie ihn basierend auf Ihren RPM-Limits an.
- Das Semaphore muss geteilt werden (global oder als Parameter übergeben), niemals lokal erstellt werden.
- Die Formel
RPM = Semaphore * (60 / durchschnittliche_Dauer)hilft bei der Dimensionierung des Werts.