Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Async og bedste praksis

Lektion 13 af 14 Opdateret 2. november 2026 Avanceret
På denne side
  1. Async I/O: Et teknisk krav
  2. Vælg biblioteker, der er asynkrone fra bunden
  3. Når ingen async-version findes
  4. Design af ryddelige aktiviteter
  5. Vigtige pointer

Async I/O: Et teknisk krav

Alle aktiviteter i Mistral Workflows skal bruge asynkrone input/output-operationer. Dette er ikke en stilanbefaling, men et teknisk krav. Et blokerende synkront kald som requests.post() fryser workeren og forhindrer enhver anden aktivitet i at køre.

Dette krav udspringer af workerens arkitektur, som eksekverer aktiviteter inden for en asyncio-begivenhedssløjfe (event loop). Når en coroutine venter på et netværkssvar asynkront, afleverer den kontrollen tilbage til sløjfen, så andre aktiviteter kan fortsætte. Et synkront kald afleverer derimod ingenting.

import requests

# FORKERT: Blokerer hele workeren
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() er synkron — den blokerer begivenhedssløjfen
    response = requests.post(url, json={"query": "test"})
    return response.json()

Symptomet i produktion kan være forvirrende: du lancerer ti aktiviteter parallelt med asyncio.gather, men de eksekveres faktisk én efter én. Hvis hver venter to sekunder på et eksternt API, måler du tyve sekunder i stedet for de forventede to, uden at der rejses fejl.

Vælg biblioteker, der er asynkrone fra bunden

Løsningen er at erstatte ethvert blokerende bibliotek med dets asynkrone modstykke. Til HTTP-kald er httpx standardvalget.

import httpx

# KORREKT: Ikke-blokerende
@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 tjener samme formål med en lidt anden API baseret på sessioner.

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

Til databaser erstatter asyncpg psycopg2 til PostgreSQL. Bemærk try/finally-blokken: forbindelsen skal lukkes, selv hvis forespørgslen rejser en undtagelse. Ellers vil gentagne forsøg udtømme forbindelsespuljen.

import asyncpg

# KORREKT: Asynkron 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()

Filadgang følger samme logik med aiofiles, selv for små filer, hvor du måske fristes til at fortsætte med at bruge open().

import aiofiles

# KORREKT: Asynkron fillæsning
@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)}

Mistral SDK er ingen undtagelse: enhver metode har en variant med suffikset _async, og det er den, du skal kalde fra en aktivitet.

from mistralai.client import Mistral

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

Hold denne mapping-tabel ved hånden under kodegennemgange: enhver linje fra venstre kolonne, der opdages i en aktivitet, er en potentiel ydelsesfejl.

OperationForkert (blokerende)Korrekt (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()
Fileropen()aiofiles.open()
Sleeptime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Når ingen async-version findes

Nogle forretningsbiblioteker, såsom et proprietært SDK eller en legacy-klient, tilbyder simpelthen ikke en asynkron variant. I disse tilfælde lader asyncio.to_thread() dig køre den blokerende kode i en separat tråd uden at fryse begivenhedssløjfen.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Omslutter et blokerende kald i en tråd."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Dette er et kompromis, ikke en ækvivalent løsning: hvert kald forbruger en tråd fra puljen, som har en begrænset størrelse. For en aktivitet, der kaldes massivt parallelt, flytter du blot flaskehalsen i stedet for at fjerne den. Foretræk altid et bibliotek, der er asynkront fra bunden, når et sådant findes.

Design af ryddelige aktiviteter

Ud over asynkronitet er der fire vaner, der adskiller en robust aktivitet fra én, der vil koste dig timer med fejlfinding.

Den første er omfang. En aktivitet bør have ét og kun ét ansvar, fordi den også er enheden for genforsøg og persistens: en „gør-alt”-aktivitet, der fejler under udsendelse af en e-mail, vil gentage udtrækning og analyse helt fra starten.

# GODT: Hver aktivitet har et klart ansvar
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# DÅRLIGT: Gør-alt-aktivitet
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # udtrækning
    sentiment = ...  # analyse
    # send e-mail
    # gem i DB
    pass

Den anden vedrører ressourcer. Context manageren async with garanterer, at klienten lukkes, selv hvis en undtagelse opstår – noget manuelle kald uundgåeligt glemmer før eller siden.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Brug async with for at garantere lukning
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Klienten lukkes automatisk her
    return response.json()

Den tredje er mere subtil: ikke alle fejl fortjener et genforsøg. En timeout, en 429 eller en 500 er midlertidige og bør boble op for at udløse et genforsøg. En 4xx-fejl indikerer derimod en ugyldig anmodning, som tre genforsøg ikke vil løse. Returnér i stedet et eksplicit resultat og lad workflowet beslutte.

@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  # Vil blive genforsøgt af platformen
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Rate limited — vil blive genforsøgt
            elif e.response.status_code >= 500:
                raise  # Serverfejl — vil blive genforsøgt
            else:
                # Klientfejl (4xx) — genforsøg ikke
                return {"status": "error", "code": e.response.status_code}

Endelig stammer det fjerde habit fra grænsen på 2 MB pr. invocation: returnér kun det, workflowet faktisk behøver for at beslutte næste skridt. Et antal, et udsnit og URL’en til det fulde resultat er næsten altid tilstrækkeligt.

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

    # Returnér kun det, workflowet behøver
    return {
        "item_count": len(data),
        "summary": data[:10],  # Kun de første 10
        "full_url": await upload_results(data)
    }

Vigtige pointer

  • Async I/O er obligatorisk: brug httpx, asyncpg, aiofiles i stedet for deres synkrone modstykker
  • Blokerende kald (requests, psycopg2, open) fryser hele workeren
  • Brug asyncio.to_thread() som sidste udvej for biblioteker uden en async-version
  • Hver aktivitet skal have ét klart ansvar
  • Luk altid forbindelser med async with
  • Håndtér fejl eksplicit: nogle skal genforsøges, andre skal ikke
  • Begræns returnerede størrelser for at holde dig under grænsen på 2 MB