Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Asynchrone architectuur en wachtrijen

Les 7 van 20 Bijgewerkt op 28 juli 2026 Gevorderd
Op deze pagina
  1. Waarom u nooit blokkeert op een LLM-aanroep
  2. Het Producer/Consumer-patroon
  3. Quota respecteren in plaats van ze te raken
  4. Direct controle teruggeven
  5. Belangrijkste punten

Waarom u nooit blokkeert op een LLM-aanroep

Een API-aanroep naar een taalmodel duurt tussen de één en dertig seconden, afhankelijk van het model en de complexiteit van de aanvraag. Dertig seconden is een eeuwigheid voor een serverproces: gedurende die tijd doet de wachtende thread niets, maar bezet deze wel een slot. Vermenigvuldig dat met honderd gelijktijdige aanvragen en uw applicatie crasht niet omdat deze te veel rekent, maar omdat deze te lang wacht.

Een asynchrone architectuur ondersteund door een wachtrij lost drie problemen tegelijk op. Het absorbeert pieken in het verkeer, omdat de wachtrij groeit in plaats van aanvragen te weigeren. Het centraliseert de retry-logica, omdat een mislukte taak terugkeert naar de wachtrij in plaats van te verdwijnen met het HTTP-verzoek dat deze heeft geactiveerd. En het ontkoppelt uw services: de component die verzoeken ontvangt, hoeft niet langer te weten hoe lang de uitvoerende component nodig heeft om ze te verwerken.

Het Producer/Consumer-patroon

De basisstructuur vertrouwt op twee objecten. Een taak beschrijft wat er moet worden gedaan en de huidige verwerkingsstatus; een wachtrij verdeelt deze taken over een pool van workers die ze parallel consumeren. Het modelleren van status als een enumeratie in plaats van een vrij formaat string vermijdt de meest voorkomende klasse bugs in dit soort code: twee delen van het programma die "terminee" en "terminée" schrijven.

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:
    """Asynchrone wachtrij voor LLM-aanroepen."""

    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:
        """Voegt een taak toe aan de wachtrij."""
        self.results[task.id] = task
        await self.queue.put(task)
        return task.id

    async def worker(self, worker_id: int):
        """Worker die taken uit de wachtrij verwerkt."""
        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):
        """Start de workers."""
        workers = [
            asyncio.create_task(self.worker(i))
            for i in range(self.num_workers)
        ]
        return workers

    async def wait_completion(self):
        """Wacht tot alle taken zijn verwerkt."""
        await self.queue.join()

Twee details in deze worker verdienen uw aandacht omdat ze in elke real-world implementatie voorkomen. De attempts-teller zit op de taak zelf, niet op de worker, waardoor elke andere worker een opnieuw in de wachtrij geplaatste taak kan oppakken zonder zijn geschiedenis te verliezen. De task_done()-aanroep staat in een finally-blok om te garanderen dat de wachtrij nooit oneindig blijft hangen als een onverwachte uitzondering het except-blok omzeilt: zonder dit is een join() die nooit terugkeert het symptoom, en dat is pijnlijk om te diagnosticeren.

Aan de kant van de aanroeper is het gebruik eenvoudig: start de workers, zet taken in de wachtrij, wacht, verzamel resultaten en stop.

async def process_documents(documents: list[str]):
    queue = ProcessingQueue(num_workers=10)
    workers = await queue.start()

    # Taken toevoegen
    for i, doc in enumerate(documents):
        task = Task(
            id=f"doc-{i}",
            prompt=f"Vat dit document samen: {doc}",
        )
        await queue.add(task)

    # Wachten op voltooiing
    await queue.wait_completion()

    # Resultaten verzamelen
    for task_id, task in queue.results.items():
        print(f"{task_id}: {task.status.value}")

    # Workers stoppen
    for w in workers:
        w.cancel()

Quota respecteren in plaats van ze te raken

OpenAI handhaaft twee gelijktijdige limieten: aanvragen per minuut en tokens per minuut. Een pool van tien workers die alles sturen wat ze kunnen, zal de ene of de andere limiet raken, rate limit-fouten ontvangen, opnieuw proberen en de congestie verergeren. Het is beter om stroomopwaarts vrijwillig te vertragen dan om stroomafwaarts te worden geweigerd.

De onderstaande limiter past een token bucket toe over een glijdend venster van één minuut. Het onderhoudt twee geschiedenissen—tijdstempels van recente aanvragen en tijdstempel/token-paren—verwijdert items die uit het venster zijn gevallen, en wacht vervolgens als een van de limieten zou worden overschreden. De asyncio-lock is essentieel: zonder dit zouden tien workers dezelfde situatie gelijktijdig evalueren en zouden alle tien besluiten dat er nog ruimte is.

import asyncio
import time

class RateLimiter:
    """Rate limiter gebaseerd op een 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):
        """Wacht indien nodig om limieten te respecteren."""
        async with self.lock:
            now = time.time()
            window = 60.0

            # Op ruimen van items buiten het venster
            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
            ]

            # Controleer RPM
            if len(self.recent_requests) >= self.rpm:
                wait_time = self.recent_requests[0] + window - now
                await asyncio.sleep(wait_time)

            # Controleer 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))

De parameter estimated_tokens verdient een woord: u kent de werkelijke kosten pas wanneer het antwoord binnenkomt, dus werkt u met een schatting. Maak deze ruimhartig in plaats van precies. Systematisch onderschatten komt neer op het uitschakelen van bescherming precies op het moment dat deze nuttig zou zijn.

Direct controle teruggeven

Voor verwerking die enkele minuten duurt, is het niet langer haalbaar om een HTTP-client te laten wachten: proxy-, browser- en load balancer-time-outs zullen ingrijpen voordat u klaar bent. Het webhook-patroon draait de verantwoordelijkheid om. Uw endpoint accepteert het verzoek, geeft onmiddellijk een taak-ID terug en stelt de beller op de hoogte wanneer het resultaat beschikbaar is, zonder dat periodieke polling nodig is.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/api/analyze")
async def start_analysis(
    request: dict,
    background_tasks: BackgroundTasks,
):
    """Start een achtergrondanalyse en stelt via webhook op de hoogte."""
    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,
):
    """Voert de analyse uit en verzendt het resultaat via 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,
            })

Sla de geretourneerde ID en bijbehorende staat altijd ergens duurzaam op. Een webhook kan verloren gaan, en de beller moet de mogelijkheid behouden om het resultaat zelf op te halen.

Belangrijkste punten

  • Gebruik asynchrone wachtrijen om ingestie te ontkoppelen van verwerking
  • Implementeer een rate limiter om de OpenAI-quota te respecteren
  • Handel retries af met exponentiële backoff in uw workers
  • Voor langlopende taken: geef de voorkeur aan een webhook-patroon boven polling