Omezení souběžných požadavků pomocí semaforů
Na této stránce
Problém nekontrolované souběžnosti
Spouštění všech požadavků paralelně bez omezení je častá chyba. Pokud máš zpracovat 200 dotazů a spustíš je všechny najednou, narazíš na limity rychlosti API, obdržíš chyby HTTP 429 a tvůj API klíč může být dočasně zablokován.
Semafor je standardním řešením pro řízení počtu souběžných požadavků. Funguje jako čítač, který umožňuje běžet paralelně pouze maximálnímu počtu korutin.
Jak fungují semafory
asyncio.Semaphore funguje jako čítač se zámkem. Když korutina vstoupí do bloku async with semaphore, čítač se sníží. Když z něj vyjde, čítač se zvýší. Pokud čítač klesne na nulu, další korutiny čekají, dokud se neuvolní místo.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # maximálně 5 souběžných požadavků
async def process_request(request: str):
async with semaphore:
# Tato sekce je omezena na 5 paralelních spuštění
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
V tomto příkladu, i když spustíš 100 korutin pomocí asyncio.gather, najednou poběží pouze 5. Zbylých 95 bude čekat ve frontě.
Kompletní vzor s OpenAI SDK
Zde je stejný vzor použitý s AsyncOpenAI, což je často preferováno kvůli kompatibilitě:
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)
Parametr max_concurrent je konfigurovatelný. Nastav jej na základě svých limitů rychlosti (lekce 7).
Volba správné hodnoty semaforu
Optimální hodnotu vypočítej ze svých limitů rychlosti, ale ne přímo: musíš zohlednit dobu trvání požadavku. Pokud tvůj tarif umožňuje 60 RPM a každý požadavek trvá přibližně 10 sekund, semafor s hodnotou 5 vytvoří maximálně 5 souběžných požadavků, což je asi 30 požadavků za minutu – bezpečně pod limitem. Aplikuj tuto úvahu (limit RPM × průměrná doba trvání ÷ 60) na svůj případ. To vysvětluje, proč modely pro logické uvažování vyžadují nižší hodnotu semaforu: jejich požadavky trvají déle, takže při stejné souběžnosti klesá propustnost za minutu a roste riziko okamžitého přetížení. Pokud si nejsi jistý, nejbezpečnější je empirický přístup: začni nízko, mezi 3 a 5, sleduj míru chyb 429 a postupně zvyšuj hodnotu, dokud nenajdeš rovnováhu mezi propustností a stabilitou.
Přibližný výpočet
Požadavků za minutu = semafor * (60 / průměrná_doba_trvání_v_sekundách)
Příklad: semafor=5, doba_trvání=10s → 5 * (60/10) = 30 RPM
Příklad: semafor=10, doba_trvání=5s → 10 * (60/5) = 120 RPM
Častá chyba: globální versus lokální semafor
# ŠPATNĚ: nový semafor při každém volání
async def bad_request(request: str):
sem = Semaphore(5) # každé volání vytvoří vlastní semafor
async with sem:
return await client.chat.completions.create(...)
# DOBŘE: semafor sdílený mezi všemi voláními
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Semafor musí být sdílen mezi všemi korutinami. Pokud jej vytvoříš lokálně uvnitř každé funkce, každá korutina bude mít vlastní semafor a omezení nebude fungovat.
Klíčové poznatky
- Semafor omezuje počet souběžných požadavků na API, aby byly dodrženy limity rychlosti
- K ochraně volání API použij
async with semaphore - Začni s hodnotou 3 až 5 a upravuj ji na základě svých limitů RPM
- Semafor musí být sdílený (globální nebo předaný jako parametr), nikdy jej nevytvářej lokálně
- Vzorec
RPM = semafor * (60 / průměrná_doba_trvání)pomáhá určit správnou velikost