Semaforien käyttö samanaikaisten pyyntöjen rajoittamiseen
Tällä sivulla
Hallitsemattoman samanaikaisuuden ongelma
Kaikkien pyyntöjen lähettäminen rinnakkain ilman rajoituksia on yleinen virhe. Jos sinulla on 200 kysymystä käsiteltävänä ja lähetät ne kaikki yhtä aikaa, osut rajapinnan nopeusrajoihin, saat HTTP 429 -virheitä ja API-avaimesi saatetaan estää väliaikaisesti.
Semafori on vakiomenetelmä samanaikaisten pyyntöjen määrän hallintaan. Se on laskuri, joka sallii ennalta määrätyn määrän korutiineja suoritettavan rinnakkain.
Miten semaforit toimivat
asyncio.Semaphore toimii lukittuna laskurina. Kun korutiini saapuu async with semaphore -lohkoon, laskuri vähenee. Kun se poistuu lohkosta, laskuri kasvaa. Jos laskuri saavuttaa nollan, myöhemmät korutiinit odottavat, kunnes vapautuu paikka.
import asyncio
from asyncio import Semaphore
semaphore = Semaphore(5) # enintään 5 samanaikaista pyyntöä
async def process_request(request: str):
async with semaphore:
# Tämä osio on rajoitettu 5:een rinnakkaiseen suoritukseen
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
max_tokens=100
)
chat.append(user(request))
return await chat.sample()
Tässä esimerkissä, vaikka käynnistäisit 100 korutiinia asyncio.gather-funktiolla, vain 5 niistä suoritetaan samanaikaisesti. Loput 95 odottavat vuoroaan.
Täydellinen malli OpenAI SDK:n kanssa
Tässä on sama malli käyttäen AsyncOpenAI:ta, jota usein suositaan yhteensopivuuden vuoksi:
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)
Parametri max_concurrent on muokattavissa. Aseta se nopeusrajoitustesi perusteella (katso oppitunti 7).
Oikean semaforiarvon valinta
Laske optimaalinen arvo nopeusrajoitustesi perusteella, mutta älä suoraan: sinun tulee ottaa huomioon pyynnön kesto. Jos tasosi sallii 60 RPM ja jokainen pyyntö kestää noin 10 sekuntia, semaforin arvo 5 tuottaa enintään 5 samanaikaista pyyntöä, eli noin 30 pyyntöä minuutissa – mikä on turvallisesti rajan alapuolella. Sovella tätä päättelyä (RPM-raja × keskimääräinen kesto ÷ 60) omaan tilanteeseesi. Tämä selittää, miksi päättelymallit vaativat pienempää semaforiarvoa: niiden pyynnöt kestävät kauemmin, joten samalla samanaikaisuudella läpimeno minuutissa laskee ja hetkellisen ylikuormituksen riski kasvaa. Jos olet epävarma, empiirinen lähestymistapa on turvallisin: aloita pienellä arvolla, 3–5 välillä, tarkkaile 429-virheiden määrää ja kasvata arvoa vähitellen, kunnes löydät tasapainon läpimenon ja vakauden välillä.
Likimääräinen laskenta
Pyyntöjä minuutissa = semafori * (60 / keskimääräinen_kesto_sekunteina)
Esimerkki: semafori=5, kesto=10s → 5 * (60/10) = 30 RPM
Esimerkki: semafori=10, kesto=5s → 10 * (60/5) = 120 RPM
Yleinen virhe: globaali vs. paikallinen semafori
# HUONO: uusi semafori jokaisella kutsulla
async def bad_request(request: str):
sem = Semaphore(5) # jokainen kutsu luo oman semaforinsa
async with sem:
return await client.chat.completions.create(...)
# HYVÄ: semafori jaettu kaikkien kutsujen kesken
sem = Semaphore(5)
async def good_request(request: str):
async with sem:
return await client.chat.completions.create(...)
Semaforin on oltava jaettu kaikkien korutiinien kesken. Jos luot sen paikallisesti jokaisen funktion sisällä, jokaisella korutiinilla on oma semaforinsa, eikä rajoitus toimi.
Keskeiset asiat
- Semafori rajoittaa samanaikaisten API-pyyntöjen määrää nopeusrajoitusten noudattamiseksi
- Käytä
async with semaphore-rakennetta suojataksesi API-kutsut - Aloita arvolla 3–5 ja säädä sitä RPM-rajoitustesi perusteella
- Semaforin on oltava jaettu (globaali tai parametrina välitetty), sitä ei saa koskaan luoda paikallisesti
- Kaava
RPM = semafori * (60 / keskimääräinen_kesto)auttaa määrittämään oikean arvon