Semafory ribojimui lygiagrečių užklausų
Šiame puslapyje
Nekontroliuojamo lygiagretumo problema
Visų užklausų siuntimas lygiagrečiai be jokių apribojimų yra dažna klaida. Jei turi 200 klausimų apdoroti ir paleidi juos visus vienu metu, pasieksi API dažnio ribas, gausi HTTP 429 klaidas ir galbūt laikinai bus užblokuotas tavo API raktas.
Semafaras yra standartinis sprendimas valdyti vienu metu vykdomų užklausų skaičių. Tai skaitiklis, leidžiantis vienu metu veikti tik maksimaliam korutinų skaičiui.
Kaip veikia semafarai
asyncio.Semaphore veikia kaip skaitiklio užraktas. Kai korutinė įeina į async with semaphore bloką, skaitiklis sumažėja. Jai išėjus, skaitiklis padidėja. Jei skaitiklis pasiekia nulį, vėlesnės korutinės laukia, kol atsiras laisva vieta.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # maksimaliai 5 vienu metu vykdomos užklausos
async def process_request(request: str):
async with semaphore:
# Ši dalis apribota iki 5 lygiagrečių vykdymų
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
Šiame pavyzdyje, net jei paleisi 100 korutinių naudodamas asyncio.gather, vienu metu veiks tik 5. Likusios 95 lauks savo eilės.
Pilnas šablonas naudojant OpenAI SDK
Štai tas pats šablonas naudojant AsyncOpenAI, kuris dažnai yra pageidaujamas dėl suderinamumo:
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)
Parametras max_concurrent yra konfigūruojamas. Nustatyk jį pagal savo dažnio ribas (7 pamoka).
Tinkamos semafaro reikšmės pasirinkimas
Apskaičiuok optimalią reikšmę iš savo dažnio ribų, bet ne tiesiogiai: turi atsižvelgti į užklausos trukmę. Jei tavo lygmuo leidžia 60 RPM ir kiekviena užklausa trunka apie 10 sekundžių, 5 semafaras sukurs daugiausia 5 vienu metu vykdomas užklausas, arba apie 30 užklausų per minutę – tai saugiai žemiau ribos. Taikyk šią logiką (RPM riba × vidutinė trukmė ÷ 60) savo atveju. Tai paaiškina, kodėl samprotavimo modeliams reikia mažesnio semafaro: jų užklausos trunka ilgiau, todėl esant tokiam pačiam lygiagretumui, pralaidumas per minutę mažėja ir didėja momentinio perkrovos rizika. Kilus abejonių, empirinis požiūris yra saugiausias: pradėk nuo mažos reikšmės, tarp 3 ir 5, stebėk 429 klaidų dažnį ir palaipsniui didink, kol rasi pusiausvyrą tarp pralaidumo ir stabilumo.
Apytikslis skaičiavimas
Užklausų per minutę = semafaras * (60 / vidutinė_trukmė_sekundėmis)
Pavyzdys: semafaras=5, trukmė=10s → 5 * (60/10) = 30 RPM
Pavyzdys: semafaras=10, trukmė=5s → 10 * (60/5) = 120 RPM
Dažna klaida: globalus prieš vietinį semafarą
# BLOGAI: naujas semafaras kiekvienam kvietimui
async def bad_request(request: str):
sem = Semaphore(5) # kiekvienas kvietimas sukuria savo semafarą
async with sem:
return await client.chat.completions.create(...)
# GERAI: semafaras bendras visiems kvietimams
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Semafaras turi būti bendras visoms korutinėms. Jei jį sukuri lokaliai kiekvienoje funkcijoje, kiekviena korutinė turės savo semafarą ir apribojimas neveiks.
Svarbiausi punktai
- Semafaras riboja vienu metu vykdomų API užklausų skaičių, kad būtų laikomasi dažnio ribų
- Naudok
async with semaphoreAPI kvietimams apsaugoti - Pradėk nuo 3–5 reikšmės ir koreguok pagal savo RPM ribas
- Semafaras turi būti bendras (globalus arba perduodamas kaip parametras), niekada nekuriamas lokaliai
- Formulė
RPM = semafaras * (60 / vidutinė_trukmė)padeda parinkti tinkamą reikšmę