Polityka ponawiania prób
Na tej stronie
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_attemptsdefiniuje 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)