Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Arkitettura Asinkrona u Kwijiet

Lezzjoni 7 / 20 Aġġornat 28 ta’ Lulju 2026 Avvanzat
F'din il-paġna
  1. Għaliex Qatt Ma Għandek Timblokka fuq Sejħa LLM
  2. Il-Mudell Produttur / Konsumatur
  3. Ir-Rispett tal-Kwoti Minflok il-Ħabt Magħhom
  4. Ir-Ritorn Immedjat tal-Kontroll
  5. Punti Ewlenin

Għaliex Qatt Ma Għandek Timblokka fuq Sejħa LLM

Sejħa API lejn mudell tal-lingwa tieħu bejn sekonda u tletin sekonda, skont il-mudell u l-kumplessità tat-talba. Tletin sekonda hija eternità għal proċess tas-server: matul dak iż-żmien, il-thread li qed jistenna ma jagħmel xejn, madankollu xorta jokkupa slot. Immultiplika dan b’mija talba simultanja, u l-applikazzjoni tiegħek tiġġarraf mhux għax qed tikkalkula wisq, iżda għax qed tistenna wisq.

Arkitettura asinkrona appoġġjata minn kwija (queue) issolvi tliet problemi f’daqqa waħda. Tassorbi l-piki fit-traffiku, peress li l-kwija tikber minflok ma tirrifjuta t-talbiet. Tiċċentralizza l-loġika tat-tentattivi mill-ġdid (retry), għax kompitu fallut jerġa’ lura fil-kwija minflok ma jisparixxi mas-sejħa HTTP li ħarġitu. U tissepara s-servizzi tiegħek: il-komponent li jirċievi t-talbiet m’għadx għandu bżonn jaf kemm jieħu żmien il-komponent eżekuttiv biex jipproċessahom.

Il-Mudell Produttur / Konsumatur

L-istruttura bażika tiddependi fuq żewġ oġġetti. Kompitu (task) jiddeskrivi x’għandu jsir u l-istatus attwali tal-ipproċessar; kwija tqassam dawn il-kompiti lil pool ta’ ħaddiema (workers) li jikkunsmawhom parallelament. Il-mudellar tal-istatus bħala enumerazzjoni minflok stringa b’forma ħielsa jevita l-aktar klassi komuni ta’ bugs f’dan it-tip ta’ kodiċi: żewġ partijiet tal-programm li jiktibu "terminee" u "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:
    """Asynchronous queue for LLM calls."""

    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:
        """Adds a task to the queue."""
        self.results[task.id] = task
        await self.queue.put(task)
        return task.id

    async def worker(self, worker_id: int):
        """Worker that processes tasks from the queue."""
        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):
        """Starts the workers."""
        workers = [
            asyncio.create_task(self.worker(i))
            for i in range(self.num_workers)
        ]
        return workers

    async def wait_completion(self):
        """Waits until all tasks are processed."""
        await self.queue.join()

Żewġ dettalji f’dan il-ħaddiem jisħqu l-attenzjoni tiegħek għax jidhru f’kull implimentazzjoni fid-dinja reali. Il-kontatur attempts jgħix fuq il-kompitu nnifsu, mhux fuq il-ħaddiem, u dan jippermetti li kwalunkwe ħaddiem ieħor jieħu kompitu mqiegħed lura fil-kwija mingħajr ma jitlif l-istorja tiegħu. Is-sejħa task_done() tinsab ġewwa blokk finally biex tiggarantixxi li l-kwija qatt ma tibqa’ mwaqqfa għal żmien indefinit jekk eċċezzjoni mhux mistennija taqbeż il-blokk except: mingħajrha, join() li qatt ma tirritorna hija s-sintomu, u hija diffiċli ħafna li tiddijanjożżaha.

Fuq in-naħa ta’ min isejjaħ (caller), l-użu huwa sempliċi: ibda l-ħaddiema, daħħal il-kompiti fil-kwija, stenna, iġbor ir-riżultati, u waqqaf kollox.

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

    # Add tasks
    for i, doc in enumerate(documents):
        task = Task(
            id=f"doc-{i}",
            prompt=f"Summarize this document: {doc}",
        )
        await queue.add(task)

    # Wait for completion
    await queue.wait_completion()

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

    # Stop workers
    for w in workers:
        w.cancel()

Ir-Rispett tal-Kwoti Minflok il-Ħabt Magħhom

OpenAI timponi żewġ limiti simultanji: talbiet kull minuta u tokens kull minuta. Pool ta’ għaxar ħaddiema li jibgħatu kull ma jistgħu se jolqtu wieħed jew l-ieħor, jirċievu żbalji ta’ limitu ta’ rata (rate limit errors), jippruvaw mill-ġdid, u jaggravaw il-konġestjoni. Huwa aħjar li tbaxxi l-veloċità volontarjament ‘il fuq fil-fluss milli tiġi miċħud ‘l isfel fil-fluss.

Il-limitatur hawn taħt japplika “token bucket” fuq tieqa li tiżżerżaq ta’ minuta waħda. Iżomm żewġ storji—timestamps ta’ talbiet riċenti u pari ta’ timestamp/token—jnaddaf l-entrati li ħarġu mit-tieqa, imbagħad jistenna jekk wieħed mil-limiti jiġi miksur. Il-lock ta’ asyncio huwa essenzjali: mingħajru, għaxar ħaddiema jevalwaw l-istess sitwazzjoni simultanjament u l-għaxra kollha jiddeċiedu li għad hemm spazju.

import asyncio
import time

class RateLimiter:
    """Rate limiter based on a 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):
        """Waits if necessary to respect limits."""
        async with self.lock:
            now = time.time()
            window = 60.0

            # Clean up entries outside the window
            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
            ]

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

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

Il-parametru estimated_tokens jistħoqqilu kelma: ma tkunx taf l-ispiża attwali sakemm tasal ir-risposta, allura taħdem b’estima. Agħmilha ġeneruża minflok preċiża. Li sistematikament tistma inqas mill-verità tfisser li qed tiddiżattiva l-protezzjoni eżattament meta tkun utli.

Ir-Ritorn Immedjat tal-Kontroll

Għal ipproċessar li jieħu diversi minuti, li tagħmel klijent HTTP jistenna m’għadx fattibbli: il-limiti ta’ żmien (timeouts) tal-proxy, tal-browser u tal-load balancer jaħdmu qabel ma tispiċċa. Il-mudell tal-webhook ibiddel ir-responsabbiltà. L-endpoint tiegħek jaċċetta t-talba, jirritorna immedjatament ID tal-kompitu, u jinnotifika lis-sejjaħ meta r-riżultat ikun jeżisti, mingħajr ma jeħtieġ polling perjodiku.

from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

@app.post("/api/analyze")
async def start_analysis(
    request: dict,
    background_tasks: BackgroundTasks,
):
    """Starts a background analysis and notifies 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,
):
    """Runs the analysis and sends the result 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,
            })

Dejjem aħżen l-ID irritornat u l-istat assoċjat f’post durabbli. Webhook jista’ jintilef, u s-sejjaħ irid iżomm il-kapaċità li jiġbed ir-riżultat innifsu.

Punti Ewlenin

  • Uża kwijiet asinkroni biex tissepara l-inġestjoni mill-ipproċessar
  • Implimenta limitatur ta’ rata biex tirrispetta l-kwoti ta’ OpenAI
  • Iġġesti t-tentattivi mill-ġdid b’backoff esponenzjali fil-ħaddiema tiegħek
  • Għal kompiti li jdumu ħafna, ippreferi mudell ta’ webhook fuq il-polling