Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

Async en best practices

Les 13 van 14 Bijgewerkt op 2 november 2026 Gevorderd
Op deze pagina
  1. Async I/O: een technische vereiste
  2. Kies native asynchrone bibliotheken
  3. Wanneer er geen async-versie bestaat
  4. Het ontwerpen van schone activiteiten
  5. Belangrijkste punten

Async I/O: een technische vereiste

Alle activiteiten in Mistral Workflows moeten asynchrone input/output-bewerkingen gebruiken. Dit is geen stijladvies, maar een technische beperking. Een blokkerende synchrone aanroep zoals requests.post() bevriest de worker en verhindert dat andere activiteiten worden uitgevoerd.

Deze vereiste vloeit voort uit de architectuur van de worker, die activiteiten uitvoert binnen een asyncio-event loop. Wanneer een coroutine asynchroon wacht op een netwerkontvangst, geeft deze de controle terug aan de loop, zodat andere activiteiten kunnen doorgaan. Een synchrone aanroep geeft daarentegen niets vrij.

import requests

# ONJUIST: Blokkeert de volledige worker
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() is synchroon — het blokkeert de event loop
    response = requests.post(url, json={"query": "test"})
    return response.json()

Het symptoom in productie kan verwarrend zijn: u start tien activiteiten parallel met asyncio.gather, maar ze worden eigenlijk één voor één uitgevoerd. Als elk twee seconden wacht op een externe API, meet u twintig seconden in plaats van de verwachte twee, zonder dat er fouten worden gegenereerd.

Kies native asynchrone bibliotheken

De oplossing is om elke blokkerende bibliotheek te vervangen door het asynchrone equivalent. Voor HTTP-aanroepen is httpx de standaardkeuze.

import httpx

# JUIST: Niet-blokkerend
@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 dient hetzelfde doel met een iets andere API gebaseerd op sessies.

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

Voor databases vervangt asyncpg psycopg2 voor PostgreSQL. Let op het try/finally-blok: de verbinding moet worden gesloten, zelfs als de query een uitzondering veroorzaakt. Anders zullen opeenvolgende nieuwe pogingen de verbindingspool uitputten.

import asyncpg

# JUIST: Asynchrone PostgreSQL-driver
@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()

Bestandstoegang volgt dezelfde logica met aiofiles, zelfs voor kleine bestanden waarbij u in de verleiding zou kunnen komen om open() te blijven gebruiken.

import aiofiles

# JUIST: Asynchroon bestandslezen
@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)}

De Mistral SDK vormt hierop geen uitzondering: elke methode heeft een variant met het achtervoegsel _async, en dat is degene die u vanuit een activiteit moet aanroepen.

from mistralai.client import Mistral

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

Houd deze mappingtabel bij de hand tijdens code reviews: elke regel uit de linkerkolom die in een activiteit wordt aangetroffen, is een potentiële prestatiebug.

BewerkingOnjuist (blokkerend)Juist (async)
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()
Bestandenopen()aiofiles.open()
Slaapstandtime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Wanneer er geen async-versie bestaat

Sommige zakelijke bibliotheken, zoals een propriëtaire SDK of een legacy-client, bieden eenvoudigweg geen asynchrone variant. In deze gevallen kunt u met asyncio.to_thread() de blokkerende code in een aparte thread uitvoeren zonder de event loop te bevriezen.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Wrapt een blokkerende aanroep in een thread."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Dit is een compromis, geen gelijkwaardige oplossing: elke aanroep verbruikt een thread uit de pool, die een eindige grootte heeft. Voor een activiteit die massaal parallel wordt aangeroepen, verplaatst u slechts de bottleneck in plaats van deze weg te nemen. Geef altijd de voorkeur aan een native asynchrone bibliotheek wanneer deze beschikbaar is.

Het ontwerpen van schone activiteiten

Naast asynchroniteit onderscheiden vier gewoonten een robuuste activiteit van een activiteit die u uren debuggen zal kosten.

De eerste is scope. Een activiteit moet één en slechts één verantwoordelijkheid hebben, omdat het ook de eenheid is voor opnieuw proberen en persistentie: een alles-in-één-activiteit die faalt tijdens het verzenden van een e-mail, zal de extractie en analyse vanaf het begin opnieuw afspelen.

# GOED: Elke activiteit heeft een duidelijke verantwoordelijkheid
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# SLECHT: Alles-in-één-activiteit
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # extractie
    sentiment = ...  # analyse
    # e-mail verzenden
    # opslaan in DB
    pass

De tweede betreft resources. De async with context manager garandeert dat de client wordt gesloten, zelfs als er een uitzondering optreedt, iets wat bij handmatige aanroepen sooner or later onvermijdelijk wordt vergeten.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Gebruik async with om sluiting te garanderen
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # De client wordt hier automatisch gesloten
    return response.json()

De derde is subtieler: niet alle fouten verdienen een nieuwe poging. Een time-out, een 429 of een 500 zijn tijdelijk en moeten worden doorgegeven om een nieuwe poging te activeren. Een 4xx-fout geeft echter een ongeldig verzoek aan dat drie keer opnieuw proberen niet zal oplossen. Retourneer in plaats daarvan een expliciet resultaat en laat de workflow beslissen.

@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  # Zal opnieuw worden geprobeerd door het platform
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Rate limited — zal opnieuw worden geprobeerd
            elif e.response.status_code >= 500:
                raise  # Serverfout — zal opnieuw worden geprobeerd
            else:
                # Clientfout (4xx) — niet opnieuw proberen
                return {"status": "error", "code": e.response.status_code}

Tot slot vloeit de vierde gewoonte voort uit de limiet van 2 MB per aanroep: retourneer alleen wat de workflow daadwerkelijk nodig heeft om de volgende stap te bepalen. Een telling, een steekproef en de URL naar het volledige resultaat zijn bijna altijd voldoende.

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

    # Retourneer alleen wat de workflow nodig heeft
    return {
        "item_count": len(data),
        "summary": data[:10],  # Alleen de eerste 10
        "full_url": await upload_results(data)
    }

Belangrijkste punten

  • Async I/O is verplicht: gebruik httpx, asyncpg, aiofiles in plaats van hun synchrone equivalenten
  • Blokkerende aanroepen (requests, psycopg2, open) bevriezen de volledige worker
  • Gebruik asyncio.to_thread() als laatste redmiddel voor bibliotheken zonder async-versie
  • Elke activiteit moet één duidelijke verantwoordelijkheid hebben
  • Sluit verbindingen altijd af met async with
  • Behandel fouten expliciet: sommige moeten opnieuw worden geprobeerd, andere niet
  • Beperk de retourgroottes om onder de limiet van 2 MB te blijven