Architektura asynchroniczna i kolejki zadań
Na tej stronie
Dlaczego nigdy nie blokujesz wywołania LLM
Wywołanie API do modelu językowego trwa od jednej do trzydziestu sekund, w zależności od modelu i złożoności żądania. Trzydzieści sekund to wieczność dla procesu serwerowego: w tym czasie oczekujący wątek nic nie robi, a mimo to zajmuje slot. Pomnóż to przez sto jednoczesnych żądań, a Twoja aplikacja padnie nie dlatego, że wykonuje zbyt wiele obliczeń, ale dlatego, że zbyt dużo czeka.
Architektura asynchroniczna oparta na kolejce rozwiązuje trzy problemy naraz. Łagodzi skoki ruchu, ponieważ kolejka rośnie zamiast odrzucać żądania. Centralizuje logikę ponawiania prób, ponieważ nieudane zadanie wraca do kolejki zamiast znikać wraz z żądaniem HTTP, które je wywołało. Rozdziela też Twoje usługi: komponent odbierający żądania nie musi już wiedzieć, ile czasu zajmuje przetwarzanie komponentowi wykonawczemu.
Wzorzec Producent / Konsument
Podstawowa struktura opiera się na dwóch obiektach. Zadanie opisuje, co należy zrobić, oraz obecny status przetwarzania; kolejka dystrybuuje te zadania do puli workerów, które konsumują je równolegle. Modelowanie statusu jako enumeracji, a nie dowolnego ciągu znaków, pozwala uniknąć najczęstszej klasy błędów w tego typu kodzie: sytuacji, w której dwie części programu zapisują "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:
"""Asynchroniczna kolejka dla wywołań 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:
"""Dodaje zadanie do kolejki."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Worker przetwarzający zadania z kolejki."""
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):
"""Uruchamia workery."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Czeka aż wszystkie zadania zostaną przetworzone."""
await self.queue.join()
Dwa szczegóły w tym workerze zasługują na Twoją uwagę, ponieważ pojawiają się w każdej implementacji produkcyjnej. Licznik attempts żyje w samym zadaniu, a nie w workerze, co pozwala dowolnemu innemu workerowi podjąć ponownie zakolejkowane zadanie bez utraty jego historii. Wywołanie task_done() znajduje się w bloku finally, aby zagwarantować, że kolejka nigdy nie zawiesi się w nieskończoność, jeśli nieoczekiwany wyjątek ominie blok except: bez tego objawem będzie join(), które nigdy nie zwraca sterowania, a diagnozowanie takiego problemu bywa bolesne.
Po stronie wywołującego użycie jest proste: uruchom workery, dodaj zadania do kolejki, poczekaj, zbierz wyniki i zatrzymaj proces.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Dodaj zadania
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Summarize this document: {doc}",
)
await queue.add(task)
# Poczekaj na zakończenie
await queue.wait_completion()
# Zbierz wyniki
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Zatrzymaj workery
for w in workers:
w.cancel()
Szanowanie limitów zamiast ich przekraczania
OpenAI egzekwuje dwa jednoczesne limity: liczba żądań na minutę oraz liczba tokenów na minutę. Pula dziesięciu workerów wysyłających wszystko, co mogą, uderzy w jeden lub drugi limit, otrzyma błędy ograniczenia przepustowości (rate limit), podejmie ponowne próby i pogorszy zator. Lepiej jest dobrowolnie zwolnić tempo u źródła, niż zostać odrzuconym na końcu łańcucha.
Poniższy limiter stosuje mechanizm kubełka z tokenami (token bucket) w przesuwnym oknie jednominutowym. Utrzymuje dwie historie – znaczniki czasu ostatnich żądań oraz pary znacznik czasu/liczba tokenów – czyści wpisy, które wypadły z okna, a następnie czeka, jeśli którykolwiek z limitów zostałby przekroczony. Blokada asyncio jest kluczowa: bez niej dziesięciu workerów oceniałoby tę samą sytuację jednocześnie i wszyscy dziesięciu uznałoby, że jest jeszcze miejsce.
import asyncio
import time
class RateLimiter:
"""Limiter przepustowości oparty na kubełku z tokenami."""
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):
"""Czeka w razie potrzeby, aby przestrzegać limitów."""
async with self.lock:
now = time.time()
window = 60.0
# Wyczyść wpisy spoza 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
]
# Sprawdź RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Sprawdź 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 zasługuje na komentarz: nie znasz rzeczywistego kosztu, dopóki nie nadejdzie odpowiedź, więc pracujesz na estymacie. Uczyń ją hojną, a nie precyzyjną. Systematyczne zaniżanie wartości oznacza de facto wyłączenie ochrony dokładnie wtedy, gdy byłaby najbardziej przydatna.
Natychmiastowe zwracanie sterowania
W przypadku przetwarzania trwającego kilka minut, czekanie klienta HTTP nie jest już wykonalne: limity czasu proxy, przeglądarki i balansera obciążenia uruchomią się, zanim skończysz pracę. Wzorzec webhooka odwraca odpowiedzialność. Twój endpoint przyjmuje żądanie, natychmiast zwraca ID zadania i powiadamia wywołującego, gdy wynik jest gotowy, bez konieczności okresowego odpytywania (polling).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Rozpoczyna analizę w tle i powiadamia przez 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,
):
"""Uruchamia analizę i wysyła wynik przez 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,
})
Zawsze przechowuj zwrócone ID i powiązany stan w trwałym miejscu. Webhook może się zgubić, a wywołujący musi zachować możliwość samodzielnego pobrania wyniku.
Kluczowe wnioski
- Używaj asynchronicznych kolejek, aby oddzielić przyjmowanie danych od ich przetwarzania
- Zaimplementuj limiter przepustowości, aby przestrzegać limitów OpenAI
- Obsługuj ponowne próby z wykładniczym opóźnieniem (exponential backoff) w swoich workerach
- W przypadku zadań długotrwałych preferuj wzorzec webhooka zamiast odpytywania (polling)