Arkitettura Asinkrona u Kwijiet
F'din il-paġna
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