Przejdź do głównej treści
Polski— Wybierz język
Menu

Asynchroniczność i najlepsze praktyki

Lekcja 13 z 14 Zaktualizowano 2 listopada 2026 Zaawansowany
Na tej stronie
  1. We/Wy asynchroniczne: wymóg techniczny
  2. Wybieraj biblioteki natywnie asynchroniczne
  3. Gdy nie istnieje wersja asynchroniczna
  4. Projektowanie czystych działań
  5. Kluczowe wnioski

We/Wy asynchroniczne: wymóg techniczny

Wszystkie działania w Mistral Workflows muszą używać asynchronicznych operacji wejścia/wyjścia. To nie jest zalecenie stylistyczne, lecz ograniczenie techniczne. Blokujące wywołanie synchroniczne, takie jak requests.post(), zamraża worker i uniemożliwia uruchomienie jakiegokolwiek innego działania.

Wymóg ten wynika z architektury workera, który wykonuje działania w pętli zdarzeń asyncio. Gdy korutyna asynchronicznie oczekuje na odpowiedź sieciową, zwraca sterowanie pętli, pozwalając innym działaniom na postęp. Wywołanie synchroniczne natomiast niczego nie zwraca.

import requests

# BŁĘDNIE: Blokuje całego workera
@workflows.activity()
async def blocking_activity(url: str) -> dict:
    # requests.post() jest synchroniczne — blokuje pętlę zdarzeń
    response = requests.post(url, json={"query": "test"})
    return response.json()

Objaw w środowisku produkcyjnym może być mylący: uruchamiasz dziesięć działań równolegle za pomocą asyncio.gather, ale faktycznie wykonują się one jedno po drugim. Jeśli każde czeka dwie sekundy na zdalne API, zmierzysz dwadzieścia sekund zamiast oczekiwanych dwóch, bez zgłaszania żadnych błędów.

Wybieraj biblioteki natywnie asynchroniczne

Rozwiązaniem jest zastąpienie każdej blokującej biblioteki jej asynchronicznym odpowiednikiem. Do wywołań HTTP domyślnym wyborem jest httpx.

import httpx

# POPRAWNIE: Nieblokujące
@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 spełnia to samo zadanie, korzystając z nieco innego API opartego na sesjach.

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

W przypadku baz danych asyncpg zastępuje psycopg2 dla PostgreSQL. Zwróć uwagę na blok try/finally: połączenie musi zostać zamknięte nawet wtedy, gdy zapytanie zgłosi wyjątek. W przeciwnym razie kolejne ponowne próby wyczerpią pulę połączeń.

import asyncpg

# POPRAWNIE: Asynchroniczny sterownik 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()

Dostęp do plików działa na tej samej zasadzie z użyciem aiofiles, nawet w przypadku małych plików, gdzie mógłbyś mieć pokusę继续使用 open().

import aiofiles

# POPRAWNIE: Asynchroniczne odczytywanie pliku
@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)}

Sam SDK Mistral nie jest wyjątkiem: każda metoda ma wariant z sufiksem _async i to właśnie jego musisz używać w działaniach.

from mistralai.client import Mistral

@workflows.activity()
async def call_mistral(prompt: str) -> dict:
    client = Mistral()
    # Użyj complete_async, NIE complete
    response = await client.chat.complete_async(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": prompt}]
    )
    return {"response": response.choices[0].message.content}

Miej tę tabelę mapowania pod ręką podczas przeglądów kodu: każda linia z lewej kolumny wykryta w działaniu to potencjalny błąd wydajnościowy.

OperacjaBłędnie (blokujące)Poprawnie (asynchroniczne)
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()
Plikiopen()aiofiles.open()
Uśpienietime.sleep()asyncio.sleep()
Mistralclient.chat.complete()client.chat.complete_async()

Gdy nie istnieje wersja asynchroniczna

Niektóre biblioteki biznesowe, takie jak własne SDK lub starszy klient, po prostu nie oferują wariantu asynchronicznego. W takich przypadkach asyncio.to_thread() pozwala uruchomić blokujący kod w osobnym wątku bez zamrażania pętli zdarzeń.

