Arhitectură asincronă și cozi de așteptare
Pe această pagină
De ce nu blocați niciodată execuția la un apel LLM
Un apel API către un model lingvistic durează între una și treizeci de secunde, în funcție de model și de complexitatea cererii. Treizeci de secunde reprezintă o eternitate pentru un proces server: în acest interval, firul de execuție care așteaptă nu face nimic, dar ocupă totuși un slot. Înmulțiți această situație cu o sută de cereri simultane, iar aplicația dumneavoastră se va prăbuși nu pentru că procesează prea mult, ci pentru că așteaptă prea mult.
O arhitectură asincronă susținută de o coadă de așteptare rezolvă trei probleme simultan. Absoarbe vârfurile de trafic, deoarece coada crește în loc să respingă cererile. Centralizează logica de reîncercare, deoarece o sarcină eșuată revine în coadă în loc să dispară odată cu cererea HTTP care a declanșat-o. Și decuplează serviciile: componenta care primește cererile nu mai trebuie să știe cât timp îi ia componentei de execuție să le proceseze.
Modelul Producător / Consumator
Structura de bază se bazează pe două obiecte. O sarcină (task) descrie ce trebuie făcut și stadiul actual de procesare; o coadă distribuie aceste sarcini către un pool de lucrători (workers) care le consumă în paralel. Modelarea stării ca o enumerare, în loc de un șir de caractere liber, evită cea mai frecventă clasă de erori în acest tip de cod: două părți ale programului scriind "terminee" și "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:
"""Coadă asincronă pentru apeluri 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:
"""Adaugă o sarcină în coadă."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Lucrător care procesează sarcinile din coadă."""
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):
"""Pornește lucrătorii."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Așteaptă până când toate sarcinile sunt procesate."""
await self.queue.join()
Două detalii din acest lucrător merită atenția dumneavoastră, deoarece apar în fiecare implementare din lumea reală. Contorul attempts aparține sarcinii în sine, nu lucrătorului, permițând oricărui alt lucrător să preia o sarcină repusă în coadă fără a-i pierde istoricul. Apelul task_done() se află într-un bloc finally pentru a garanta că coada nu se blochează la infinit dacă o excepție neașteptată ocolește blocul except: fără el, un join() care nu returnează niciodată este simptomul, iar diagnosticarea sa este dureroasă.
Din partea apelantului, utilizarea este simplă: porniți lucrătorii, adăugați sarcinile în coadă, așteptați, colectați rezultatele și opriți procesele.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Adaugă sarcinile
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Summarize this document: {doc}",
)
await queue.add(task)
# Așteaptă finalizarea
await queue.wait_completion()
# Colectează rezultatele
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Oprește lucrătorii
for w in workers:
w.cancel()
Respectarea cotelor în loc de lovirea lor
OpenAI impune două limite simultane: cereri pe minut și tokeni pe minut. Un pool de zece lucrători care trimit tot ce pot va lovi una sau cealaltă limită, va primi erori de limitare a ratei, va reîncerca și va agrava congestia. Este mai bine să încetiniți voluntar în amonte decât să fiți respinși în aval.
Limitatorul de mai jos aplică un sistem de tip „găleată cu tokeni“ (token bucket) pe o fereastră glisantă de un minut. Menține două istorice – marcaje temporale ale cererilor recente și perechi marcaj temporal/tokeni – elimină intrările care au ieșit din fereastră, apoi așteaptă dacă oricare dintre limite ar fi depășită. Blocajul asyncio este esențial: fără el, zece lucrători ar evalua aceeași situație simultan și toți zece ar decide că mai există loc disponibil.
import asyncio
import time
class RateLimiter:
"""Limitator de rată bazat pe o găleată cu tokeni."""
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):
"""Așteaptă dacă este necesar pentru a respecta limitele."""
async with self.lock:
now = time.time()
window = 60.0
# Curăță intrările din afara ferestrei
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
]
# Verifică RPM (cereri pe minut)
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Verifică TPM (tokeni pe minut)
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))
Parametrul estimated_tokens merită o mențiune: nu cunoașteți costul real până când nu sosește răspunsul, așa că lucrați cu o estimare. Faceți-o generoasă, nu precisă. Subestimarea sistematică echivalează cu dezactivarea protecției exact atunci când ar fi utilă.
Returnarea imediată a controlului
Pentru procesările care durează câteva minute, a face un client HTTP să aștepte nu mai este viabil: timeout-urile proxy-ului, browserului și ale balansatorului de sarcină se vor declanșa înainte ca dumneavoastră să terminați. Modelul webhook inversează responsabilitatea. Endpoint-ul dumneavoastră acceptă cererea, returnează imediat un ID de sarcină și notifică apelantul când rezultatul există, fără a necesita interogări periodice (polling).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Pornește o analiză în fundal și notifică prin 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,
):
"""Rulează analiza și trimite rezultatul prin 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,
})
Stocați întotdeauna ID-ul returnat și starea asociată undeva durabil. Un webhook se poate pierde, iar apelantul trebuie să păstreze capacitatea de a prelua rezultatul singur.
Puncte cheie
- Utilizați cozi asincrone pentru a decupla ingestia de procesare
- Implementați un limitator de rată pentru a respecta cotele OpenAI
- Gestionați reîncercările cu backoff exponențial în lucrătorii dumneavoastră
- Pentru sarcinile de lungă durată, preferați modelul webhook în detrimentul interogărilor periodice