Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Semaphore nutzen, um gleichzeitige Anfragen zu begrenzen

Lektion 4 von 12 Aktualisiert am 30. Juli 2026 Fortgeschritten
Auf dieser Seite
  1. Das Problem unkontrollierter Parallelität
  2. Funktionsweise von Semaphoren
  3. Vollständiges Muster mit dem OpenAI SDK
  4. Die richtige Semaphore-Wert wählen
  5. Häufiger Fehler: Globales versus lokales Semaphore
  6. Kernaussagen

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.

5
Empfohlene parallele Anfragen
429
HTTP-Rate-Limit-Fehler
RPM
Anfragen pro Minute
TPM
Tokens pro Minute

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.