import asyncio
from some_library import blocking_function

@workflows.activity()
async def compatibility_activity(params: dict) -> dict:
    """Obejmuje wywołanie blokujące wątkiem."""
    result = await asyncio.to_thread(
        blocking_function,
        params["arg1"],
        params["arg2"]
    )
    return {"result": result}

Jest to kompromis, a nie rozwiązanie równoważne: każde wywołanie zużywa wątek z puli, która ma skończony rozmiar. W przypadku działania wywoływanego masowo równolegle, jedynie przenosisz wąskie gardło, zamiast je usuwać. Zawsze preferuj natywnie asynchroniczną bibliotekę, jeśli taka istnieje.

Projektowanie czystych działań

Poza asynchronicznością, cztery nawyki odróżniają solidne działanie od takiego, które kosztować cię będzie godziny debugowania.

Pierwszym jest zakres. Działanie powinno mieć jedno i tylko jedno odpowiedzialność, ponieważ jest również jednostką ponawiania i trwałości: działanie typu „wszystko w jednym“, które zawiedzie podczas wysyłania e-maila, spowoduje ponowne wykonanie ekstrakcji i analizy od samego początku.

# DOBRZE: Każde działanie ma jasną odpowiedzialność
@workflows.activity()
async def extract_text(url: str) -> dict:
    # ...
    pass

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

# ŹLE: Działanie typu „wszystko w jednym“
@workflows.activity()
async def do_everything(url: str) -> dict:
    text = ...  # ekstrakcja
    sentiment = ...  # analiza
    # wyślij e-mail
    # zapisz do bazy danych
    pass

Drugi dotyczy zasobów. Menadżer kontekstu async with gwarantuje zamknięcie klienta nawet w przypadku wystąpienia wyjątku, czego ręczne wywołania prędzej czy później nie dopilnują.

@workflows.activity()
async def clean_request(params: dict) -> dict:
    # Użyj async with, aby zagwarantować zamknięcie
    async with httpx.AsyncClient() as client:
        response = await client.get(params["url"])
    # Klient jest tutaj automatycznie zamykany
    return response.json()

Trzeci jest bardziej subtelny: nie wszystkie błędy zasługują na ponowną próbę. Timeout, kod 429 lub 500 są przejściowe i powinny być propagowane, aby uruchomić ponowną próbę. Błąd 4xx wskazuje jednak na nieprawidłowe żądanie, którego trzykrotne ponowienie nie naprawi. Zamiast tego zwróć wyraźny wynik i pozwól workflow podjąć decyzję.

@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  # Zostanie ponowione przez platformę
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                raise  # Ograniczenie stawki — zostanie ponowione
            elif e.response.status_code >= 500:
                raise  # Błąd serwera — zostanie ponowione
            else:
                # Błąd klienta (4xx) — nie powtarzaj
                return {"status": "error", "code": e.response.status_code}

Wreszcie, czwarty nawyk wynika z limitu 2 MB na wywołanie: zwracaj tylko to, czego workflow faktycznie potrzebuje, aby podjąć decyzję o następnym kroku. Licznik, próbka i URL do pełnego wyniku są prawie zawsze wystarczające.

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

    # Zwróć tylko to, czego potrzebuje workflow
    return {
        "item_count": len(data),
        "summary": data[:10],  # Tylko pierwsze 10
        "full_url": await upload_results(data)
    }

Kluczowe wnioski

  • We/Wy asynchroniczne są obowiązkowe: używaj httpx, asyncpg, aiofiles zamiast ich synchronicznych odpowiedników
  • Wywołania blokujące (requests, psycopg2, open) zamrażają całego workera
  • Używaj asyncio.to_thread() jako ostateczności dla bibliotek bez wersji asynchronicznej
  • Każde działanie musi mieć jedną jasną odpowiedzialność
  • Zawsze zamykaj połączenia za pomocą async with
  • Obsługuj błędy jawnie: niektóre powinny być ponawiane, inne nie
  • Ograniczaj rozmiary zwracanych danych, aby zmieścić się w limicie 2 MB