Przejdź do głównej treści
Polski— Wybierz język
Menu

Używanie semaforów do ograniczania równoległych żądań

Lekcja 4 z 12 Zaktualizowano 30 lipca 2026 Zaawansowany
Na tej stronie
  1. Problem niekontrolowanej współbieżności
  2. Jak działają semafory
  3. Pełny wzorzec z użyciem OpenAI SDK
  4. Wybór odpowiedniej wartości semafora
  5. Częsty błąd: semafor globalny kontra lokalny
  6. Kluczowe wnioski

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.

5
Zalecana liczba żądań równoległych
429
Błąd limitu częstotliwości HTTP
RPM
Żądania na minutę
TPM
Tokeny na minutę

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ść