Asinchroninis I/O ir geriausios praktikos
Šiame puslapyje
Asinchroninis I/O: techninis reikalavimas
Visos „Mistral Workflows“ veiklos privalo naudoti asinchronines įvesties ir išvesties operacijas. Tai ne stiliaus rekomendacija, o techninis apribojimas. Blokuojantis sinchroninis kvietimas, pavyzdžiui, requests.post(), sustabdo darbuotoją ir neleidžia vykdyti jokiai kitai veiklai.
Šis reikalavimas kyla iš darbuotojo architektūros, kuri vykdo veiklas „asyncio“ įvykių cikle. Kai korutina asinchroniškai laukia tinklo atsako, ji grąžina valdymą ciklui, leisdama tęsti kitas veiklas. Sinchroninis kvietimas, priešingai, nieko negrąžina.
import requests
# NETEISINGAI: Blokuoja visą darbuotoją
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() yra sinchroninis – jis blokuoja įvykių ciklą
response = requests.post(url, json={"query": "test"})
return response.json()
Simptomas gamybinėje aplinkoje gali būti painus: paleidi dešimt veiklų lygiagrečiai naudodamas asyncio.gather, tačiau jos iš tikrųjų vykdomos viena po kitos. Jei kiekviena laukia dviejų sekundžių nuotolinio API atsako, išmatuoji dvidešimt sekundžių vietoj tikėtųjų dviejų, ir jokių klaidų nekyla.
Pasirink natūraliai asinchronines bibliotekas
Sprendimas – pakeisti kiekvieną blokuojančią biblioteką jos asinchroniniu atitikmeniu. HTTP užklausoms „httpx“ yra pagrindinis pasirinkimas.
import httpx
# TEISINGAI: Neblokuojantis
@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“ atlieka tą pačią funkciją, tačiau turi šiek tiek kitokį API, pagrįstą sesijomis.
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()
Duomenų bazėms „asyncpg“ pakeičia „psycopg2“ skirtą „PostgreSQL“. Atkreipk dėmesį į try/finally bloką: ryšys privalo būti uždarytas net ir tuo atveju, jei užklausa išmeta klaidą. Priešingu atveju pakartotiniai bandymai išsekins ryšių telkinį.
import asyncpg
# TEISINGAI: Asinchroninis „PostgreSQL“ tvarkyklė
@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()
Failų skaitymas laikosi tos pačios logikos naudojant „aiofiles“, net ir mažiems failams, kuriems gali kilti pagunda toliau naudoti open().
import aiofiles
# TEISINGAI: Asinchroninis failų skaitymas
@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)}
Pats „Mistral“ SDK nėra išimtis: kiekvienas metodas turi variantą su priesaga _async, ir būtent jį privalai kviesti iš veiklos.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Naudok complete_async, o NE complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Peržiūrėdamas kodą, turėk po ranka šią atitikimų lentelę: bet kuri eilutė iš kairiojo stulpelio, pastebėta veikloje, yra potenciali našumo klaida.
| Operacija | Netinkama (blokuojanti) | Tinkama (asinchroninė) |
|---|---|---|
| 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() |
| Failai | open() | aiofiles.open() |
| Miegojimas | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Kai asinchroninės versijos nėra
Kai kurios verslo bibliotekos, pavyzdžiui, nuosavybinis SDK arba senas klientas, tiesiog neturi asinchroninio varianto. Tokiais atvejais asyncio.to_thread() leidžia vykdyti blokuojantį kodą atskiroje gijoje neužblokuojant įvykių ciklo.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Apvynioja blokuojantį kvietimą gijoje."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Tai kompromisas, o ne lygiavertis sprendimas: kiekvienas kvietimas sunaudoja vieną giją iš telkinio, kurio dydis yra baigtinis. Veiklai, kviečiamai masiškai lygiagrečiai, tu tik perkeli „butelio kaklelį“, o ne pašalini jį. Visada teik pirmenybę natūraliai asinchroninei bibliotekai, jei tokia egzistuoja.
Švarių veiklų kūrimas
Be asinchroniškumo, keturi įpročiai skiria patikimą veiklą nuo tokios, kuri tau kainuos valandas derinimo.
Pirmasis – apimtis. Veikla turi turėti vieną ir tik vieną atsakomybę, nes ji taip pat yra pakartotinio vykdymo ir išsaugojimo vienetas: viską apimanti veikla, kuri nepavyksta siunčiant el. laišką, iš naujo paleis ekstrakciją ir analizę nuo pat pradžių.
# GERAI: Kiekviena veikla turi aiškią atsakomybę
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# BLOGAI: Visą darbą atliekanti veikla
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # ekstrakcija
sentiment = ... # analizė
# siųsti el. laišką
# įrašyti į DB
pass
Antrasis susijęs su ištekliais. async with konteksto valdytojas garantuoja, kad klientas bus uždarytas net įvykus išimčiai – to rankiniai kvietimai anksčiau ar vėliau neišvengiamai pamiršta.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Naudok async with, kad užtikrintum uždarymą
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Klientas čia automatiškai uždaromas
return response.json()
Trečiasis yra subtilesnis: ne visos klaidos nusipelno pakartotinio bandymo. Laiko limito viršijimas, 429 arba 500 klaidos yra laikinos ir turėtų būti perduotos toliau, kad būtų inicijuotas pakartotinis bandymas. Tačiau 4xx klaida rodo neteisingą užklausą, kurios trys pakartotiniai bandymai neištaisys. Užuot tai daręs, grąžink aiškų rezultatą ir leisk darbo eigai nuspręsti.
@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 tai bandys vykdyti iš naujo
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Ribojamas dažnis – bus bandoma iš naujo
elif e.response.status_code >= 500:
raise # Serverio klaida – bus bandoma iš naujo
else:
# Kliento klaida (4xx) – nebandyti iš naujo
return {"status": "error", "code": e.response.status_code}
Galiausiai, ketvirtasis įprotis kyla iš 2 MB ribos vienam kvietimui: grąžink tik tai, ko darbo eigai iš tikrųjų reikia norint nuspręsti dėl kito žingsnio. Skaičius, imtis ir URL nuoroda į pilną rezultatą beveik visada yra pakankami.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Grąžink tik tai, ko reikia darbo eigai
return {
"item_count": len(data),
"summary": data[:10], # Tik pirmieji 10
"full_url": await upload_results(data)
}
Svarbiausi punktai
- Asinchroninis I/O yra privalomas: naudok
httpx,asyncpg,aiofilesvietoj jų sinchroninių atitikmenų - Blokuojantys kvietimai (
requests,psycopg2,open) sustabdo visą darbuotoją - Naudok
asyncio.to_thread()tik kaip paskutinę išeitį bibliotekoms, neturinčioms asinchroninės versijos - Kiekviena veikla privalo turėti vieną aiškią atsakomybę
- Visada užverk ryšius naudodamas
async with - Tvarkyk klaidas aiškiai: kai kurias reikia bandyti vykdyti iš naujo, kitų – ne
- Apribok grąžinamų duomenų dydį, kad neviršytum 2 MB ribos