Używanie semaforów do ograniczania równoległych żądań
Na tej stronie
Problem niekontrolowanej współbieżności
Wysyłanie wszystkich żądań równolegle bez żadnych ograniczeń to częsty błąd. Jeśli masz do przetworzenia 200 pytań i uruchomisz je wszystkie jednocześnie, przekroczysz limity częstotliwości wywołań API (rate limits), otrzymasz błędy HTTP 429, a Twój klucz API może zostać tymczasowo zablokowany.
Semafor to standardowe rozwiązanie pozwalające kontrolować liczbę równoległych żądań. Działa jak licznik, który pozwala na uruchomienie maksymalnie określonej liczby korutyn jednocześnie.
Jak działają semafory
asyncio.Semaphore działa jak blokada licznika. Gdy korutyna wchodzi w blok async with semaphore, licznik maleje. Gdy z niego wychodzi, licznik rośnie. Jeśli licznik osiągnie zero, kolejne korutyny czekają, aż zwolni się miejsce.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # maksymalnie 5 jednoczesnych żądań
async def process_request(request: str):
async with semaphore:
# Ta sekcja jest ograniczona do 5 równoległych wykonań
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
W tym przykładzie, nawet jeśli uruchomisz 100 korutyn za pomocą asyncio.gather, tylko 5 z nich będzie działać jednocześnie. Pozostałe 95 poczeka na swoją kolej.
Pełny wzorzec z użyciem OpenAI SDK
Oto ten sam wzorzec z wykorzystaniem AsyncOpenAI, które jest często preferowane ze względu na kompatybilność:
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 jest konfigurowalny. Ustaw go w oparciu o swoje limity częstotliwości wywołań (lekcja 7).
Wybór odpowiedniej wartości semafora
Oblicz optymalną wartość na podstawie swoich limitów, ale nie rób tego bezpośrednio: musisz uwzględnić czas trwania żądania. Jeśli Twój plan pozwala na 60 RPM, a każde żądanie trwa około 10 sekund, semafor o wartości 5 pozwoli na maksymalnie 5 jednoczesnych żądań, co daje około 30 żądań na minutę – bezpiecznie poniżej limitu. Zastosuj to rozumowanie (limit RPM × średni czas trwania ÷ 60) do swojego przypadku. Wyjaśnia to, dlaczego modele rozumujące wymagają niższej wartości semafora: ich żądania trwają dłużej, więc przy tej samej współbieżności przepustowość na minutę spada, a ryzyko chwilowego przeciążenia rośnie. W razie wątpliwości najbezpieczniejsze jest podejście empiryczne: zacznij od niskiej wartości, między 3 a 5, obserwuj wskaźnik błędów 429 i stopniowo zwiększaj liczbę, aż znajdziesz balans między przepustowością a stabilnością.
Przybliżone obliczenia
Żądania na minutę = semafor * (60 / średni_czas_trwania_w_sekundach)
Przykład: semafor=5, czas_trwania=10s → 5 * (60/10) = 30 RPM
Przykład: semafor=10, czas_trwania=5s → 10 * (60/5) = 120 RPM
Częsty błąd: semafor globalny kontra lokalny
# ŹLE: nowy semafor przy każdym wywołaniu
async def bad_request(request: str):
sem = Semaphore(5) # każde wywołanie tworzy własny semafor
async with sem:
return await client.chat.completions.create(...)
# DOBRZE: semafor współdzielony między wszystkimi wywołaniami
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Semafor musi być współdzielony przez wszystkie korutyny. Jeśli utworzysz go lokalnie wewnątrz każdej funkcji, każda korutyna będzie miała własny semafor i limit nie zadziała.
Kluczowe wnioski
- Semafor ogranicza liczbę jednoczesnych żądań API, aby przestrzegać limitów częstotliwości wywołań
- Używaj
async with semaphore, aby chronić wywołania API - Zacznij od wartości od 3 do 5 i dostosuj ją w oparciu o swoje limity RPM
- Semafor musi być współdzielony (globalny lub przekazywany jako parametr), nigdy nie twórz go lokalnie
- Wzór
RPM = semafor * (60 / średni_czas_trwania)pomaga dobrać odpowiednią wartość