Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Asynkroninen arkkitehtuuri ja jonot

Oppitunti 7 / 20 Päivitetty 28. heinäkuuta 2026 Edistynyt
Tällä sivulla
  1. Miksi et koskaan estä LLM-kutsua
  2. Tuottaja / Kuluttaja -kuvio
  3. Kiintiöiden kunnioittaminen niiden rikkomisen sijaan
  4. Ohjauksen palauttaminen välittömästi
  5. Keskeiset asiat

Miksi et koskaan estä LLM-kutsua

Kielimallin API-kutsu kestää yhdestä kolmeenkymmeneen sekuntiin riippuen mallista ja pyynnön vaativuudesta. Kolmekymmentä sekuntia on ikuisuus palvelinprosessille: tänä aikana odottava säie ei tee mitään, mutta se vie silti paikan. Kerro tämä sadalla samanaikaisella pyynnöllä, ja sovelluksesi kaatuu ei siksi, että se laskisi liikaa, vaan siksi, että se odottaa liikaa.

Jonoon perustuva asynkroninen arkkitehtuuri ratkaisee kolme ongelmaa kerralla. Se vaimentaa liikennehuiput, koska jono kasvaa pyyntöjen hylkäämisen sijaan. Se keskittää uudelleenyrityslogiikan, koska epäonnistunut tehtävä palaa jonoon sen sijaan, että se katoaisi sen käynnistäneen HTTP-pyynnön mukana. Ja se irrottaa palvelusi toisistaan: pyyntöjä vastaanottavan komponentin ei tarvitse enää tietää, kuinka kauan tehtävän suorittava komponentti kestää.

Tuottaja / Kuluttaja -kuvio

Perusrakenne nojaa kahteen olioon. Tehtävä kuvaa, mitä on tehtävä ja nykyisen käsittelyn tilan; jono jakaa nämä tehtävät rinnakkain niitä kuluttavalle työntekijäpoolille. Tilan mallintaminen lueteltuna tyyppinä vapaamuotoisen merkkijonon sijaan välttää yleisimmän bugiluokan tämän tyyppisessä koodissa: kaksi ohjelman osaa kirjoittaa "terminee" ja "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:
    """Asynkroninen jono LLM-kutsuille."""

    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:
        """Lisää tehtävän jonoon."""
        self.results[task.id] = task
        await self.queue.put(task)
        return task.id

    async def worker(self, worker_id: int):
        """Työntekijä, joka käsittelee tehtäviä jonosta."""
        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):
        """Käynnistää työntekijät."""
        workers = [
            asyncio.create_task(self.worker(i))
            for i in range(self.num_workers)
        ]
        return workers

    async def wait_completion(self):
        """Odottaa, kunnes kaikki tehtävät on käsitelty."""
        await self.queue.join()

Tässä työntekijässä kaksi yksityiskohtaa ansaitsevat huomiosi, sillä ne esiintyvät jokaisessa todellisessa toteutuksessa. attempts-laskuri elää itse tehtävässä, ei työntekijässä, mikä mahdollistaa sen, että mikä tahansa muu työntekijä voi napata uudelleenjonotetun tehtävän menettämättä sen historiaa. task_done()-kutsu sijaitsee finally-lohkossa varmistaakseen, että jono ei jumitu ikuisesti, jos odottamaton poikkeus ohittaa except-lohkon: ilman sitä oireena on palautumaton join(), ja sen diagnosointi on tuskallista.

Kutsujan puolella käyttö on suoraviivaista: käynnistä työntekijät, laita tehtävät jonoon, odota, kerää tulokset ja pysäytä.

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

    # Lisää tehtävät
    for i, doc in enumerate(documents):
        task = Task(
            id=f"doc-{i}",
            prompt=f"Tiivistä tämä asiakirja: {doc}",
        )
        await queue.add(task)

    # Odota valmistumista
    await queue.wait_completion()

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

    # Pysäytä työntekijät
    for w in workers:
        w.cancel()

Kiintiöiden kunnioittaminen niiden rikkomisen sijaan

OpenAI valvoo kahta samanaikaista rajaa: pyyntöjä minuutissa ja tokeneja minuutissa. Kymmenen työntekijän pooli, joka lähettää kaiken minkä ehtii, osuu jompaankumpaan, saa nopeusrajoitusvirheitä, yrittää uudelleen ja pahentaa ruuhkaa. On parempi hidastaa vapaaehtoisesti ylävirrassa kuin tulla torjutuksi alavirrassa.

Alla oleva rajoitin toteuttaa tokenämpärin liukuvan minuutin ikkunalla. Se ylläpitää kahta historiaa – viimeaikaisten pyyntöjen aikaleimoja ja aikaleima/token-pareja – puhdistaa ikkunan ulkopuolelle jääneet merkinnät ja odottaa sitten, jos jompikumpi raja ylittyisi. Asyncio-lukko on välttämätön: ilman sitä kymmenen työntekijää arvioisi saman tilanteen samanaikaisesti, ja kaikki kymmenen päättäisivät tilaa olevan vielä jäljellä.

import asyncio
import time

class RateLimiter:
    """Nopeusrajoitin, joka perustuu tokenämpäriin."""

    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):
        """Odottaa tarvittaessa rajojen kunnioittamiseksi."""
        async with self.lock:
            now = time.time()
            window = 60.0

            # Puhdistaa ikkunan ulkopuolelle jääneet merkinnät
            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
            ]

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

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

Parametri estimated_tokens ansaitsee sanan: et tiedä todellista kustannusta ennen kuin vastaus saapuu, joten työskentelet arvion kanssa. Tee siitä mieluummin antelias kuin tarkka. Systemaattinen aliarviointi tarkoittaa suojauksen kytkemistä pois päältä juuri silloin, kun sitä tarvitsisi.

Ohjauksen palauttaminen välittömästi

Useita minuutteja kestävälle käsittelylle HTTP-asiakkaan odottaminen ei ole enää viable: välityspalvelimet, selaimet ja kuormantasaimien aikakatkaisut ehtivät laukaista ennen kuin olet valmis. Webhook-kuvio kääntää vastuun. Päätepisteesi hyväksyy pyynnön, palauttaa välittömästi tehtävätunnuksen ja ilmoittaa kutsujalle, kun tulos on olemassa, ilman tarvetta jaksolliseen kyselyyn.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/api/analyze")
async def start_analysis(
    request: dict,
    background_tasks: BackgroundTasks,
):
    """Käynnistää tausta-analyysin ja ilmoittaa webhookin kautta."""
    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,
):
    """Suorittaa analyysin ja lähettää tuloksen webhookin kautta."""
    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,
            })

Tallenna aina palautettu tunnus ja siihen liittyvä tila kestävään tallennustilaan. Webhook voi kadota, ja kutsujan on pystyttävä hakemaan tulos itse.

Keskeiset asiat

  • Käytä asynkronisia jonoja irrottaaksesi vastaanoton käsittelystä
  • Toteuta nopeusrajoitin OpenAI-kiintiöiden kunnioittamiseksi
  • Käsittele uudelleenyritykset eksponentiaalisella viiveellä työntekijöissäsi
  • Suosi pitkissä tehtävissä webhook-kuviota kyselyn sijaan