Asynkron arkitektur og køer
På denne side
Hvorfor du aldrig bør blokere på et LLM-kald
Et API-kald til en sprogmodel tager mellem ét og tredive sekunder, afhængigt af modellen og forespørgslens kompleksitet. Tredive sekunder er en evighed for en serverproces: I mellemtiden laver den ventende tråd ingenting, men den optager stadig en plads. Gang det med hundrede samtidige forespørgsler, og din applikation crascher ikke fordi den regner for meget, men fordi den venter for meget.
En asynkron arkitektur understøttet af en kø løser tre problemer på én gang. Den absorberer trafikspidsbelastninger, da køen vokser i stedet for at afvise forespørgsler. Den centraliserer logik for genforsøg, fordi en mislykket opgave returnerer til køen i stedet for at forsvinde sammen med den HTTP-forespørgsel, der udløste den. Og den afkobler dine tjenester: Komponenten der modtager forespørgsler behøver ikke længere vide, hvor lang tid den udførende komponent tager om at behandle dem.
Producent / Forbruger-mønsteret
Den grundlæggende struktur hviler på to objekter. En opgave beskriver, hvad der skal gøres, og den aktuelle behandlingsstatus; en kø distribuerer disse opgaver til en pulje af arbejdere, der forbruger dem parallelt. At modellere status som en enumeration i stedet for en frit formateret streng undgår den mest almindelige klasse af fejl i denne type kode: To dele af programmet, der skriver "terminee" og "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:
"""Asynkron kø til LLM-kald."""
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:
"""Tilføjer en opgave til køen."""
self.results[task.id] = task
await self.queue.put(task)
return task.id
async def worker(self, worker_id: int):
"""Arbejder der behandler opgaver fra køen."""
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):
"""Starter arbejderne."""
workers = [
asyncio.create_task(self.worker(i))
for i in range(self.num_workers)
]
return workers
async def wait_completion(self):
"""Venter indtil alle opgaver er behandlet."""
await self.queue.join()
To detaljer i denne arbejder fortjener din opmærksomhed, fordi de optræder i enhver implementering i den virkelige verden. Tælleren attempts lever på selve opgaven, ikke på arbejderen, hvilket tillader enhver anden arbejder at hente en genkøet opgave uden at miste dens historik. Kaldet task_done() sidder inde i en finally-blok for at garantere, at køen aldrig hænger ubestemt, hvis en uventet undtagelse omgår except-blokken: Uden den er et join(), der aldrig returnerer, symptomet, og det er smertefuldt at diagnosticere.
På kaldersiden er brugen ligetil: Start arbejderne, sæt opgaver i kø, vent, saml resultater og stop.
async def process_documents(documents: list[str]):
queue = ProcessingQueue(num_workers=10)
workers = await queue.start()
# Tilføj opgaver
for i, doc in enumerate(documents):
task = Task(
id=f"doc-{i}",
prompt=f"Opsummer dette dokument: {doc}",
)
await queue.add(task)
# Vent på fuldførelse
await queue.wait_completion()
# Saml resultater
for task_id, task in queue.results.items():
print(f"{task_id}: {task.status.value}")
# Stop arbejdere
for w in workers:
w.cancel()
Respektér kvoter i stedet for at ramme dem
OpenAI håndhæver to samtidige grænser: Forespørgsler per minut og tokens per minut. En pulje på ti arbejdere, der sender alt hvad de kan, vil ramme den ene eller den anden, modtage fejl om hastighedsbegrænsning, forsøge igen og forværre overbelastningen. Det er bedre at bremse frivilligt opstrøms end at blive afvist nedstrøms.
Begrænseren nedenfor anvender en token-spand over et glidende vindue på ét minut. Den vedligeholder to historikker – tidsstempler for nylige forespørgsler og par af tidsstempel/token – rydder poster, der er faldet ud af vinduet, og venter derefter, hvis enten grænse ville blive overskredet. Asyncio-låsen er afgørende: Uden den ville ti arbejdere evaluere den samme situation samtidigt, og alle ti ville konkludere, at der stadig er plads.
import asyncio
import time
class RateLimiter:
"""Hastighedsbegrænser baseret på en token-spand."""
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):
"""Venter om nødvendigt for at overholde grænser."""
async with self.lock:
now = time.time()
window = 60.0
# Ryd poster uden for vinduet
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
]
# Tjek RPM
if len(self.recent_requests) >= self.rpm:
wait_time = self.recent_requests[0] + window - now
await asyncio.sleep(wait_time)
# Tjek 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))
Parameteren estimated_tokens fortjener et ord: Du kender ikke den faktiske omkostning, før svaret ankommer, så du arbejder med et estimat. Gør det generøst frem for præcist. Systematisk at undervurdere svarer til at deaktivere beskyttelsen præcis når den ville være nyttig.
Returnér kontrollen øjeblikkeligt
For behandling der tager flere minutter, er det ikke længere levedygtigt at få en HTTP-klient til at vente: Proxy-, browser- og load balancer-timeouts vil træde i kraft før du er færdig. Webhook-mønsteret vender ansvaret om. Dit endpoint accepterer forespørgslen, returnerer straks et opgave-ID og underretter kaldernår resultatet foreligger, uden at kræve periodisk polling.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
@app.post("/api/analyze")
async def start_analysis(
request: dict,
background_tasks: BackgroundTasks,
):
"""Starter en baggrundsanalyse og underretter via 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,
):
"""Kører analysen og sender resultatet 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,
})
Gem altid det returnerede ID og den tilhørende tilstand et sted, der er holdbart. En webhook kan gå tabt, og kaldern skal beholde muligheden for selv at hente resultatet.
Vigtige pointer
- Brug asynkrone køer til at afkoble indsamling fra behandling
- Implementér en hastighedsbegrænser for at overholde OpenAI-kvoter
- Håndtér genforsøg med eksponentiel backoff i dine arbejdere
- Foretræk et webhook-mønster frem for polling til langvarige opgaver