Asünkroonne arhitektuur ja järjekorrad
Sellel lehel
Miks sa mitte kunagi LLM-i päringut ei blokeeri
Keelemudeli API-päring võtab aega ühest kuni kolmekümne sekundini, sõltuvalt mudelist ja päringu keerukusest. Kolmkümmend sekundit on serveriprotsessi jaoks igavik: sel ajal ootav lõng ei tee midagi, kuid hõivab siiski ühe pesa. Korruta see sajaks samaaegseks päringuks ja sinu rakendus kukub kokku mitte sellepärast, et see arvutaks liiga palju, vaid sellepärast, et see ootab liiga kaua.
Järjekorral põhinev asünkroonne arhitektuur lahendab korraga kolm probleemi. See neelab liikluse tipphetked, kuna järjekord kasvab päringute tagasilükkamise asemel. See tsentraliseerib uuesti proovimise loogika, sest ebaõnnestunud ülesanne naaseb järjekorda, selleks et kaduda koos seda käivitanud HTTP-päringuga. Ja see eraldab sinu teenused: päringuid vastu võttev komponent ei pea enam teadma, kui kaua täitval komponendil nende töötlemine aega võtab.
Tootja / Tarbija muster
Põhistruktuur tugineb kahele objektile. Ülesanne kirjeldab, mida tuleb teha, ja praegust töötlemise olekut; järjekord jaotab need ülesanded töötajate kogumile, mis tarbivad neid paralleelselt. Oleku modelleerimine loeteluna vabas vormis stringi asemel väldib sellist tüüpi koodi kõige levinumat veaklassi: programmi kaks osa kirjutavad "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:
"""Asünkroonne järjekord LLM-i päringute jaoks."""
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:
"""Lisab ülesande järjekorda."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Töötaja, mis töötleb järjekorras olevaid ülesandeid."""
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äivitab töötajad."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Ootab, kuni kõik ülesanded on töödeldud."""
await self.queue.join()
Selles töötajas on kaks detaili, mis väärivad sinu tähelepanu, kuna need esinevad igas reaalses rakenduses. Loendur attempts asub ülesandel endal, mitte töötajal, võimaldades mis tahes muul töötajal uuesti järjekorda pandud ülesande vastu võtta ilma selle ajalugu kaotamata. Väljakutse task_done() asub plokis finally, et garanteerida, et järjekord ei jääks lõputuks seisma, kui ootamatu erind möödub plokist except: ilma selleta on sümptomiks join(), mis kunagi ei tagastu, ja seda on valus diagnoosida.
Kutsuja poolel on kasutamine sirgjooneline: käivita töötajad, lisa ülesanded järjekorda, oota, kogu tulemused ja peata töö.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Lisa ülesanded
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Võta see dokument kokku: {doc}",
)
await queue.add(task)
# Oota lõpetamist
await queue.wait_completion()
# Kogu tulemused
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Peata töötajad
for w in workers:
w.cancel()
Kvootide austamine nende rikkumise asemel
OpenAI rakendab kahte samaaegset piirangut: päringuid minutis ja tokeneid minutis. Kümnest töötajast koosnev kogum, mis saadab kõik, mida suudab, põrkub kokku kas ühe või teisega, saab kiiruse piiramise veateateid, proovib uuesti ja süvendab ummistust. Parem on vabatahtlikult ülesvoolu aeglustada, kui allavoolu tagasi lükatud saada.
Allpool olev piiraja rakendab tokenite ämbrit libiseva üheminutilise akna üle. See haldab kahte ajalugu – hiljutiste päringute ajatempleid ja ajatempli/tokenite paare – puhastab aknast välja langenud kirjed ja ootab seejärel, kui kumbki limiit ületataks. Asyncio lukk on hädavajalik: ilma selleta hindaksid kümme töötajat sama olukorda samaaegselt ja kõik kümme otsustaksid, et ruumi on veel.
import asyncio
import time
class RateLimiter:
"""Tokenite ämbril põhinev kiiruse piiraja."""
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):
"""Ootab vajadusel, et austada piiranguid."""
async with self.lock:
now = time.time()
window = 60.0
# Puhasta aknast väljas olevad kirjed
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
]
# Kontrolli RPM-i
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Kontrolli TPM-i
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))
Parameeter estimated_tokens väärib märkust: sa ei tea tegelikku kulu enne, kui vastus saabub, seega töötad hinnanguga. Tee see heldeks, mitte täpseks. Süstemaatiline alahindamine võrdub kaitse deaktiviseerimisega täpselt siis, kui see oleks kasulik.
Juhtimise viivitamatu tagastamine
Mitu minutit kestva töötlemise puhul ei ole HTTP-kliendi ootamine enam elujõuline: proksi, brauseri ja koormusjaoturi ajalõpud jõuavad jõuda enne, kui sa lõpetad. Webhook’i muster pöörab vastutuse ümber. Sinu lõpp-punkt võtab päringu vastu, tagastab viivitamata ülesande ID ja teatab kutsujale, kui tulemus on olemas, ilma perioodilist pärimist nõudmata.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Käivitab taustal analüüsi ja teatab webhook'i kaudu."""
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,
):
"""Käivitab analüüsi ja saadab tulemuse webhook'i kaudu."""
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,
})
Salvesta alati tagastatud ID ja sellega seotud olek kusagile püsivasse salvestisse. Webhook võib kaduda ja kutsuja peab säilitama võime tulemus ise hankida.
Peamised punktid
- Kasuta asünkroonseid järjekordi sisendi ja töötlemise eraldamiseks
- Rakenda kiiruse piiraja OpenAI kvootide austamiseks
- Käitle uuesti proovimisi eksponentsiaalse tagasiminekuga oma töötajates
- Pikaajaliste ülesannete puhul eelista webhook’i mustrit pärimisele