Async og bedste praksis
På denne side
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.
| Operation | Forkert (blokerende) | Korrekt (async) |
|---|---|---|
| HTTP | requests.get() | httpx.AsyncClient().get() |
| HTTP | urllib.request.urlopen() | aiohttp.ClientSession().get() |
| PostgreSQL | psycopg2.connect() | asyncpg.connect() |
| MySQL | mysql.connector.connect() | aiomysql.connect() |
| Redis | redis.Redis() | redis.asyncio.Redis() |
| Filer | open() | aiofiles.open() |
| Sleep | time.sleep() | asyncio.sleep() |
| Mistral | client.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,aiofilesi 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