Asynkroninen arkkitehtuuri ja jonot
Tällä sivulla
Miksi et koskaan estä LLM-kutsua
Kielimallin API-kutsu kestää yhdestä kolmeenkymmeneen sekuntiin riippuen mallista ja pyynnön vaativuudesta. Kolmekymmentä sekuntia on ikuisuus palvelinprosessille: tänä aikana odottava säie ei tee mitään, mutta se vie silti paikan. Kerro tämä sadalla samanaikaisella pyynnöllä, ja sovelluksesi kaatuu ei siksi, että se laskisi liikaa, vaan siksi, että se odottaa liikaa.
Jonoon perustuva asynkroninen arkkitehtuuri ratkaisee kolme ongelmaa kerralla. Se vaimentaa liikennehuiput, koska jono kasvaa pyyntöjen hylkäämisen sijaan. Se keskittää uudelleenyrityslogiikan, koska epäonnistunut tehtävä palaa jonoon sen sijaan, että se katoaisi sen käynnistäneen HTTP-pyynnön mukana. Ja se irrottaa palvelusi toisistaan: pyyntöjä vastaanottavan komponentin ei tarvitse enää tietää, kuinka kauan tehtävän suorittava komponentti kestää.
Tuottaja / Kuluttaja -kuvio
Perusrakenne nojaa kahteen olioon. Tehtävä kuvaa, mitä on tehtävä ja nykyisen käsittelyn tilan; jono jakaa nämä tehtävät rinnakkain niitä kuluttavalle työntekijäpoolille. Tilan mallintaminen lueteltuna tyyppinä vapaamuotoisen merkkijonon sijaan välttää yleisimmän bugiluokan tämän tyyppisessä koodissa: kaksi ohjelman osaa kirjoittaa "terminee" ja "terminée".
import asyncio
from dataclasses import dataclass, field
from enum import Enum
class TaskStatus(Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
FAILED = "failed"
@dataclass
class Task:
id: str
prompt: str
model: str = "gpt-5.6-terra"
status: TaskStatus = TaskStatus.PENDING
result: str | None = None
attempts: int = 0
max_attempts: int = 3
class ProcessingQueue:
"""Asynkroninen jono LLM-kutsuille."""
def __init__(self, num_workers: int = 5):
self.queue: asyncio.Queue[Task] = asyncio.Queue()
self.results: dict[str, Task] = {}
self.num_workers = num_workers
async def add(self, task: Task) -> str:
"""Lisää tehtävän jonoon."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Työntekijä, joka käsittelee tehtäviä jonosta."""
import openai
client = openai.AsyncOpenAI()
while True:
task = await self.queue.get()
task.status = TaskStatus.IN_PROGRESS
task.attempts += 1
try:
response = await client.responses.create(
model=task.model,
input=task.prompt,
)
task.result = response.output_text
task.status = TaskStatus.COMPLETED
except Exception as e:
if task.attempts < task.max_attempts:
task.status = TaskStatus.PENDING
await self.queue.put(task)
else:
task.status = TaskStatus.FAILED
task.result = str(e)
finally:
self.queue.task_done()
async def start(self):
"""Käynnistää työntekijät."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Odottaa, kunnes kaikki tehtävät on käsitelty."""
await self.queue.join()
Tässä työntekijässä kaksi yksityiskohtaa ansaitsevat huomiosi, sillä ne esiintyvät jokaisessa todellisessa toteutuksessa. attempts-laskuri elää itse tehtävässä, ei työntekijässä, mikä mahdollistaa sen, että mikä tahansa muu työntekijä voi napata uudelleenjonotetun tehtävän menettämättä sen historiaa. task_done()-kutsu sijaitsee finally-lohkossa varmistaakseen, että jono ei jumitu ikuisesti, jos odottamaton poikkeus ohittaa except-lohkon: ilman sitä oireena on palautumaton join(), ja sen diagnosointi on tuskallista.
Kutsujan puolella käyttö on suoraviivaista: käynnistä työntekijät, laita tehtävät jonoon, odota, kerää tulokset ja pysäytä.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Lisää tehtävät
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Tiivistä tämä asiakirja: {doc}",
)
await queue.add(task)
# Odota valmistumista
await queue.wait_completion()
# Kerää tulokset
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Pysäytä työntekijät
for w in workers:
w.cancel()
Kiintiöiden kunnioittaminen niiden rikkomisen sijaan
OpenAI valvoo kahta samanaikaista rajaa: pyyntöjä minuutissa ja tokeneja minuutissa. Kymmenen työntekijän pooli, joka lähettää kaiken minkä ehtii, osuu jompaankumpaan, saa nopeusrajoitusvirheitä, yrittää uudelleen ja pahentaa ruuhkaa. On parempi hidastaa vapaaehtoisesti ylävirrassa kuin tulla torjutuksi alavirrassa.
Alla oleva rajoitin toteuttaa tokenämpärin liukuvan minuutin ikkunalla. Se ylläpitää kahta historiaa – viimeaikaisten pyyntöjen aikaleimoja ja aikaleima/token-pareja – puhdistaa ikkunan ulkopuolelle jääneet merkinnät ja odottaa sitten, jos jompikumpi raja ylittyisi. Asyncio-lukko on välttämätön: ilman sitä kymmenen työntekijää arvioisi saman tilanteen samanaikaisesti, ja kaikki kymmenen päättäisivät tilaa olevan vielä jäljellä.
import asyncio
import time
class RateLimiter:
"""Nopeusrajoitin, joka perustuu tokenämpäriin."""
def __init__(self, rpm: int = 500, tpm: int = 200_000):
self.rpm = rpm
self.tpm = tpm
self.recent_requests: list[float] = []
self.recent_tokens: list[tuple[float, int]] = []
self.lock = asyncio.Lock()
async def wait(self, estimated_tokens: int = 1000):
"""Odottaa tarvittaessa rajojen kunnioittamiseksi."""
async with self.lock:
now = time.time()
window = 60.0
# Puhdistaa ikkunan ulkopuolelle jääneet merkinnät
self.recent_requests = [
t for t in self.recent_requests
if now - t < window
]
self.recent_tokens = [
(t, n) for t, n in self.recent_tokens
if now - t < window
]
# Tarkista RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Tarkista TPM
tokens_used = sum(n for _, n in self.recent_tokens)
if tokens_used + estimated_tokens > self.tpm:
wait_time = self.recent_tokens[0][0] + window - now
await asyncio.sleep(wait_time)
self.recent_requests.append(time.time())
self.recent_tokens.append((time.time(), estimated_tokens))
Parametri estimated_tokens ansaitsee sanan: et tiedä todellista kustannusta ennen kuin vastaus saapuu, joten työskentelet arvion kanssa. Tee siitä mieluummin antelias kuin tarkka. Systemaattinen aliarviointi tarkoittaa suojauksen kytkemistä pois päältä juuri silloin, kun sitä tarvitsisi.
Ohjauksen palauttaminen välittömästi
Useita minuutteja kestävälle käsittelylle HTTP-asiakkaan odottaminen ei ole enää viable: välityspalvelimet, selaimet ja kuormantasaimien aikakatkaisut ehtivät laukaista ennen kuin olet valmis. Webhook-kuvio kääntää vastuun. Päätepisteesi hyväksyy pyynnön, palauttaa välittömästi tehtävätunnuksen ja ilmoittaa kutsujalle, kun tulos on olemassa, ilman tarvetta jaksolliseen kyselyyn.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Käynnistää tausta-analyysin ja ilmoittaa webhookin kautta."""
task_id = generate_id()
background_tasks.add_task(
run_analysis,
task_id=task_id,
document=request["document"],
webhook_url=request.get("webhook_url"),
)
return {"task_id": task_id, "status": "in_progress"}
async def run_analysis(
task_id: str,
document: str,
webhook_url: str | None,
):
"""Suorittaa analyysin ja lähettää tuloksen webhookin kautta."""
import httpx
result = await call_llm(document)
if webhook_url:
async with httpx.AsyncClient() as http:
await http.post(webhook_url, json={
"task_id": task_id,
"status": "completed",
"result": result,
})
Tallenna aina palautettu tunnus ja siihen liittyvä tila kestävään tallennustilaan. Webhook voi kadota, ja kutsujan on pystyttävä hakemaan tulos itse.
Keskeiset asiat
- Käytä asynkronisia jonoja irrottaaksesi vastaanoton käsittelystä
- Toteuta nopeusrajoitin OpenAI-kiintiöiden kunnioittamiseksi
- Käsittele uudelleenyritykset eksponentiaalisella viiveellä työntekijöissäsi
- Suosi pitkissä tehtävissä webhook-kuviota kyselyn sijaan