Asynchrónna architektúra a fronty
Na tejto strane
Prečo nikdy neblokuješ volanie LLM
Volanie API jazykového modelu trvá medzi jednou a tridsiatimi sekundami, v závislosti od modelu a zložitosti požiadavky. Tridsať sekúnd je pre serverový proces večnosť: počas tohto času čakajúce vlákno nič nerobí, no stále obsadzuje slot. Vynásob to stovkou simultánnych požiadaviek a tvoja aplikácia spadne nie preto, že by príliš počítala, ale preto, že príliš čaká.
Asynchrónna architektúra založená na fronte rieši naraz tri problémy. Absorbuje špičky v premávke, keďže fronta rastie namiesto odmietania požiadaviek. Centralizuje logiku opakovaných pokusov, pretože neúspešná úloha sa vráti do fronty namiesto toho, aby zmizla spolu s HTTP požiadavkou, ktorá ju spustila. A oddeľuje tvoje služby: komponent prijímajúci požiadavky už nemusí vedieť, ako dlho trvá vykonávajúcemu komponentu ich spracovanie.
Vzorec Producent / Konzument
Základná štruktúra sa spolieha na dva objekty. Úloha opisuje, čo treba urobiť, a aktuálny stav spracovania; fronta distribuuje tieto úlohy do poolu workerov, ktorí ich spracúvajú paralelne. Modelovanie stavu ako enumerácie namiesto voľného reťazca predchádza najčastejšej triede chýb v tomto type kódu: dve časti programu zapisujúce "terminee" a "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:
"""Asynchrónna fronta pre volania LLM."""
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:
"""Pridá úlohu do fronty."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Worker spracúvajúci úlohy z fronty."""
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):
"""Spustí workerov."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Čaká, kým sa nespracujú všetky úlohy."""
await self.queue.join()
Dva detaily v tomto workerovi si zaslúžia tvoju pozornosť, pretože sa objavujú v každej reálnej implementácii. Počítadlo attempts žije priamo v úlohe, nie vo workerovi, čo umožňuje ktorejkoľvek inej inštancii workeru prevziať znovu zaradenú úlohu bez straty jej histórie. Volanie task_done() sa nachádza v bloku finally, aby sa zaručilo, že fronta nikdy nezostane visieť na neurčito, ak neočakávaná výnimka obíde blok except: bez neho je príznakom join(), ktorý sa nikdy nevráti, a jeho diagnostika je bolestivá.
Na strane volajúceho je použitie priamočiare: spusti workerov, enqueue úloh, čakaj, zozbieraj výsledky a zastav.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Pridanie úloh
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Zhrň tento dokument: {doc}",
)
await queue.add(task)
# Čakanie na dokončenie
await queue.wait_completion()
# Zber výsledkov
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Zastavenie workerov
for w in workers:
w.cancel()
Rešpektovanie kvót namiesto ich narážania
OpenAI presadzuje dva simultánne limity: požiadavky za minútu a tokeny za minútu. Pool desiatich workerov posielajúcich všetko, čo môžu, narazí na jeden alebo druhý limit, dostane chyby obmedzenia rýchlosti, skúsi to znova a zhorší preťaženie. Je lepšie sa dobrovoľne spomaliť upstream, než byť odmietnutý downstream.
Nižšie uvedený obmedzovač aplikuje token bucket na posuvnom jednominútovom okne. Udržiava dve histórie – časové pečiatky nedávnych požiadaviek a dvojice časová pečiatka/tokeny – čistí záznamy, ktoré vypadli z okna, a potom čaká, ak by bol prekročený ktorýkoľvek limit. Zámok asyncio je nevyhnutný: bez neho by desať workerov vyhodnotilo tú istú situáciu simultánne a všetci desiati by sa rozhodli, že je ešte miesto.
import asyncio
import time
class RateLimiter:
"""Obmedzovač rýchlosti založený na token bucket."""
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):
"""Počká, ak je to potrebné, aby sa rešpektovali limity."""
async with self.lock:
now = time.time()
window = 60.0
# Vyčistenie záznamov mimo okna
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
]
# Kontrola RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Kontrola 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))
Parameter estimated_tokens si zaslúži slovo: skutočnú cenu nepoznáš, kým nepríde odpoveď, takže pracuješ s odhadom. Urob ho štedrým skôr než presným. Systematické podceňovanie sumy sa rovná vypnutiu ochrany presne vtedy, keď by bola užitočná.
Okamžité vrátenie kontroly
Pre spracovanie, ktoré trvá niekoľko minút, nie je životaschopné nechať HTTP klienta čakať: time-outy proxy, prehliadača a load balancera sa aktivujú skôr, než dokončíš. Vzorec webhooku obracia zodpovednosť. Tvoj endpoint prijme požiadavku, okamžite vráti ID úlohy a upozorní volajúceho, keď existuje výsledok, bez potreby periodického dotazovania (polling).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Spustí analýzu na pozadí a upozorní cez webhook."""
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,
):
"""Spustí analýzu a odošle výsledok cez webhook."""
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,
})
Vždy ulož vrátené ID a priradený stav niekam trvalo. Webhook sa môže stratiť a volajúci si musí zachovať schopnosť výsledok sám načítať.
Kľúčové poznatky
- Používaj asynchrónne fronty na oddelenie ingestie od spracovania
- Implementuj obmedzovač rýchlosti na rešpektovanie kvót OpenAI
- Spravuj opakované pokusy s exponenciálnym oneskorením vo svojich workerov
- Pre dlho bežiace úlohy uprednostni vzorec webhooku pred periodickým dotazovaním