Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Asynchronní I/O a osvědčené postupy

Lekce 13 z 14 Aktualizováno 2. listopadu 2026 Pokročilý
Na této stránce
  1. Asynchronní I/O: Technický požadavek
  2. Volba nativně asynchronních knihoven
  3. Když neexistuje asynchronní verze
  4. Návrh čistých aktivit
  5. Klíčové poznatky

Asynchronní I/O: Technický požadavek

Všechny aktivity v Mistral Workflows musí používat asynchronní operace vstupů/výstupů. Není to jen doporučení stylu; je to technické omezení. Blokující synchronní volání, jako je requests.post(), zmrazí worker a zabrání spuštění jakékoli jiné aktivity.

Tento požadavek vyplývá z architektury workeru, který spouští aktivity uvnitř smyčky událostí asyncio. Když korutina asynchronně čeká na síťovou odpověď, vrátí řízení zpět do smyčky a umožní pokračování ostatním aktivitám. Synchronní volání naproti tomu nic neuvolní.

import requests

# ŠPATNĚ: Blokuje celého workeru
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() je synchronní — blokuje smyčku událostí
    response = requests.post(url, json={"query": "test"})
    return response.json()

Projev v produkci může být matoucí: spustíš deset aktivit paralelně pomocí asyncio.gather, ale ve skutečnosti se provedou jedna po druhé. Pokud každá čeká dvě sekundy na vzdálené API, naměříš dvacet sekund místo očekávaných dvou, aniž by došlo k chybám.

Volba nativně asynchronních knihoven

Řešením je nahradit každou blokující knihovnu jejím asynchronním ekvivalentem. Pro HTTP volání je výchozí volbou httpx.

import httpx

# SPRÁVNĚ: Neblokující
@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 slouží stejnému účelu s mírně odlišným API založeným na relací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()

Pro databáze nahrazuje asyncpg knihovnu psycopg2 pro PostgreSQL. Všimni si bloku try/finally: připojení se musí uzavřít, i když dotaz vyvolá výjimku. Jinak successive retry vyčerpají pool připojení.

import asyncpg

# SPRÁVNĚ: Asynchronní ovladač 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()

Přístup k souborům funguje na stejném principu s aiofiles, a to i pro malé soubory, kde bys mohl mít chuť stále používat open().

import aiofiles

# SPRÁVNĚ: Asynchronní čtení souboru
@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 není výjimkou: každá metoda má variantu s příponou _async a právě tu musíš volat z aktivity.

from mistralai.client import Mistral

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

Měj tuto mapovací tabulku po ruce během code review: jakýkoli řádek z levého sloupce nalezený v aktivitě je potenciální chybou výkonu.

OperaceŠpatně (blokující)Správně (asynchronní)
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()
Souboryopen()aiofiles.open()
Spánektime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Když neexistuje asynchronní verze

Některé obchodní knihovny, jako je proprietární SDK nebo starý klient, prostě nenabízejí asynchronní variantu. V těchto případech ti asyncio.to_thread() umožní spustit blokující kód v samostatném vlákně bez zmrazení smyčky událostí.

import asyncio
from some_library import blocking_function

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

Jde o kompromis, nikoli o ekvivalentní řešení: každé volání spotřebuje vlákno z poolu, který má konečnou velikost. Pro aktivitu volanou masivně paralelně pouze přesuneš úzké hrdlo, místo abys jej odstranil. Vždy upřednostni nativně asynchronní knihovnu, pokud existuje.

Návrh čistých aktivit

Kromě asynchronnosti rozlišují robustní aktivitu od té, která tě bude stát hodiny ladění, čtyři návyky.

Prvním je rozsah působnosti. Aktivita by měla mít jednu a pouze jednu odpovědnost, protože je také jednotkou pro opakování a perzistenci: univerzální aktivita, která selže při odesílání e-mailu, znovu přehraje extrakci a analýzu od začátku.

# DOBŘE: Každá aktivita má jasnou odpovědnost
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# ŠPATNĚ: Univerzální aktivita
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # extrakce
    sentiment = ...  # analýza
    # odeslat e-mail
    # uložit do DB
    pass

Druhý se týká zdrojů. Kontextový manažer async with zaručí uzavření klienta, i když dojde k výjimce, což manuální volání dříve či později nevyhnutelně zapomenou.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Použij async with pro zaručení uzavření
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Klient je zde automaticky uzavřen
    return response.json()

Třetí je subtilnější: ne všechny chyby si zaslouží opakování. Časový limit, stav 429 nebo 500 jsou přechodné a měly by bublat nahoru, aby spustily retry. Chyba 4xx však indikuje neplatný požadavek, který tři opakování neopraví. Místo toho vrať explicitní výsledek a nech rozhodnutí na workflow.

@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  # Omezení rychlosti — bude zopakováno
            elif e.response.status_code >= 500:
                raise  # Chyba serveru — bude zopakováno
            else:
                # Chyba klienta (4xx) — neopakovat
                return {"status": "error", "code": e.response.status_code}

Nakonec, čtvrtý návyk vyplývá z limitu 2 MB na vyvolání: vrať pouze to, co workflow skutečně potřebuje k rozhodnutí o dalším kroku. Počet, ukázka a URL k úplnému výsledku jsou téměř vždy dostatečné.

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

    # Vrať pouze to, co workflow potřebuje
    return {
        "item_count": len(data),
        "summary": data[:10],  # Pouze prvních 10
        "full_url": await upload_results(data)
    }

Klíčové poznatky

  • Asynchronní I/O je povinné: používej httpx, asyncpg, aiofiles místo jejich synchronních ekvivalentů
  • Blokující volání (requests, psycopg2, open) zmrazí celého workeru
  • Použij asyncio.to_thread() jako poslední možnost pro knihovny bez asynchronní verze
  • Každá aktivita musí mít jednu jasnou odpovědnost
  • Vždy uzavírej připojení pomocí async with
  • Zacházej s chybami explicitně: některé by se měly opakovat, jiné ne
  • Omez velikost návratových dat, abys zůstal pod limitem 2 MB