Asynchronní architektura a fronty
Na této stránce
Proč nikdy neblokovat při volání LLM
Volání API jazykového modelu trvá mezi jednou a třiceti sekundami, v závislosti na modelu a složitosti požadavku. Třicet sekund je pro serverový proces věčnost: během této doby čekající vlákno nic nedělá, přesto však obsazuje slot. Vynásob to stovkou současných požadavků a tvá aplikace spadne ne proto, že by počítala příliš mnoho, ale protože příliš dlouho čeká.
Asynchronní architektura založená na frontě řeší najednou tři problémy. Pohlcuje špičky provozu, protože fronta roste místo toho, aby odmítala požadavky. Centralizuje logiku opakování, protože neúspěšný úkol se vrací do fronty místo toho, aby zmizel spolu s HTTP požadavkem, který jej spustil. A odděluje vaše služby: komponenta přijímající požadavky již nemusí vědět, jak dlouho trvá vykonávající komponentě jejich zpracování.
Vzorec Producent / Konzument
Základní struktura spoléhá na dva objekty. Úkol popisuje, co je třeba udělat, a aktuální stav zpracování; fronta distribuuje tyto úkoly do poolu workerů, kteří je zpracovávají paralelně. Modelování stavu jako výčtu (enum) namísto volného řetězce se vyhýbá nejčastější třídě chyb v tomto typu kódu: dvě části programu zapisují "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:
"""Asynchronní fronta pro volání 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:
"""Přidá úkol do fronty."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Worker zpracovávající úkoly 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í workery."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Čeká, dokud nejsou zpracovány všechny úkoly."""
await self.queue.join()
Dva detaily v tomto workeru si zaslouží tvou pozornost, protože se objevují v každé reálné implementaci. Čítač attempts žije přímo na úkolu, nikoliv na workerovi, což umožňuje jakémukoli jinému workerovi převzít znovu zařazený úkol bez ztráty jeho historie. Volání task_done() sídlí uvnitř bloku finally, aby se zaručilo, že fronta nikdy nezůstane viset na neurčito, pokud neočekávaná výjimka obejde blok except: bez toho je příznakem join(), který se nikdy nevrátí, a jeho diagnostika je bolestivá.
Na straně volajícího je použití přímočaré: spusť workery, zařaď úkoly, počkej, sesbírej výsledky a zastav.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Přidání úkolů
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Shrň tento dokument: {doc}",
)
await queue.add(task)
# Čekání na dokončení
await queue.wait_completion()
# Sesbírání výsledků
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Zastavení workerů
for w in workers:
w.cancel()
Respektování kvót místo jejich narážení
OpenAI vynucuje dva současné limity: požadavky za minutu a tokeny za minutu. Pool deseti workerů posílajících vše, co mohou, narazí na jeden nebo druhý limit, obdrží chyby omezení rychlosti, zkusí to znovu a zhorší přetížení. Je lepší se dobrovolně zpomalit upstream, než být odmítnut downstream.
Níže uvedený omezovač aplikuje token bucket na posuvném jednominutovém okně. Udržuje dvě historie – časová razítka nedávných požadavků a dvojice časové razítko/token – čistí položky, které vypadly z okna, a poté čeká, pokud by byl překročen kterýkoli limit. Zámek asyncio je zásadní: bez něj by deset workerů vyhodnocovalo stejnou situaci současně a všech deset by se rozhodlo, že je ještě místo.
import asyncio
import time
class RateLimiter:
"""Omezovač rychlosti 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):
"""Čeká, pokud je to nutné, aby respektoval limity."""
async with self.lock:
now = time.time()
window = 60.0
# Vyčištění položek mimo okno
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))
Parametr estimated_tokens si zaslouží slovo: skutečnou cenu neznáš, dokud nedorazí odpověď, takže pracuješ s odhadem. Udělej ho štědrý spíše než přesný. Systematické podceňování znamená de facto vypnutí ochrany přesně ve chvíli, kdy by byla užitečná.
Okamžité vrácení řízení
Pro zpracování, které trvá několik minut, není čekání HTTP klienta životaschopné: časové limity proxy, prohlížeče a zátěžové rovnováhy nastoupí dříve, než skončíš. Vzorec webhooku obrací odpovědnost. Tvůj koncový bod přijme požadavek, okamžitě vrátí ID úkolu a upozorní volajícího, když existuje výsledek, aniž by vyžadoval periodické dotazování (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í přes 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 odešle výsledek přes 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 ukládej vrácené ID a přidružený stav někam trvalého. Webhook se může ztratit a volající si musí zachovat schopnost získat výsledek sám.
Klíčové poznatky
- Používej asynchronní fronty k oddělení ingestování od zpracování
- Implementuj omezovač rychlosti pro respektování kvót OpenAI
- Zacházej s opakováními pomocí exponenciálního backoff ve svých workerech
- Pro dlouho běžící úkoly upřednostni vzorec webhooku před dotazováním