Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Asinhrono delovanje in najboljša praksa

Lekcija 13 od 14 Posodobljeno 2. november 2026 Napredni
Na tej strani
  1. Asinhroni V/I: Tehnična zahteva
  2. Izbira izvorno asinhronih knjižnic
  3. Ko asinhrona različica ne obstaja
  4. Načrtovanje čistih aktivnosti
  5. Ključne ugotovitve

Asinhroni V/I: Tehnična zahteva

Vse aktivnosti v Mistral Workflows morajo uporabljati asinhrone operacije vhodov/izhodov. To ni zgolj priporočilo za slog kodiranja, temveč tehnična omejitev. Blokirajoči sinhroni klic, kot je requests.post(), zamrzne delavca (worker) in prepreči izvajanje katere koli druge aktivnosti.

Ta zahteva izhaja iz arhitekture delavca, ki izvaja aktivnosti znotraj dogodkovne zanke asyncio. Ko korutina asinhrono čaka na omrežni odgovor, vrne nadzor zanki in omogoči nadaljevanje drugih aktivnosti. Sinhroni klic nasprotno ne vrne ničesar.

import requests

# NEPRAVILNO: Blokira celotnega delavca
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() je sinhron — blokira dogodkovno zanko
    response = requests.post(url, json={"query": "test"})
    return response.json()

Simptom v produkcijskem okolju je lahko zavajajoč: zaženeš deset aktivnosti vzporedno z asyncio.gather, vendar se dejansko izvajajo ena za drugo. Če vsaka čaka dve sekundi na oddaljeni API, izmeriš dvajset sekund namesto pričakovanih dveh, brez sproženih napak.

Izbira izvorno asinhronih knjižnic

Rešitev je zamenjava vsake blokirajoče knjižnice z njenim asinhronim ekvivalentom. Za klice HTTP je privzeta izbira httpx.

import httpx

# PRAVILNO: Ne-blokirajoče
@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 služi istemu namenu z nekoliko drugačnim API-jem, ki temelji na sejah.

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

Za baze podatkov asyncpg nadomešča psycopg2 za PostgreSQL. Opazi blok try/finally: povezava se mora zapreti tudi, če poizvedba sproži izjemo. V nasprotnem primeru bodo zaporedni poskusi ponovnega izvajanja izčrpali bazen povezav.

import asyncpg

# PRAVILNO: Asinhroni gonilnik za 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()

Dostop do datotek sledi isti logiki z aiofiles, celo za majhne datoteke, kjer bi te lahko zamikalo, da še vedno uporabljaš open().

import aiofiles

# PRAVILNO: Asinhrono branje datotek
@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)}

Tudi sam Mistral SDK ni izjema: vsaka metoda ima različico s pripono _async in prav to moraš klicati iz aktivnosti.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Uporabi 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}

Med pregledi kode imej pri roki to tabelo preslikav: vsaka vrstica iz levega stolpca, opažena v aktivnosti, je potencialna napaka pri zmogljivosti.

OperacijaNepravilno (blokirajoče)Pravilno (asinhrono)
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()
Datotekeopen()aiofiles.open()
Čakanjetime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Ko asinhrona različica ne obstaja

Nekatere poslovne knjižnice, kot so lastniški SDK-ji ali starejši odjemalci, preprosto ne ponujajo asinhrone različice. V teh primerih ti asyncio.to_thread() omogoča zagon blokirajoče kode v ločeni niti, ne da bi zamrznil dogodkovno zanko.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Ovije blokirajoči klic v nit."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

To je kompromis, ne enakovredna rešitev: vsak klic porabi nit iz bazena, ki ima končno velikost. Za aktivnost, ki se množično kliče vzporedno, le premakneš ozko grlo, namesto da bi ga odstranil. Vedno raje izberi izvorno asinhrono knjižnico, če obstaja.

Načrtovanje čistih aktivnosti

Poleg asinhronosti štiri navade ločijo robustno aktivnost od tiste, ki ti bo povzročila ure odpravljanja napak.

Prva je obseg. Aktivnost mora imeti eno in samo eno odgovornost, saj je hkrati enota za ponovni poskus in trajnost: aktivnost „vse-v-enem”, ki odpove med pošiljanjem e-pošte, bo od začetka znova izvedla ekstrakcijo in analizo.

# DOBRO: Vsaka aktivnost ima jasno odgovornost
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# SLABO: Aktivnost za vse
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # ekstrakcija
    sentiment = ...  # analiza
    # pošlji e-pošto
    # shrani v bazo
    pass

Druga se nanaša na vire. Upravitelj konteksta async with zagotavlja zaprtje odjemalca tudi ob pojavu izjeme, kar ročni klici prej ali slej neizogibno pozabijo.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Uporabi async with za zagotovilo zaprtja
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Odjemalec je tu samodejno zaprt
    return response.json()

Tretja je bolj subtilna: ne vse napake si zaslužijo ponovni poskus. Časovni potek, koda 429 ali 500 so prehodne napake in bi se morale dvigniti navzgor, da sprožijo ponovni poskus. Napaka 4xx pa kaže na neveljaven zahtevek, ki ga trije ponovni poskusi ne bodo popravili. Namesto tega vrni ekspliciten rezultat in prepusti odločitev delovnemu toku.

@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 bo to ponovno poskusila
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Omejitev hitrosti — bo ponovno poskušano
            elif e.response.status_code >= 500:
                raise  # Napaka strežnika — bo ponovno poskušano
            else:
                # Napaka odjemalca (4xx) — ne ponavljaj
                return {"status": "error", "code": e.response.status_code}

Končno, četrta navada izhaja iz omejitve 2 MB na priklic: vrni le tisto, kar delovni tok dejansko potrebuje za odločitev o naslednjem koraku. Število, vzorec in URL do polnega rezultata sta skoraj vedno dovolj.

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

    # Vrni le tisto, kar delovni tok potrebuje
    return {
        "item_count": len(data),
        "summary": data[:10],  # Le prvih 10
        "full_url": await upload_results(data)
    }

Ključne ugotovitve

  • Asinhroni V/I so obvezni: uporabi httpx, asyncpg, aiofiles namesto njihovih sinhronih ekvivalentov
  • Blokirajoči klici (requests, psycopg2, open) zamrznejo celotnega delavca
  • Uporabi asyncio.to_thread() kot zadnjo možnost za knjižnice brez asinhrone različice
  • Vsaka aktivnost mora imeti eno jasno odgovornost
  • Vedno zapri povezave z async with
  • Obravnavaj napake eksplicitno: nekatere je treba ponoviti, drugih ne
  • Omeji velikost vrnjenih podatkov, da ostaneš pod omejitvijo 2 MB