Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Aszinkron műveletek és bevált gyakorlatok

13. lecke 14 közül Frissítve 2026. november 2. Haladó
Ezen az oldalon
  1. Aszinkron I/O: Technikai követelmény
  2. Válassz natívan aszinkron könyvtárakat
  3. Ha nem létezik aszinkron verzió
  4. Tiszta tevékenységek tervezése
  5. Főbb megállapítások

Aszinkron I/O: Technikai követelmény

A Mistral Workflows összes tevékenységének aszinkron bemeneti/kimeneti műveleteket kell használnia. Ez nem stílusjavaslat, hanem technikai kényszer. Egy blokkoló szinkron hívás, mint például a requests.post(), lefagyasztja a munkást (worker), és megakadályozza bármely más tevékenység futását.

Ez a követelmény a munkás architektúrájából ered, amely egy asyncio eseményhurokban hajtja végre a tevékenységeket. Amikor egy korutin aszinkron módon vár egy hálózati válaszra, visszaadja a vezérlést a huroknak, lehetővé téve más tevékenységek folytatását. Ezzel szemben egy szinkron hívás semmit nem ad vissza.

import requests

# HELYTELEN: Blokkolja az egész munkást
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # A requests.post() szinkron — blokkolja az eseményhurkot
    response = requests.post(url, json={"query": "test"})
    return response.json()

A tünet éles környezetben zavaró lehet: tíz tevékenységet indítasz párhuzamosan az asyncio.gather segítségével, de azok valójában egymás után hajtódnak végre. Ha mindegyik két másodpercet vár egy távoli API-ra, akkor húsz másodpercet mérsz a várt két másodperc helyett, hibajelzés nélkül.

Válassz natívan aszinkron könyvtárakat

A megoldás az, hogy minden blokkoló könyvtárat lecserélsz annak aszinkron megfelelőjére. HTTP-hívások esetén az httpx az alapértelmezett választás.

import httpx

