Asynkroninen I/O ja parhaat käytännöt
Tällä sivulla
Asynkroninen I/O: Tekninen vaatimus
Kaikkien Mistral Workflows -aktiviteettien on käytettävä asynkronisia syöte- ja tulostetoimintoja. Tämä ei ole tyylisuositus, vaan tekninen pakko. Estävä synkroninen kutsu, kuten requests.post(), jäädyttää workerin ja estää muiden aktiviteettien suorittamisen.
Tämä vaatimus johtuu workerin arkkitehtuurista, joka suorittaa aktiviteetit asyncio-tapahtumasilmukassa. Kun korutiini odottaa verkkovastausta asynkronisesti, se luovuttaa ohjauksen takaisin silmukalle, jolloin muut aktiviteetit voivat edetä. Synkroninen kutsu sen sijaan ei luovuta ohjausta lainkaan.
import requests
# VÄÄRIN: Estää koko workerin
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() on synkroninen — se estää tapahtumasilmukan
response = requests.post(url, json={"query": "test"})
return response.json()
Oire tuotantoympäristössä voi olla hämmentävä: käynnistät kymmenen aktiviteettia rinnakkain komennolla asyncio.gather, mutta ne suoritetaan itse asiassa yksi kerrallaan. Jos kukin odottaa kaksi sekuntia etä-API:lta, mittaat kaksikymmentä sekuntia odotetun kahden sijaan, eikä virheitä nosteta.
Valitse natiivisti asynkroniset kirjastot
Ratkaisu on korvata jokainen estävä kirjasto sen asynkronisella vastineella. HTTP-kutsuissa httpx on oletusvalinta.
import httpx
# OIKEIN: Ei-estävä
@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 palvelee samaa tarkoitusta hieman erilaisella istuntoihin perustuvalla API:lla.
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()
Tietokantojen osalta asyncpg korvaa psycopg2:n PostgreSQL:ssä. Huomaa try/finally-lohko: yhteys on suljettava, vaikka kysely nostaisikin poikkeuksen. Muuten peräkkäiset uudelleenyritykset tyhjentävät yhteyspoolin.
import asyncpg
# OIKEIN: Asynkroninen PostgreSQL-ajuri
@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()
Tiedostojen käsittely noudattaa samaa logiikkaa aiofiles:n kanssa, jopa pienille tiedostoille, joissa saatat olla kiusaus käyttää edelleen open():aa.
import aiofiles
# OIKEIN: Asynkroninen tiedostonluku
@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)}
Itse Mistral SDK ei ole poikkeus: jokaisella metodilla on _async-päätteinen muunnos, ja juuri sitä sinun on kutsuttava aktiviteetista.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Käytä complete_async, ÄLÄkä complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Pidä tämä vastaavuustaulukko käsillä koodikatselmusten aikana: mikä tahansa vasemman sarakkeen rivi aktiviteetissa on potentiaalinen suorituskykybugi.
| Toiminto | Väärin (estävä) | Oikein (asynkroninen) |
|---|---|---|
| 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() |
| Tiedostot | open() | aiofiles.open() |
| Lepo | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Kun asynkronista versiota ei ole olemassa
Jotkin liiketoimintakirjastot, kuten omisteinen SDK tai vanhentunut asiakasohjelmisto, eivät yksinkertaisesti tarjoa asynkronista muunnosta. Näissä tapauksissa asyncio.to_thread() antaa sinun suorittaa estävän koodin erillisessä säikeessä jäädyttämättä tapahtumasilmukkaa.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Käärii estävän kutsun säikeeseen."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Tämä on kompromissi, ei vastaava ratkaisu: jokainen kutsu kuluttaa säikeen poolista, jonka koko on äärellinen. Massiivisesti rinnakkain kutsutussa aktiviteetissa siirrät vain pullonkaulaa etkä poista sitä. Suosi aina natiivia asynkronista kirjastoa, jos sellainen on olemassa.
Siistien aktiviteettien suunnittelu
Asynkronisuuden lisäksi neljä tapaa erottaa vankan aktiviteetin sellaisesta, joka maksaa sinulle tunteja vianetsintää.
Ensimmäinen on laajuus. Aktiviteetilla tulisi olla yksi ja vain yksi vastuualue, koska se on myös uudelleenyrityksen ja pysyvyyden yksikkö: kaiken kattava aktiviteetti, joka epäonnistuu sähköpostin lähetyksessä, toistaa extractionin ja analyysin alusta alkaen.
# HYVÄ: Jokaisella aktiviteetilla on selkeä vastuu
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# HUONO: Kaiken kattava aktiviteetti
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # extraction
sentiment = ... # analysis
# lähetä sähköposti
# tallenna tietokantaan
pass
Toinen koskee resursseja. async with -kontekstinhallitsija takaa, että asiakas sulkeutuu jopa poikkeustilanteessa, mikä manuaalisista kutsuista väistämättä unohtuu ennemmin tai myöhemmin.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Käytä async with varmistaaksesi sulkemisen
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Asiakas sulkeutuu automaattisesti tässä
return response.json()
Kolmas on hienovaraisempi: kaikki virheet eivät ansaitse uudelleenyritystä. Aikakatkaisu, 429 tai 500 ovat ohimeneviä ja niiden pitäisi kuplia ylös uudelleenyrityksen laukaisemiseksi. 4xx-virhe sen sijaan kertoo virheellisestä pyynnöstä, jota kolme uudelleenyritystä ei korjaa. Palauta sen sijaan eksplisiittinen tulos ja anna työnkulun päättää.
@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 # Alusta yritetään uudelleen
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Nopeusrajoitus — yritetään uudelleen
elif e.response.status_code >= 500:
raise # Palvelinvirhe — yritetään uudelleen
else:
# Asiakasvirhe (4xx) — älä yritä uudelleen
return {"status": "error", "code": e.response.status_code}
Lopuksi neljäs tapa juontaa juurensa 2 Mt:n kutsukohtaiseen rajoitukseen: palauta vain se, mitä työnkulku todella tarvitsee päättääkseen seuraavan vaiheen. Lukumäärä, otos ja URL osoitteeseen, jossa on täydellinen tulos, ovat lähes aina riittäviä.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Palauta vain se, mitä työnkulku tarvitsee
return {
"item_count": len(data),
"summary": data[:10], # Vain ensimmäiset 10
"full_url": await upload_results(data)
}
Keskeiset asiat
- Asynkroninen I/O on pakollinen: käytä
httpx:ää,asyncpg:tä jaaiofiles:ää niiden synkronisten vastineiden sijaan - Estävät kutsut (
requests,psycopg2,open) jäädyttävät koko workerin - Käytä
asyncio.to_thread():ää viimeisenä keinona kirjastoille, joista ei ole asynkronista versiota - Jokaisella aktiviteetilla on oltava yksi selkeä vastuualue
- Sulje yhteydet aina käyttämällä
async with:ää - Käsittele virheet eksplisiittisesti: joitakin pitäisi yrittää uudelleen, toisia ei
- Rajoita palautettavien tietojen kokoa pysyäksesi 2 Mt:n rajan alapuolella