Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Asünkroonne sisend/väljund ja parimad tavad

Õppetund 13 / 14 Värskendatud 2. november 2026 Edasijõudnutele
Sellel lehel
  1. Asünkroonne I/O: tehniline nõue
  2. Vali loomupäraselt asünkroonsed teegid
  3. Kui asünkroonset versiooni pole
  4. Puhtate tegevuste kujundamine
  5. Peamised punktid

Asünkroonne I/O: tehniline nõue

Kõik Mistral Workflowsi tegevused peavad kasutama asünkroonseid sisendi/väljundi operatsioone. See ei ole stiilisoovitus, vaid tehniline piirang. Blokeeriv sünkroonne väljakutse, nagu requests.post(), külmutab töötaja ja takistab teiste tegevuste käivitumist.

See nõue tuleneb töötaja arhitektuurist, mis käivitab tegevusi asyncio sündmuste silmuses. Kui korutiin ootab asünkroonselt võrguvastust, annab see juhtimise tagasi silmusele, võimaldades teistel tegevustel jätkuda. Sünkroonne väljakutse seevastu ei loovuta midagi.

import requests

# VALE: Blokeerib kogu töötaja
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() on sünkroonne — see blokeerib sündmuste silmuse
    response = requests.post(url, json={"query": "test"})
    return response.json()

Sümptom tootmiskeskkonnas võib olla segadusttekitav: käivitad kümme tegevust paralleelselt käsuga asyncio.gather, kuid need tegelikult käivituvad üksteise järel. Kui üks ootab kahe sekundi jooksul kaug-API vastust, mõõdad kakskümmend sekundit eeldatud kahe asemel, ilma et ühtegi viga tõstetaks.

Vali loomupäraselt asünkroonsed teegid

Lahendus seisneb iga blokeeriva teegi asendamises selle asünkroonse ekvivalendiga. HTTP-päringute jaoks on vaikimisi valikuks httpx.

import httpx

# ÕIGE: Mitteblokeeriv
@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 täidab sama eesmärki, kasutades sessioonidel põhinevat veidi erinevat API-t.

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

Andmebaaside jaoks asendab asyncpg PostgreSQLi puhul psycopg2-t. Pane tähele try/finally plokki: ühendus peab sulguma isegi siis, kui päring tõstab erindi. Vastasel juhul ammendavad järjestikused uuestiproovimised ühenduste basseini.

import asyncpg

# ÕIGE: Asünkroonne PostgreSQLi draiver
@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()

Failide lugemine järgib sama loogikat aiofiles-iga, isegi väikeste failide puhul, kus võiks olla kiusatus kasutada jätkuvalt open()-i.

import aiofiles

# ÕIGE: Asünkroonne faili lugemine
@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)}

Ka Mistrali SDK ei ole erand: igal meetodil on _async-liitega variant ja just seda pead tegevuses kutsuma.

from mistralai.client import Mistral

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

Hoia see vastavustabel koodiülevaatuste jaoks käepärast: iga rida vasakust veerust, mis tegevuses leitakse, on potentsiaalne jõudlusviga.

OperatsioonVale (blokeeriv)Õige (asünkroonne)
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()
Failidopen()aiofiles.open()
Ooteaegtime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Kui asünkroonset versiooni pole

Mõned äriraamatukogud, nagu omanimeline SDK või vana klient, lihtsalt ei paku asünkroonset varianti. Sellistel juhtudel võimaldab asyncio.to_thread() käivitada blokeerivat koodi eraldi lõimes, külmutamata sündmuste silmust.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Mähib blokeeriva väljakutse lõimesse."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

See on kompromiss, mitte samaväärne lahendus: iga väljakutse tarbib lõimede basseinist ühe lõime, mille suurus on lõplik. Massiivselt paralleelselt kutsutava tegevuse puhul liigutad lihtalt kitsaskohta, mitte ei eemalda seda. Eelista alati loomupäraselt asünkroonset teeki, kui see on olemas.

Puhtate tegevuste kujundamine

Lisaks asünkroonsusele eristab robustset tegevust sellisest, mis maksab sulle tunde silumist, neli harjumust.

Esimene on ulatus. Tegevusel peaks olema üks ja ainult üks vastutusala, sest see on ka uuestiproovimise ja püsivuse üksus: kõik-ühes tegevus, mis e-kirja saatmise ajal nurjub, kordab ekstraheerimist ja analüüsi algusest peale.

# HEA: Igal tegevusel on selge vastutus
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# VALE: Kõikehõlmav tegevus
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # ekstraheerimine
    sentiment = ...  # analüüs
    # saada e-kiri
    # salvesta andmebaasi
    pass

Teine puudutab ressursse. Kontekstihaldur async with garanteerib, et klient suletakse isegi erindi korral, mida käsitsi tehtud väljakutsed varem või hiljem unustavad.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Kasuta async with, et garanteerida sulgemine
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Klient suletakse siin automaatselt
    return response.json()

Kolmas on peenem: mitte kõik vead ei väärí uuestiproovimist. Aegumine, 429 või 500 on ajutised ja peaksid tõusma üles, et käivitada uuestiproovimine. 4xx viga näitab aga vigast päringut, mida kolm korda uuesti proovimine ei paranda. Selle asemel tagasta selge tulemus ja lase töövoogul otsustada.

@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  # Platvorm proovib uuesti
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Kiiruse piirang — proovitakse uuesti
            elif e.response.status_code >= 500:
                raise  # Serveri viga — proovitakse uuesti
            else:
                # Kliendi viga (4xx) — ära proovi uuesti
                return {"status": "error", "code": e.response.status_code}

Lõpuks tuleneb neljas harjumus 2 MB piirangust kutse kohta: tagasta ainult see, mida töövoog tegelikult vajab järgmise sammu otsustamiseks. Loend, näidis ja URL täistulemusele on peaaegu alati piisavad.

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

    # Tagasta ainult see, mida töövoog vajab
    return {
        "item_count": len(data),
        "summary": data[:10],  # Ainult esimesed 10
        "full_url": await upload_results(data)
    }

Peamised punktid

  • Asünkroonne I/O on kohustuslik: kasuta httpx, asyncpg, aiofiles nende sünkroonsete ekvivalentide asemel
  • Blokeerivad väljakutsed (requests, psycopg2, open) külmutavad kogu töötaja
  • Kasuta asyncio.to_thread() viimase abinõuna teekide puhul, millel puudub asünkroonne versioon
  • Igal tegevusel peab olema üks selge vastutusala
  • Sulge ühendused alati käsuga async with
  • Käitle vigu selgelt: mõnda tuleks uuesti proovida, teisi mitte
  • Piira tagastatavate andmete suurust, et jääda alla 2 MB piiri