# HELYES: Nem blokkoló
@workflows.activity()
async def async_activity(url: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(url, json={"query": "test"})
    return response.json()

Az aiohttp ugyanerre a célra szolgál, kissé eltérő, munkameneteken alapuló API-val.

import aiohttp

@workflows.activity()
async def aiohttp_activity(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json={"query": "test"}) as response:
            return await response.json()

Adatbázisok esetén az asyncpg váltja le a psycopg2-t PostgreSQL-hez. Figyeld meg a try/finally blokkot: a kapcsolatnak le kell záródnia akkor is, ha a lekérdezés kivételt dob. Ellenkező esetben az ismétlődő újrapróbálkozások kimerítik a kapcsolatkészletet.

import asyncpg

# HELYES: Aszinkron PostgreSQL illesztőprogram
@workflows.activity()
async def async_db_query(user_id: str) -> dict:
    conn = await asyncpg.connect("postgresql://user:pass@localhost/db")
    try:
        row = await conn.fetchrow(
            "SELECT * FROM users WHERE id = $1", user_id
        )
        return dict(row) if row else {"error": "user not found"}
    finally:
        await conn.close()

A fájlhozzáférés ugyanígy működik az aiofiles segítségével, még kis fájlok esetén is, amikor esetleg kísértésbe esnél, hogy továbbra is az open()-t használd.

import aiofiles

# HELYES: Aszinkron fájlolvasás
@workflows.activity()
async def read_file_async(path: str) -> dict:
    async with aiofiles.open(path, mode="r") as f:
        content = await f.read()
    return {"content": content, "size": len(content)}

Maga a Mistral SDK sem kivétel: minden metódusnak létezik egy _async utótaggal ellátott változata, és ezt kell meghívnod egy tevékenységből.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Használd a complete_async metódust, NE a complete-et
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Tartsd kéznél ezt az összehasonlító táblázatot kódreviewk során: a bal oszlopból származó bármely sor, amelyet egy tevékenységben találsz, potenciális teljesítményhiba.

MűveletHelytelen (blokkoló)Helyes (aszinkron)
HTTPrequests.get()httpx.AsyncClient().get()
HTTPurllib.request.urlopen()aiohttp.ClientSession().get()
PostgreSQLpsycopg2.connect()asyncpg.connect()
MySQLmysql.connector.connect()aiomysql.connect()
Redisredis.Redis()redis.asyncio.Redis()
Fájlokopen()aiofiles.open()
Alvástime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Ha nem létezik aszinkron verzió

Egyes üzleti könyvtárak, mint például egy tulajdonosi SDK vagy egy elavult kliens, egyszerűen nem kínálnak aszinkron változatot. Ilyen esetekben az asyncio.to_thread() lehetővé teszi, hogy a blokkoló kódot egy külön szálban futtasd anélkül, hogy lefagyasztanád az eseményhurkot.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Becsomagol egy blokkoló hívást egy szálba."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Ez egy kompromisszum, nem egyenértékű megoldás: minden hívás fogyaszt egy szálat a készletből, amelynek véges a mérete. Ha egy tevékenységet masszívan párhuzamosítva hívsz meg, csupán áthelyezed a szűk keresztmetszetet, nem pedig megszünteted azt. Mindig részesítsd előnyben a natívan aszinkron könyvtárat, ha létezik ilyen.

Tiszta tevékenységek tervezése

Az aszinkronitás mellett négy szokás különbözteti meg a robusztus tevékenységet attól, amely óráknyi hibakeresésbe fog kerülni.

Az első a hatáskör. Egy tevékenységnek pontosan egy felelőssége legyen, mivel ez egyszerre az újrapróbálkozás és a perzisztencia egysége is: egy mindent magába foglaló tevékenység, amely e-mail küldése közben elbukik, újra lefuttatja a kinyerést és az elemzést is a legelejétől.

# JÓ: Minden tevékenységnek világos felelőssége van
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
    # ...
    pass

# ROSSZ: Mindent egyben tevékenység
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # kinyerés
    sentiment = ...  # elemzés
    # e-mail küldés
    # mentés az adatbázisba
    pass

A második az erőforrásokra vonatkozik. Az async with kontextuskezelő garantálja, hogy a kliens lezáródik még kivétel esetén is, amit a manuális hívások előbb-utóbb elfelejtenek.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Használd az async with blokkot a lezárás garantálásához
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # A kliens itt automatikusan lezáródik
    return response.json()

A harmadik finomabb: nem minden hiba érdemel újrapróbálkozást. Egy időtúllépés, egy 429-es vagy egy 500-as hiba átmeneti jellegű, és fel kell emelkednie (bubble up), hogy újrapróbálkozást váltson ki. Ezzel szemben egy 4xx-es hiba érvénytelen kérést jelez, amit három újrapróbálkozás sem fog megoldani. Ehelyett adj vissza egy explicit eredményt, és hagyd, hogy a munkafolyamat döntsön.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2),
    retry_policy_max_attempts=3,
)
async def robust_activity(params: dict) -> dict:
    async with httpx.AsyncClient(timeout=60) as client:
        try:
            response = await client.post(params["url"], json=params["data"])
            response.raise_for_status()
            return {"status": "success", "data": response.json()}
        except httpx.TimeoutException:
            raise  # A platform újrapróbálja
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Sebességkorlátozás — újrapróbálásra kerül
            elif e.response.status_code >= 500:
                raise  # Szerverhiba — újrapróbálásra kerül
            else:
                # Klienshiba (4xx) — ne próbáld újra
                return {"status": "error", "code": e.response.status_code}

Végül, a negyedik szokás a hívásonkénti 2 MB-os limitből ered: csak azt add vissza, amire a munkafolyamatnak ténylegesen szüksége van a következő lépés eldöntéséhez. Egy darabszám, egy minta és a teljes eredmény URL-címe szinte mindig elegendő.

@workflows.activity()
async def extract_data(source: str) -> dict:
    data = await retrieve_large_data(source)

    # Csak azt add vissza, amire a munkafolyamatnak szüksége van
    return {
        "item_count": len(data),
        "summary": data[:10],  # Csak az első 10 elem
        "full_url": await upload_results(data)
    }

Főbb megállapítások

  • Az aszinkron I/O kötelező: használd az httpx, asyncpg, aiofiles könyvtárakat szinkron megfelelőik helyett
  • A blokkoló hívások (requests, psycopg2, open) lefagyasztják az egész munkást
  • Használd az asyncio.to_thread() funkciót végső megoldásként olyan könyvtárakhoz, amelyeknek nincs aszinkron verziójuk
  • Minden tevékenységnek egyértelmű felelősséggel kell rendelkeznie
  • Mindig zárd le a kapcsolatokat az async with használatával
  • Kezeld explicit módon a hibákat: egyeseket újra kell próbálni, másokat nem
  • Korlátozd a visszatérési adatok méretét, hogy a 2 MB-os limit alatt maradj