Премини към основното съдържание
Български— Изберете език
Меню

Асинхронност и най-добри практики

Урок 13 от 14 Обновен 2 ноември 2026 г. Напреднало
На тази страница
  1. Асинхронен вход/изход: Техническо изискване
  2. Изберете библиотеки с вградена асинхронност
  3. Когато няма асинхронна версия
  4. Проектиране на изчистени дейности
  5. Ключови изводи

Асинхронен вход/изход: Техническо изискване

Всички дейности в Mistral Workflows трябва да използват асинхронни операции за вход/изход. Това не е препоръка за стил на кодиране, а техническо ограничение. Блокиращ синхронен вызов като requests.post() замразява работника (worker) и предотвратява изпълнението на всяка друга дейност.

Това изискване произтича от архитектурата на работника, който изпълнява дейностите в рамките на събитийния цикъл (event loop) на asyncio. Когато корутината изчака асинхронно мрежов отговор, тя връща контрола на цикъла, позволявайки на други дейности да продължат. Синхронният вызов, обратно, не връща нищо.

import requests

# ГРЕШНО: Блокира целия работник
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() е синхронен — блокира събитийния цикъл
    response = requests.post(url, json={"query": "test"})
    return response.json()

Симптомът в продукционна среда може да бъде объркващ: стартирате десет дейности паралелно с asyncio.gather, но те всъщност се изпълняват една след друга. Ако всяка чака две секунди за отговор от отдалечен API, ще измерите двадесет секунди вместо очакваните две, без да бъдат генерирани грешки.

Изберете библиотеки с вградена асинхронност

Решението е да замените всяка блокираща библиотека с нейния асинхронен еквивалент. За HTTP заявки httpx е стандартният избор.

import httpx

# ПРАВИЛНО: Неблокиращо
@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 служи за същата цел с леко различен API, базиран на сесии.

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

За бази данни asyncpg замества psycopg2 за PostgreSQL. Обърнете внимание на блока try/finally: връзката трябва да се затвори дори ако заявката генерира изключение. В противен случай последователните повторни опити ще изчерпят пула от връзки.

import asyncpg

# ПРАВИЛНО: Асинхронен драйвер за PostgreSQL
@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()

Достъпът до файлове следва същата логика с aiofiles, дори за малки файлове, където може да сте склонни да продължите да използвате open().

import aiofiles

# ПРАВИЛНО: Асинхронно четене на файл
@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 не е изключение: всеки метод има вариант с наставка _async и точно него трябва да извиквате от дейност.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Използвайте complete_async, НЕ complete
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Пазете тази таблица за съпоставка под ръка по време на преглед на кода: всеки ред от лявата колона, открит в дейност, е потенциален бъг, засягащ производителността.

ОперацияГрешно (блокиращо)Правилно (асинхронно)
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()
Файловеopen()aiofiles.open()
Паузаtime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Когато няма асинхронна версия

Някои бизнес библиотеки, като собствен SDK или остарял клиент, просто не предлагат асинхронен вариант. В тези случаи asyncio.to_thread() Ви позволява да изпълните блокиращия код в отделен нишк (thread), без да замразявате събитийния цикъл.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Опакова блокиращ извикване в нишка."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Това е компромис, а не еквивалентно решение: всяко извикване консумира нишка от пула, който има краен размер. За дейност, извиквана масово паралелно, Вие просто премествате тясното място, вместо да го премахнете. Винаги предпочитайте библиотека с вградена асинхронност, когато такава съществува.

Проектиране на изчистени дейности

Отвъд асинхронността, четири навика отличават една надеждна дейност от такава, която ще Ви коства часове дебъгване.

Първият е обхватът. Една дейност трябва да има една-единствена отговорност, тъй като тя е и единицата за повторен опит и постоянство: дейност „всичко в едно“, която се провали при изпращане на имейл, ще възпроизведе екстракцията и анализа от самото начало.

# ДОБРЕ: Всяка дейност има ясна отговорност
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# ЗЛЕ: Дейност „всичко в едно“
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # екстракция
    sentiment = ...  # анализ
    # изпращане на имейл
    # запис в БД
    pass

Вторият се отнася до ресурсите. Мениджърът на контекста async with гарантира, че клиентът ще се затвори дори при възникване на изключение – нещо, което ръчните извиквания неизбежно пропускат рано или късно.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Използвайте async with, за да гарантирате затваряне
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Клиентът се затваря автоматично тук
    return response.json()

Третият е по-фин: не всички грешки заслужават повторен опит. Изтичане на времето (timeout), код 429 или 500 са преходни и трябва да се предадат нагоре, за да задействат повторен опит. Грешка 4xx обаче показва невалидна заявка, която три повторни опита няма да поправят. Вместо това върнете изричен резултат и оставете работния поток да реши.

@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  # Ще бъде повторено от платформата
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Ограничение на скоростта — ще бъде повторено
            elif e.response.status_code >= 500:
                raise  # Грешка на сървъра — ще бъде повторено
            else:
                # Грешка на клиента (4xx) — не повтаряй
                return {"status": "error", "code": e.response.status_code}

Накрая, четвъртият навик произтича от ограничението от 2 MB на извикване: връщайте само онова, от което работният поток действително се нуждае, за да вземе решение за следващата стъпка. Брой, извадка и URL адрес към пълния резултат почти винаги са достатъчни.

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

    # Върнете само онова, от което работният поток се нуждае
    return {
        "item_count": len(data),
        "summary": data[:10],  # Само първите 10
        "full_url": await upload_results(data)
    }

Ключови изводи

  • Асинхронният вход/изход е задължителен: използвайте httpx, asyncpg, aiofiles вместо техните синхронни еквиваленти
  • Блокиращите извиквания (requests, psycopg2, open) замразяват целия работник
  • Използвайте asyncio.to_thread() като последна мярка за библиотеки без асинхронна версия
  • Всяка дейност трябва да има една ясна отговорност
  • Винаги затваряйте връзките с async with
  • Обработвайте грешките изрично: някои трябва да се повторят, други – не
  • Ограничете размера на връщаните данни, за да останете под лимита от 2 MB