Salt la conținutul principal
Română— Alege o limbă
Meniu

Async și bune practici

Lecția 13 din 14 Actualizată 2 noiembrie 2026 Avansat
Pe această pagină
  1. I/O asincron: o cerință tehnică
  2. Alegeți librării native asincrone
  3. Când nu există o versiune asincronă
  4. Proiectarea unor activități curate
  5. Puncte cheie

I/O asincron: o cerință tehnică

Toate activitățile din Mistral Workflows trebuie să utilizeze operațiuni de intrare/ieșire asincrone. Aceasta nu este o recomandare de stil, ci o constrângere tehnică. Un apel sincron blocant, precum requests.post(), îngheață worker-ul și împiedică executarea oricărei alte activități.

Această cerință decurge din arhitectura worker-ului, care execută activitățile în cadrul unei bucle de evenimente asyncio. Atunci când o corutină așteaptă asincron un răspuns de rețea, ea cedează controlul buclei, permițând altor activități să progreseze. Un apel sincron, dimpotrivă, nu cedează nimic.

import requests

# INCORECT: Blochează întregul worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() este sincron — blochează bucla de evenimente
    response = requests.post(url, json={"query": "test"})
    return response.json()

Simptomul în producție poate fi confuz: lansați zece activități în paralel cu asyncio.gather, dar acestea se execută de fapt una după alta. Dacă fiecare așteaptă două secunde un API remote, veți măsura douăzeci de secunde în loc de cele două așteptate, fără ca nicio eroare să fie ridicată.

Alegeți librării native asincrone

Soluția constă în înlocuirea fiecărei librării blocante cu echivalentul său asincron. Pentru apelurile HTTP, httpx este alegerea implicită.

import httpx

# CORECT: Non-blocant
@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()

aiohttp servește aceluiași scop, având un API ușor diferit, bazat pe sesiuni.

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()

Pentru bazele de date, asyncpg înlocuiește psycopg2 pentru PostgreSQL. Observați blocul try/finally: conexiunea trebuie închisă chiar dacă interogarea ridică o excepție. În caz contrar, reîncercările succesive vor epuiza pool-ul de conexiuni.

import asyncpg

# CORECT: Driver asincron pentru PostgreSQL
@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()

Accesul la fișiere urmează aceeași logică cu aiofiles, chiar și pentru fișiere mici unde ați putea fi tentați să continuați să utilizați open().

import aiofiles

# CORECT: Citire asincronă de fișiere
@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)}

Nici SDK-ul Mistral nu face excepție: fiecare metodă are o variantă cu sufixul _async, iar aceea este cea pe care trebuie să o apelați dintr-o activitate.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Utilizați complete_async, NU complete
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Păstrați acest tabel de corespondență la îndemână în timpul revizuirilor de cod: orice linie din coloana stângă identificată într-o activitate reprezintă un potențial bug de performanță.

OperațiuneIncorect (blocant)Corect (asincron)
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()
Fișiereopen()aiofiles.open()
Sleeptime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Când nu există o versiune asincronă

Unele librării de business, cum ar fi un SDK proprietar sau un client legacy, pur și simplu nu oferă o variantă asincronă. În aceste cazuri, asyncio.to_thread() vă permite să rulați codul blocant într-un fir de execuție separat, fără a îngheța bucla de evenimente.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Înfășoară un apel blocant într-un fir de execuție."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Acesta este un compromis, nu o soluție echivalentă: fiecare apel consumă un fir de execuție din pool, care are o dimensiune finită. Pentru o activitate apelată masiv în paralel, mutați doar gâtul de sticlă, nu îl eliminați. Preferați întotdeauna o librărie nativ asincronă atunci când una există.

Proiectarea unor activități curate

Dincolo de asincronie, patru obiceiuri disting o activitate robustă de una care vă va costa ore de depanare.

Primul este domeniul de aplicare. O activitate trebuie să aibă una și singură responsabilitate, deoarece ea constituie și unitatea de reîncercare și persistență: o activitate „catch-all“ care eșuează în timpul trimiterii unui e-mail va relua extracția și analiza de la început.

# BINE: Fiecare activitate are o responsabilitate clară
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# RĂU: Activitate catch-all
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # extracție
    sentiment = ...  # analiză
    # trimitere e-mail
    # salvare în DB
    pass

Al doilea privește resursele. Managerul de context async with garantează închiderea clientului chiar dacă apare o excepție, lucru pe care apelurile manuale îl uită inevitabil mai devreme sau mai târziu.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Utilizați async with pentru a garanta închiderea
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Clientul este închis automat aici
    return response.json()

Al treilea este mai subtil: nu toate erorile merită o reîncercare. Un timeout, un 429 sau un 500 sunt tranzitorii și ar trebui să propagate eroarea pentru a declanșa o reîncercare. O eroare 4xx indică însă o cerere invalidă pe care trei reîncercări nu o vor rezolva. În schimb, returnați un rezultat explicit și lăsați workflow-ul să decidă.

@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  # Va fi reîncercat de platformă
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Limitare de rată — va fi reîncercat
            elif e.response.status_code >= 500:
                raise  # Eroare de server — va fi reîncercat
            else:
                # Eroare de client (4xx) — nu reîncerca
                return {"status": "error", "code": e.response.status_code}

În final, al patrulea obicei decurge din limita de 2 MB per invocare: returnați doar ceea ce workflow-ul are nevoie pentru a decide pasul următor. Un contor, un eșantion și URL-ul către rezultatul complet sunt aproape întotdeauna suficiente.

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

    # Returnați doar ceea ce are nevoie workflow-ul
    return {
        "item_count": len(data),
        "summary": data[:10],  # Doar primele 10
        "full_url": await upload_results(data)
    }

Puncte cheie

  • I/O asincron este obligatoriu: utilizați httpx, asyncpg, aiofiles în locul echivalentelor lor sincrone
  • Apelurile blocante (requests, psycopg2, open) îngheață întregul worker
  • Utilizați asyncio.to_thread() doar ca ultimă soluție pentru librăriile fără versiune asincronă
  • Fiecare activitate trebuie să aibă o singură responsabilitate clară
  • Închideți întotdeauna conexiunile cu async with
  • Gestionați erorile explicit: unele trebuie reîncercate, altele nu
  • Limitați dimensiunile returnate pentru a rămâne sub limita de 2 MB