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

Polityka ponawiania prób

Lekcja 12 z 14 Zaktualizowano 29 lipca 2026 Zaawansowany
Na tej stronie
  1. Dlaczego ponawianie prób jest niezbędne
  2. Konfigurowanie polityki ponawiania prób
  3. Nigdy nie pomijaj start_to_close_timeout
  4. Idempotentność: warunek nienegocjowalny
  5. Trzy profile konfiguracji
  6. Kluczowe wnioski

Dlaczego ponawianie prób jest niezbędne

W systemach rozproszonych błędy przemijające są nieuniknione: przekroczenia limitu czasu sieci, limity częstotliwości zapytań (rate limits), tymczasowa niedostępność usług. Żadna z tych awarii nie oznacza błędu w Twoim kodzie, ale każda z nich może spowodować niepowodzenie procesu, jeśli nic nie złagodzi tego wstrząsu. Polityka ponawiania prób pozwala Twoim działaniom przetrwać te błędy bez interwencji ręcznej, ponieważ platforma automatycznie uruchamia je ponownie zgodnie z konfiguracją zdefiniowaną dla każdego działania.

Konfigurowanie polityki ponawiania prób

Dekorator @workflows.activity() przyjmuje parametry sterujące tym zachowaniem. Oto przykład działania wywołującego zewnętrzne API, odpowiednio zabezpieczonego pod kątem odporności na błędy.

from datetime import timedelta
import mistralai.workflows as workflows

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=5),
    retry_policy_max_attempts=3,
    retry_policy_backoff_coefficient=2.0,
)
async def call_external_api(url: str, data: dict) -> dict:
    """Calls an external API with automatic retry."""
    async with httpx.AsyncClient(timeout=60) as client:
        response = await client.post(url, json=data)
        response.raise_for_status()
        return response.json()

Trzy parametry, trzy uzupełniające się role.

  • start_to_close_timeout — Maksymalny czas trwania pojedynczej próby wykonania. Jeśli działanie nie zakończy się w tym czasie, zostaje uznane za nieudane i uruchamiana jest nowa próba.

  • retry_policy_max_attempts — Maksymalna liczba prób. Wartość domyślna zależy od platformy. Po przekroczeniu tej liczby działanie kończy się ostatecznym niepowodzeniem, a workflow otrzymuje błąd.

  • retry_policy_backoff_coefficient — Mnożnik opóźnienia między próbami. Przy współczynniku 2.0 opóźnienia podwajają się z każdą próbą (1 s, 2 s, 4 s, 8 s…). Jest to wykładnicze opóźnianie (exponential backoff).

Mechanizm ten zasługuje na uwagę, ponieważ jego celem nie jest tylko czekanie: daje on walczącemu serwisowi czas na odzyskanie sprawności, zamiast go przeciążać. Poniższy przebieg wywołania, które ostatecznie kończy się sukcesem, ilustruje to wyraźnie.

Attempt 1: immediate execution
  → Failure (network timeout)
  → Wait 1 second

Attempt 2: execution
  → Failure (service unavailable)
  → Wait 2 seconds (1 × 2.0)

Attempt 3: execution
  → Failure (rate limit)
  → Wait 4 seconds (2 × 2.0)

Attempt 4: execution
  → Success!

W obliczu odpowiedzi „429 Too Many Requests“ mechanizm ten jest szczególnie skuteczny: polityka natychmiastowego ponawiania prób tylko podtrzymywałaby przeciążenie, podczas gdy zwiększanie odstępów czasowych pozwala最終nie zejść poniżej progu dostawcy.

Nigdy nie pomijaj start_to_close_timeout

Ten limit czasu jest krytyczny i musi występować w każdym działaniu, bez wyjątku. Bez niego działanie, które utknęło (deadlock, zawieszone połączenie, usługa, która przyjmuje żądanie, ale nigdy nie odpowiada), czeka w nieskończoność i zamraża cały workflow. Co gorsza: nie uruchamia to ponownej próby, ponieważ z perspektywy platformy działanie jeszcze nie zakończyło się niepowodzeniem.

# BAD PRACTICE: no timeout
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
    # If the service never responds, the activity waits indefinitely
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

# GOOD PRACTICE: explicit timeout
@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2)
)
async def safe_activity(params: dict) -> dict:
    async with httpx.AsyncClient(timeout=90) as client:
        response = await client.get("https://api.lente.example.com/data")
    return response.json()

