Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Asynchrónne operácie a osvedčené postupy

Lekcia 13 z 14 Aktualizované 2. novembra 2026 Pokročilý
Na tejto strane
  1. Asynchrónny I/O: Technická požiadavka
  2. Vyberaj natívne asynchrónne knižnice
  3. Keď neexistuje asynchrónna verzia
  4. Navrhovanie čistých aktivít
  5. Kľúčové poznatky

Asynchrónny I/O: Technická požiadavka

Všetky aktivity v Mistral Workflows musia používať asynchrónne operácie vstupu/výstupu. Nie je to len odporúčanie štýlu; je to technické obmedzenie. Blokujúci synchronný volanie, ako je requests.post(), zmrazí worker a zabráni spusteniu akejkoľvek inej aktivity.

Táto požiadavka vyplýva z architektúry workeru, ktorý vykonáva aktivity v rámci slučky udalostí asyncio. Keď korutína asynchrónne čaká na odpoveď zo siete, vráti riadenie späť do slučky a umožní pokračovanie iným aktivitám. Synchronné volanie naopak nič neuvolní.

import requests

# NESPRÁVNE: Blokuje celého workera
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() je synchronné — blokuje slučku udalostí
    response = requests.post(url, json={"query": "test"})
    return response.json()

Príznak v produkcii môže byť mätúci: spustíš desať aktivít paralelne pomocou asyncio.gather, no v skutočnosti sa vykonajú jedna po druhej. Ak každá čaká dve sekundy na vzdialené API, nameriaš dvadsať sekúnd namiesto očakávaných dvoch, pričom sa nevyhodí žiadna chyba.

Vyberaj natívne asynchrónne knižnice

Riešením je nahradiť každú blokujúcu knižnicu jej asynchrónnym ekvivalentom. Pre HTTP volania je štandardnou voľbou httpx.

import httpx

# SPRÁVNE: Neblokujúce
@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 slúži na rovnaký účel s mierne odlišným API založeným na reláciách.

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

Pre databázy nahrádza asyncpg knižnicu psycopg2 pre PostgreSQL. Všimni si blok try/finally: pripojenie sa musí uzavrieť aj v prípade, že dotaz vyhodí výnimku. Inak successive retry vyčerpajú pool pripojení.

import asyncpg

# SPRÁVNE: Asynchrónny ovládač pre 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()

Prístup k súborom funguje na rovnakom princípe s aiofiles, dokonca aj pre malé súbory, kde by ťa mohlo lákať pokračovať v používaní open().

import aiofiles

# SPRÁVNE: Asynchrónne čítanie súboru
@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)}

Ani samotné Mistral SDK nie je výnimkou: každá metóda má variantu s príponou _async a práve tú musíš volať z aktivity.

from mistralai.client import Mistral

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

Maj túto mapovaciu tabuľku poruke počas kódových revízií: akýkoľvek riadok z ľavého stĺpca nájdený v aktivite je potenciálnou chybou výkonu.

OperáciaNesprávne (blokujúce)Správne (asynchrónne)
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()
Súboryopen()aiofiles.open()
Čakanietime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Keď neexistuje asynchrónna verzia

Niektoré business knižnice, ako proprietárne SDK alebo starší klient, jednoducho nenabízajú asynchrónnu variantu. V týchto prípadoch ti asyncio.to_thread() umožní spustiť blokujúci kód v samostatnom vlákne bez zmrazenia slučky udalostí.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Zabalí blokujúce volanie do vlákna."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Je to kompromis, nie rovnocenné riešenie: každé volanie spotrebuje vlákno z poolu, ktorý má konečnú veľkosť. Pre aktivitu volanú masívne paralelne len presunieš úzke hrdlo, namiesto toho, aby si ho odstránil. Vždy uprednostni natívne asynchrónnu knižnicu, ak existuje.

Okrem asynchrónnosti štyri návyky odlišujú robustnú aktivitu od tej, ktorá ťa bude stáť hodiny ladenia.

Prvým je rozsah. Aktivita by mala mať jednu a len jednu zodpovednosť, pretože je tiež jednotkou opakovania a perzistencie: catch-all aktivita, ktorá zlyhá pri odosielaní e-mailu, zopakuje extrakciu a analýzu od začiatku.

# DOBRÉ: Každá aktivita má jasnú zodpovednosť
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# ZLÉ: Catch-all aktivita
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # extrakcia
    sentiment = ...  # analýza
    # odoslať e-mail
    # uložiť do DB
    pass

Druhý sa týka zdrojov. Kontextový manažér async with garantuje uzavretie klienta aj v prípade výnimky, čo manuálne volania skôr či neskôr nevyhnutne zabudnú urobiť.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Použi async with na garantovanie uzavretia
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Klient sa tu automaticky uzavrie
    return response.json()

Tretí je jemnejší: nie všetky chyby si zaslúžia opakovanie. Časový limit, 429 alebo 500 sú prechodné a mali by sa preniesť vyššie, aby sa spustil retry. Chyba 4xx však indikuje neplatnú požiadavku, ktorú tri opakovania neopravia. Namiesto toho vráť explicitný výsledok a nechaj workflow rozhodnúť.

@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  # Platforma to zopakuje
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Obmedzená rýchlosť — zopakuje sa
            elif e.response.status_code >= 500:
                raise  # Chyba servera — zopakuje sa
            else:
                # Chyba klienta (4xx) — neopakovať
                return {"status": "error", "code": e.response.status_code}

Nakoniec, štvrtý návyk vyplýva z limitu 2 MB na jedno vyvolanie: vráť len to, čo workflow skutočne potrebuje na rozhodnutie o ďalšom kroku. Počet, vzorka a URL k úplnému výsledku sú takmer vždy dostatočné.

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

    # Vráť len to, čo workflow potrebuje
    return {
        "item_count": len(data),
        "summary": data[:10],  # Len prvých 10
        "full_url": await upload_results(data)
    }

Kľúčové poznatky

  • Asynchrónny I/O je povinný: používaj httpx, asyncpg, aiofiles namiesto ich synchronných ekvivalentov
  • Blokujúce volania (requests, psycopg2, open) zmrazia celého workera
  • Použi asyncio.to_thread() ako poslednú možnosť pre knižnice bez asynchrónnej verzie
  • Každá aktivita musí mať jednu jasnú zodpovednosť
  • Vždy uzatváraj pripojenia pomocou async with
  • Spracúvaj chyby explicitne: niektoré sa majú opakovať, iné nie
  • Obmedz veľkosť návratových hodnôt, aby si zostal pod limitom 2 MB