Przejdź do głównej treści
Polski— Wybierz język
Menu

Architektura asynchroniczna i kolejki zadań

Lekcja 7 z 20 Zaktualizowano 28 lipca 2026 Zaawansowany
Na tej stronie
  1. Dlaczego nigdy nie blokujesz wywołania LLM
  2. Wzorzec Producent / Konsument
  3. Szanowanie limitów zamiast ich przekraczania
  4. Natychmiastowe zwracanie sterowania
  5. Kluczowe wnioski

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)