Aby ustawić wartość, najpierw zmierz normalny czas wykonania działania, a następnie dodaj margines dwu- lub trzykrotny, aby uwzględnić przypadki wolniejsze. Na koniec upewnij się, że wewnętrzny limit czasu klienta HTTP jest niższy niż start_to_close_timeout — w powyższym przykładzie 90 sekund wobec 2 minut — aby błąd był czysto propagowany z Twojego kodu, zamiast być ucinany przez platformę.

Idempotentność: warunek nienegocjowalny

Ponieważ działanie może być odtwarzane wielokrotnie z tymi samymi parametrami, musi ono wywoływać ten sam skutek niezależnie od liczby wykonań. Właściwość ta nazywa się idempotentnością, a jej brak zamienia politykę ponawiania prób w generator incydentów.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
    """DANGEROUS: if retried, credit is added multiple times!"""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://api.billing.com/credits/add",
            json={"user_id": user_id, "amount": amount}
        )
    return response.json()

Przerażający scenariusz jest powszechny: API rozliczeniowe przetwarza żądanie poprawnie, ale odpowiedź ginie w sieci. Działanie kończy się niepowodzeniem, platforma ponawia próbę, a klient otrzymuje uznanie środków dwukrotnie. Klucz idempotentności eliminuje ten problem, dając zdalnej usłudze możliwość rozpoznania już przetworzonego żądania.

@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
    """CORRECT: idempotency key prevents duplication."""
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"https://api.billing.com/credits/add",
            json={
                "user_id": user_id,
                "amount": amount,
                "idempotency_key": idempotency_key
            }
        )
    return response.json()

Wygeneruj klucz w workflow za pomocą workflow.uuid4(), co gwarantuje, że pozostanie on identyczny przy każdym odtworzeniu — klasyczne uuid.uuid4() wygenerowałoby nową wartość przy każdej próbie i anulowałoby całą ochronę. Gdy zdalna usługa nie oferuje tego mechanizmu, istnieją dwie inne ścieżki: operacja upsert w bazie danych (użycie INSERT ... ON CONFLICT UPDATE zamiast samego INSERT) lub weryfikacja wstępna, polegająca na sprawdzeniu stanu przed podjęciem działania.

Trzy profile konfiguracji

Wartości kalibruje się w zależności od charakteru operacji. Płatność lub powiadomienie muszą zakończyć się szybko sukcesem lub szybkim niepowodzeniem: krótki limit czasu, trzy próby, umiarkowane opóźnianie.

@workflows.activity(
    start_to_close_timeout=timedelta(seconds=30),
    retry_policy_max_attempts=3,
    retry_policy_backoff_coefficient=2.0,
)
async def process_payment(params: dict) -> dict:
    # ...
    pass

Przetwarzanie długotrwałe, takie jak generowanie raportów lub ciężkie wnioskowanie (inferencja), odwraca tę logikę: każda próba kosztuje znaczący czas obliczeniowy, więc autoryzujesz mniej prób z większymi odstępami.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=15),
    retry_policy_max_attempts=2,
    retry_policy_backoff_coefficient=3.0,
)
async def generate_ml_report(params: dict) -> dict:
    # ...
    pass

W obliczu niestabilnego API strony trzeciej podlegającego limitowaniu częstotliwości zapytań, zakładasz wreszcie uporczywość: pięć prób, nawet jeśli rozciąga się to na kilka minut.

@workflows.activity(
    start_to_close_timeout=timedelta(minutes=2),
    retry_policy_max_attempts=5,
    retry_policy_backoff_coefficient=2.0,
)
async def call_third_party_api(params: dict) -> dict:
    # ...
    pass

Kluczowe wnioski

  • Zawsze konfiguruj start_to_close_timeout, aby uniknąć blokowania działań
  • Wykładnicze opóźnianie (retry_policy_backoff_coefficient) zwiększa czas oczekiwania między próbami
  • retry_policy_max_attempts definiuje maksymalną liczbę prób przed ostatecznym niepowodzeniem
  • Działania z ponawianiem prób muszą być idempotentne — ten sam wynik przy wielokrotnym wykonaniu
  • Używaj kluczy idempotentności lub operacji upsert, aby zagwarantować idempotentność
  • Dostosuj limity czasu i liczbę prób do typu operacji (szybka vs długa, stabilna vs niestabilna)