Asinkrona arhitektura i redovi
Na ovoj stranici
Zašto nikada ne blokiraš na pozivu LLM-a
API poziv jezičnom modelu traje između jedne i trideset sekundi, ovisno o modelu i složenosti zahtjeva. Trideset sekundi je vječnost za serverski proces: u tom vremenu nit koja čeka ne radi ništa, a ipak zauzima slot. Pomnoži to sa sto istovremenih zahtjeva i tvoja aplikacija će se srušiti ne zato što previše računa, već zato što previše čeka.
Asinkrona arhitektura utemeljena na redu rješava tri problema odjednom. Upija skokove prometa jer red raste umjesto da odbija zahtjeve. Centralizira logiku ponovnih pokušaja jer se neuspjeli zadatak vraća u red umjesto da nestane zajedno s HTTP zahtjevom koji ga je pokrenuo. I odvaja tvoje servise: komponenta koja prima zahtjeve više ne mora znati koliko vremena izvršnoj komponenti treba za obradu.
Obrazac proizvođač / potrošač
Osnovna struktura oslanja se na dva objekta. Zadatak opisuje što treba učiniti i trenutni status obrade; red distribuira te zadatke skupu radnika koji ih troše paralelno. Modeliranje statusa kao enumeracije umjesto kao niza slobodnog oblika izbjegava najčešću klasu grešaka u ovakvom kodu: dva dijela programa pišu „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:
"""Asinkroni red za LLM pozive."""
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:
"""Dodaje zadatak u red."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Radnik koji obrađuje zadatke iz reda."""
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):
"""Pokreće radnike."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Čeka dok se svi zadaci ne obrade."""
await self.queue.join()
Dva detalja u ovom radniku zaslužuju tvoju pažnju jer se pojavljuju u svakoj implementaciji u stvarnom svijetu. Brojač attempts živi na samom zadatku, a ne na radniku, što omogućuje bilo kojem drugom radniku da preuzme ponovno stavljeni zadatak bez gubitka njegove povijesti. Poziv task_done() nalazi se unutar bloka finally kako bi se zajamčilo da se red nikada neće beskonačno zaglaviti ako neočekivana iznimka zaobiđe blok except: bez njega, simptom je join() koji se nikada ne vraća, a dijagnosticiranje je bolno.
Na strani pozivatelja uporaba je jednostavna: pokreni radnike, stavi zadatke u red, pričekaj, prikupi rezultate i zaustavi.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Dodaj zadatke
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Summarize this document: {doc}",
)
await queue.add(task)
# Pričekaj završetak
await queue.wait_completion()
# Prikupi rezultate
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Zaustavi radnike
for w in workers:
w.cancel()
Poštovanje kvota umjesto njihovog udara
OpenAI nameće dva istovremena ograničenja: zahtjeva u minuti i tokena u minuti. Skup od deset radnika koji šalju sve što mogu udarit će u jedno ili drugo, primiti greške ograničenja stope, pokušati ponovno i pogoršati zagušenje. Bolje je dobrovoljno usporiti uzvodno nego biti odbijen nizvodno.
Ograničivač u nastavku primjenjuje kantu tokena na kliznom prozoru od jedne minute. Održava dvije povijesti – vremenske oznake nedavnih zahtjeva i parove vremenske oznake/token – briše unose koji su ispali iz prozora, a zatim čeka ako bi bilo koje ograničenje bilo premašeno. asyncio lokvit je ključan: bez njega, deset radnika bi istovremeno procijenilo istu situaciju i svih deset bi odlučilo da još ima mjesta.
import asyncio
import time
class RateLimiter:
"""Ograničivač stope temeljen na kanti tokena."""
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):
"""Čeka ako je potrebno radi poštovanja ograničenja."""
async with self.lock:
now = time.time()
window = 60.0
# Očisti unose izvan prozora
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
]
# Provjeri RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Provjeri 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))
Parametar estimated_tokens zaslužuje riječ: ne znaš stvarnu cijenu dok odgovor ne stigne, pa radiš s procjenom. Učini je velikodušnom umjesto preciznom. Sustavno podcjenjivanje jednako je isključivanju zaštite točno kada bi bila korisna.
Trenutni povratak kontrole
Za obradu koja traje nekoliko minuta, čekanje HTTP klijenta više nije izvedivo: time-outovi proxyja, preglednika i balancera opterećenja aktivirat će se prije nego što završiš. Obrazac webhooka preokreće odgovornost. Tvoja krajnja točka prihvaća zahtjev, odmah vraća ID zadatka i obavještava pozivatelja kada rezultat postoji, bez potrebe za povremenim ispitivanjem.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Pokreće pozadinsku analizu i obavještava putem webhooka."""
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,
):
"""Pokreće analizu i šalje rezultat putem webhooka."""
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,
})
Uvijek pohrani vraćeni ID i pridruženo stanje negdje trajno. Webhook se može izgubiti, a pozivatelj mora zadržati mogućnost samostalnog dohvaćanja rezultata.
Ključne točke
- Koristi asinkrone redove za odvajanje unosa od obrade
- Implementiraj ograničivač stope za poštovanje OpenAI kvota
- Rukuj ponovnim pokušajima s eksponencijalnim kašnjenjem u svojim radnicima
- Za dugotrajne zadatke, daj prednost obrascu webhooka umjesto ispitivanju