Zásady opakování
Na této stránce
Proč jsou opakování nezbytná
V distribuovaném systému jsou přechodné chyby nevyhnutelné: vypršení časového limitu sítě, překročení limitů rychlosti nebo dočasně nedostupné služby. Žádná z těchto chyb neznamená chybu ve tvém kódu, ale každá z nich může způsobit selhání procesu, pokud ji nic neabsorbuje. Zásady opakování umožňují tvým aktivitám přežít tyto chyby bez manuálního zásahu, přičemž platforma je automaticky znovu spustí podle konfigurace, kterou pro každou aktivitu definuješ.
Konfigurace zásad opakování
Dekorátor @workflows.activity() přijímá parametry, které toto chování řídí. Zde je ukázka aktivity volající externí API, která je správně vybavena pro odolnost.
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:
"""Volá externí API s automatickým opakováním."""
async with httpx.AsyncClient(timeout=60) as client:
response = await client.post(url, json=data)
response.raise_for_status()
return response.json()
Tři parametry, tři doplňkové role.
-
start_to_close_timeout— Maximální délka trvání jednoho pokusu o provedení. Pokud se aktivita v tomto časovém rámci nedokončí, je považována za selhanou a je spuštěn nový pokus. -
retry_policy_max_attempts— Maximální počet pokusů. Výchozí hodnota závisí na platformě. Po dosažení tohoto počtu pokusů aktivita definitivně selže a workflow obdrží chybu. -
retry_policy_backoff_coefficient— Násobitel prodlevy mezi pokusy. Při koeficientu 2,0 se prodlevy s každým pokusem zdvojnásobí (1 s, 2 s, 4 s, 8 s…). Jedná se o exponenciální backoff.
Tento mechanismus backoff si zaslouží pozornost, protože jeho účelem není jen čekat: dává trpící službě čas na zotavení, místo aby byla bombardována požadavky. Průběh volání, které nakonec uspěje, to jasně ilustruje.
Pokus 1: okamžité provedení
→ Selhání (vypršel časový limit sítě)
→ Čekání 1 sekunda
Pokus 2: provedení
→ Selhání (služba nedostupná)
→ Čekání 2 sekundy (1 × 2,0)
Pokus 3: provedení
→ Selhání (limit rychlosti)
→ Čekání 4 sekundy (2 × 2,0)
Pokus 4: provedení
→ Úspěch!
Při odpovědi „429 Too Many Requests“ je tento mechanismus obzvláště účinný: zásada, která by opakovala okamžitě, by pouze udržovala saturaci, zatímco zvyšování rozestupů nakonec klesne pod práh poskytovatele.
Nikdy nevynechávej start_to_close_timeout
Tento časový limit je kritický a musí se objevit u každé aktivity, bez výjimky. Bez něj aktivita, která se zasekne (deadlock, visící připojení, služba, která přijme požadavek, ale nikdy neodpoví), čeká donekonečna a zmrazí celé workflow. Horší je, že nespustí žádné opakování, protože z jejího pohledu ještě nedošlo k selhání.
# ŠPATNÁ PRAXE: žádný časový limit
@workflows.activity()
async def dangerous_activity(params: dict) -> dict:
# Pokud služba nikdy neodpoví, aktivita čeká donekonečna
async with httpx.AsyncClient() as client:
response = await client.get("https://api.lente.example.com/data")
return response.json()
# DOBRÁ PRAXE: explicitní časový limit
@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()
Pro nastavení hodnoty nejprve změř běžnou dobu provádění aktivity a poté přidej rezervu dvou až trojnásobku pro pokrytí pomalých případů. Nakonec se ujisti, že interní časový limit klienta HTTP zůstává nižší než start_to_close_timeout – v příkladu výše 90 sekund versus 2 minuty – aby se chyba čistě šířila z tvého kódu, místo aby byla přerušena platformou.
Idempotence: nepostradatelná podmínka
Protože lze aktivitu přehrát vícekrát se stejnými parametry, musí produkovat stejný efekt bez ohledu na počet provedení. Této vlastnosti se říká idempotence a její absence promění zásady opakování v generátor incidentů.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float) -> dict:
"""NEBEZPEČNÉ: při opakování bude kredit připsán vícekrát!"""
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()
Obávaný scénář je běžný: fakturační API zpracuje požadavek správně, ale odpověď se ztratí v síti. Aktivita vyhodnotí selhání, platforma to zkusí znovu a zákazník dostane kredit dvakrát. Klíč idempotence tento problém eliminuje tím, že vzdálené službě poskytne způsob, jak rozpoznat již zpracovaný požadavek.
@workflows.activity(retry_policy_max_attempts=3)
async def add_credit(user_id: str, amount: float, idempotency_key: str) -> dict:
"""SPRÁVNĚ: klíč idempotence zabraňuje duplikaci."""
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()
Klíč vygeneruj ve workflow pomocí workflow.uuid4(), což zaručuje, že zůstane totožný od jednoho přehrání k druhému – klasické uuid.uuid4() by při každém pokusu vyprodukovalo novou hodnotu a zrušilo veškerou ochranu. Pokud vzdálená služba tento mechanismus nenabízí, existují dvě další cesty: upsert v databázi pomocí INSERT ... ON CONFLICT UPDATE místo samotného INSERT, nebo ověření předběžnou kontrolou, což zahrnuje dotazování stavu před provedením akce.
Tři konfigurační profily
Hodnoty se kalibrují podle povahy operace. Platba nebo oznámení musí rychle uspět, nebo rychle selhat: krátký časový limit, tři pokusy, mírný backoff.
@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
Dlouho běžící zpracování, jako je generování reportů nebo náročná inference, obrací logiku: každý pokus stojí významný výpočetní čas, takže povolíš méně pokusů s většími rozestupy.
@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
Tváří v tvář nestabilnímu API třetí strany podléhajícímu omezování rychlosti nakonec předpokládáš vytrvalost: pět pokusů, i když to zabere několik 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
Klíčové poznatky
- Vždy konfiguruj
start_to_close_timeout, abys předešel blokování aktivit - Exponenciální backoff (
retry_policy_backoff_coefficient) zvyšuje prodlevu mezi pokusy retry_policy_max_attemptsdefinuje maximální počet pokusů před definitivním selháním- Aktivity s opakováním musí být idempotentní – stejný výsledek při více provedeních
- Používej klíče idempotence nebo upserty k zajištění idempotence
- Přizpůsob časové limity a počty opakování typu operace (rychlá vs. dlouhá, stabilní vs. nestabilní)