Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Semaforide kasutamine samaaegsete päringute piiramiseks

Õppetund 4 / 12 Värskendatud 30. juuli 2026 Edasijõudnutele
Sellel lehel
  1. Kontrollimatu samaaegsuse probleem
  2. Kuidas semafid töötavad
  3. Täielik muster OpenAI SDK-ga
  4. Õige semafi väärtuse valimine
  5. Levinud viga: globaalne vs lokaalne semaf
  6. Peamised punktid

Kontrollimatu samaaegsuse probleem

Kõigi päringute paralleelselt ja ilma piiranguteta käivitamine on levinud viga. Kui sul on töödelda 200 küsimust ja käivitad need kõik samaaegselt, ületad API kiiruse piirangud, saad HTTP 429 veateateid ja võid isegi ajutiselt kaotada oma API võtme kasutusõiguse.

Semaf on standardlahendus samaaegsete päringute arvu kontrollimiseks. See on loendur, mis lubab maksimaalselt teatud arvul korutiinidel paralleelselt töötada.

5
Soovitatav paralleelsete päringute arv
429
HTTP kiiruse piirangu viga
RPM
Päringuid minutis
TPM
Tokeneid minutis

Kuidas semafid töötavad

asyncio.Semaphore toimib nagu loenduriga lukk. Kui korutiin siseneb plokki async with semaphore, väheneb loendur. Väljumisel loendur suureneb. Kui loendur jõuab nullini, ootavad järgmised korutiinid, kuni vaba koht tekib.

import asyncio
from asyncio import Semaphore

semaphore = Semaphore(5)  # maksimaalselt 5 samaaegset päringut

async def process_request(request: str):
    async with semaphore:
        # See lõik on piiratud 5 paralleelse täitmisega
        chat = client.chat.create(
            model="grok-4.20-0309-reasoning",
            max_tokens=100
        )
        chat.append(user(request))
        return await chat.sample()

Selles näites, isegi kui käivitad asyncio.gather abil 100 korutiini, töötab samaaegselt ainult 5. Ülejäänud 95 ootavad oma korda.

Täielik muster OpenAI SDK-ga

Siin on sama muster, kasutades AsyncOpenAI-d, mida eelistatakse sageli ühilduvuse tõttu:

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)

Parameeter max_concurrent on konfigureeritav. Määra see vastavalt oma kiiruse piirangutele (tund 7).

Õige semafi väärtuse valimine

Arvuta optimaalne väärtus oma kiiruse piirangute põhjal, kuid mitte otse: võta arvesse päringu kestust. Kui sinu tase lubab 60 RPM ja iga päring võtab umbes 10 sekundit, annab semaf väärtusega 5 maksimaalselt 5 samaaegset päringut ehk umbes 30 päringut minutis – jäädes mugavalt alla piiri. Rakenda seda arutluskäiku (RPM piirang × keskmine kestus ÷ 60) oma juhtumile. See selgitab, miks arutlusmudelid nõuavad väiksemat semafi: nende päringud kestavad kauem, nii et sama samaaegsuse korral langeb läbilaskevõime minutis ja hetkelise ülekoormuse oht kasvab. Kahtluse korral on empiiriline lähenemine ohutum: alusta madalalt, vahemikus 3 kuni 5, jälgi 429 vigade määra ja suurenda järk-järgult, kuni leiad tasakaalu läbilaskevõime ja stabiilsuse vahel.

Ligikaudne arvutus

Päringuid minutis = semaf * (60 / keskmine_kestus_sekundites)

Näide: semaf=5, kestus=10s → 5 * (60/10) = 30 RPM
Näide: semaf=10, kestus=5s → 10 * (60/5) = 120 RPM

Levinud viga: globaalne vs lokaalne semaf

# HALB: uus semaf iga väljakutse korral
async def bad_request(request: str):
    sem = Semaphore(5)  # iga väljakutse loob oma semafi
    async with sem:
        return await client.chat.completions.create(...)

# HEA: semaf on jagatud kõigi väljakutsete vahel
sem = Semaphore(5)

async def good_request(request: str):
    async with sem:
        return await client.chat.completions.create(...)

Semaf peab olema jagatud kõigi korutiinide vahel. Kui lood selle iga funktsiooni sees lokaalselt, on igal korutiinil oma semaf ja piirang ei toimi.

Peamised punktid

  • Semaf piirab samaaegsete API päringute arvu, et austada kiiruse piiranguid
  • Kasuta API kõnede kaitsmiseks konstruktsiooni async with semaphore
  • Alusta väärtusega 3 kuni 5 ja kohanda seda vastavalt oma RPM piirangutele
  • Semaf peab olema jagatud (globaalne või parameetrina edastatud), mitte kunagi lokaalselt loodud
  • Valem RPM = semaf * (60 / keskmine_kestus) aitab väärtust sobivaks määrata