Asinhronā I/O un labākā prakse
Šajā lapā
Asinhronā I/O: tehniska prasība
Visām Mistral Workflows darbībām ir jāizmanto asinhronas ievades/izvades operācijas. Tas nav stila ieteikums, bet gan tehnisks ierobežojums. Bloķējošs sinhrons izsaukums, piemēram, requests.post(), iesaldē strādnieku un neļauj izpildīt nevienu citu darbību.
Šī prasība izriet no strādnieka arhitektūras, kas darbības izpilda asyncio notikumu cilpā. Kad korutīne asinhroni gaida tīkla atbildi, tā atdod vadību cilpai, ļaujot citām darbībām turpināties. Sinhrons izsaukums, turpretī, neatdod neko.
import requests
# NEPAREIZI: Bloķē visu strādnieku
@workflows.activity()
async def blocking_activity(url: str) -> dict:
# requests.post() ir sinhrons — tas bloķē notikumu cilpu
response = requests.post(url, json={"query": "test"})
return response.json()
Simptomi ražošanas vidē var būt mulsinoši: tu palaid desmit darbības paralēli ar asyncio.gather, taču tās faktiski izpildās viena pēc otras. Ja katra gaida divas sekundes pēc attālā API, tu mēri divdesmit sekundes paredzēto divu vietā, un netiek izraisīta neviena kļūda.
Izvēlies dabiski asinhronas bibliotēkas
Risinājums ir aizstāt katru bloķējošo bibliotēku ar tās asinhrono ekvivalentu. HTTP izsaukumiem httpx ir noklusējuma izvēle.
import httpx
# PAREIZI: Nebloķējošs
@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 kalpo tam pašam mērķim ar nedaudz atšķirīgu API, kas balstīts uz sesijām.
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()
Datubāzēm asyncpg aizvieto psycopg2 priekš PostgreSQL. Ņem vērā try/finally bloku: savienojumam ir jābūt aizvērtam pat tad, ja vaicājums izraisa izņēmumu. Pretējā gadījumā secīgi mēģinājumi izsmels savienojumu baseinu.
import asyncpg
# PAREIZI: Asinhrons PostgreSQL draiveris
@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()
Failu piekļuve seko tai pašai loģikai ar aiofiles, pat maziem failiem, kur tev varētu rasties kārdinājums turpināt lietot open().
import aiofiles
# PAREIZI: Asinhrona failu lasīšana
@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 nav izņēmums: katrai metodei ir variants ar sufiksu _async, un tieši tas ir jāizsauc no darbības.
from mistralai.client import Mistral
@workflows.activity()
async def call_mistral(prompt: str) -> dict:
client = Mistral()
# Izmanto complete_async, NEVIS complete
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[{"role": "user", "content": prompt}]
)
return {"response": response.choices[0].message.content}
Koda apskatu laikā tur šo kartēšanas tabulu pa rokai: jebkura rinda no kreisās kolonnas, kas pamanīta darbībā, ir potenciāla veiktspējas kļūda.
| Operācija | Nepareizi (bloķējošs) | Pareizi (asinhrons) |
|---|---|---|
| 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() |
| Faili | open() | aiofiles.open() |
| Miega režīms | time.sleep() | asyncio.sleep() |
| Mistral | client.chat.complete() | client.chat.complete_async() |
Ja asinhrona versija nepastāv
Dažas biznesa bibliotēkas, piemēram, īpašnieka SDK vai vecs klients, vienkārši nepiedāvā asinhronu variantu. Šādos gadījumos asyncio.to_thread() ļauj izpildīt bloķējošo kodu atsevišķā pavedienā, neiesaldējot notikumu cilpu.
import asyncio
from some_library import blocking_function
@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
"""Ietver bloķējošu izsaukumu pavedienā."""
result = await asyncio.to_thread(
blocking_function,
params["arg1"],
params["arg2"]
)
return {"result": result}
Tas ir kompromiss, nevis ekvivalents risinājums: katrs izsaukums patērē vienu pavedienu no baseina, kura izmērs ir ierobežots. Darbībai, ko izsauc masveidā paralēli, tu vienkārši pārvieto sašaurinājuma vietu, nevis to novērš. Vienmēr dod priekšroku dabiski asinhronai bibliotēkai, ja tāda pastāv.
Tīru darbību projektēšana
Papildus asinhronijai, četri ieradumi atšķir stabilu darbību no tādas, kas tev izmaksās stundas debugošanā.
Pirmais ir darbības joma. Darbībai ir jābūt vienam un tikai vienam pienākumam, jo tā ir arī atkārtotas izpildes un noturības vienība: visaptveroša darbība, kas neizdodas, sūtot e-pastu, no jauna izpildīs ekstrakciju un analīzi no paša sākuma.
# LABI: Katrai darbībai ir skaidrs pienākums
@workflows.activity()
async def extract_text(url: str) -> dict:
# ...
pass
@workflows.activity()
async def analyze_sentiment(text: str) -> dict:
# ...
pass
# SLIKTI: Visaptveroša darbība
@workflows.activity()
async def do_everything(url: str) -> dict:
text = ... # ekstrakcija
sentiment = ... # analīze
# sūtīt e-pastu
# saglabāt DB
pass
Otrais attiecas uz resursiem. async with konteksta menedžeris garantē, ka klients tiks aizvērts pat tad, ja rodas izņēmums – kaut ko, ko manuāli izsaukumi agrāk vai vēlāk neizbēgami aizmirsīs.
@workflows.activity()
async def clean_request(params: dict) -> dict:
# Izmanto async with, lai garantētu aizvēršanu
async with httpx.AsyncClient() as client:
response = await client.get(params["url"])
# Klients šeit tiek automātiski aizvērts
return response.json()
Trešais ir smalkāks: ne visas kļūdas ir pelnījušas atkārtotu mēģinājumu. Noilgums, 429 vai 500 ir pārejoši un tiem ir jāļauj izplatīties tālāk, lai izraisītu atkārtotu mēģinājumu. 4xx kļūda tomēr norāda uz nederīgu pieprasījumu, ko trīs atkārtoti mēģinājumi neizlabos. Tā vietā atgriez skaidru rezultātu un ļauj darba plūsmai lemt.
@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 to atkārtos
except httpx.HTTPStatusError as e:
if e.response.status_code == 429:
raise # Ātruma ierobežojums — tiks atkārtots
elif e.response.status_code >= 500:
raise # Servera kļūda — tiks atkārtots
else:
# Klienta kļūda (4xx) — neatkārtot
return {"status": "error", "code": e.response.status_code}
Visbeidzot, ceturtais ieradums izriet no 2 MB limita vienam izsaukumam: atgriez tikai to, kas darba plūsmai faktiski nepieciešams, lai lemtu par nākamo soli. Skaits, paraugs un URL uz pilno rezultātu gandrīz vienmēr ir pietiekami.
@workflows.activity()
async def extract_data(source: str) -> dict:
data = await retrieve_large_data(source)
# Atgriez tikai to, kas darba plūsmai nepieciešams
return {
"item_count": len(data),
"summary": data[:10], # Tikai pirmie 10
"full_url": await upload_results(data)
}
Galvenās atziņas
- Asinhronā I/O ir obligāta: izmanto
httpx,asyncpg,aiofilesto sinhrono ekvivalentu vietā - Bloķējoši izsaukumi (
requests,psycopg2,open) iesaldē visu strādnieku - Izmanto
asyncio.to_thread()kā pēdējo līdzekli bibliotēkām bez asinhronas versijas - Katrai darbībai ir jābūt vienam skaidram pienākumam
- Vienmēr aizver savienojumus ar
async with - Apstrādā kļūdas eksplicīti: dažas ir jāatkārto, citas – nē
- Ierobežo atgriežamos datus, lai iekļautos 2 MB limitā