Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Retry-politik

Lektion 12 af 14 Opdateret 29. juli 2026 Avanceret
På denne side
  1. Hvorfor genforsøg er afgørende
  2. Konfiguration af en retry-politik
  3. Udelad aldrig start_to_close_timeout
  4. Idempotens: En ikke-forhandlingsbetinget betingelse
  5. Tre konfigurationsprofiler
  6. Vigtige pointer

Hvorfor genforsøg er afgørende

I et distribueret system er forbigående fejl uundgåelige: netværks-timeouts, overskredne hastighedsgrænser eller midlertidigt utilgængelige tjenester. Ingen af disse fejl indikerer en bug i din kode, men enhver af dem kan få en proces til at fejle, hvis intet absorberer chokket. En retry-politik lader dine aktiviteter overleve disse fejl uden manuel indgriben, idet platformen automatisk genstarter dem i henhold til den konfiguration, du definerer for hver aktivitet.

Konfiguration af en retry-politik

Dekoratøren @workflows.activity() accepterer parametre, der styrer denne adfærd. Her er en aktivitet, der kalder en ekstern API, korrekt rustet til modstandsdygtighed.

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

Tre parametre, tre komplementære roller.

  • start_to_close_timeout — Maksimal varighed for et enkelt executionsforsøg. Hvis aktiviteten ikke fuldføres inden for denne tidsramme, betragtes den som fejlet, og et nyt forsøg startes.

  • retry_policy_max_attempts — Maksimalt antal forsøg. Standardværdien afhænger af platformen. Efter dette antal forsøg fejler aktiviteten endeligt, og workflow’et modtager en fejl.

  • retry_policy_backoff_coefficient — Multiplikator for forsinkelsen mellem forsøg. Med en koefficient på 2,0 fordobles forsinkelserne ved hvert forsøg (1 s, 2 s, 4 s, 8 s…). Dette kaldes eksponentiel backoff.

Denne backoff-mekanisme fortjener opmærksomhed, fordi formålet ikke blot er at vente: den giver den struggling service tid til at komme sig, i stedet for at hamre løs på den. Forløbet for et opkald, der til sidst lykkes, illustrerer dette tydeligt.

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!

Over for et svar „429 Too Many Requests” er denne mekanisme særligt effektiv: En politik, der genforsøgte øjeblikkeligt, ville kun opretholde mætningen, hvorimod øget afstand til sidst bringer belastningen under udbyderens grænseværdi.

Udelad aldrig start_to_close_timeout

Denne timeout er kritisk og skal forekomme på hver eneste aktivitet uden undtagelse. Uden den vil en aktivitet, der hænger fast – deadlock, hængende forbindelse eller en service, der accepterer anmodningen men aldrig svarer – vente på ubestemt tid og fryse hele workflow’et. Værre endnu: Den udløser intet genforsøg, da den fra sit perspektiv endnu ikke er fejlet.

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

For at fastsætte værdien skal du først måle den normale executionstid for aktiviteten og derefter lægge en margin på to til tre gange til for at dække langsomme tilfælde. Sørg endelig for, at timeout-værdien for den interne HTTP-klient forbliver lavere end start_to_close_timeout – i eksemplet ovenfor 90 sekunder mod 2 minutter – så fejlen propagerer rent fra din kode i stedet for at blive afbrudt af platformen.

Idempotens: En ikke-forhandlingsbetinget betingelse

Da en aktivitet kan afspilles flere gange med de samme parametre, skal den producere den samme effekt uanset antallet af executioner. Denne egenskab kaldes idempotens, og fraværet af den gør en retry-politik til en generator af incidenter.

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

Det frygtede scenarie er almindeligt: Billing-API’en behandler anmodningen korrekt, men svaret går tabt på netværket. Aktiviteten konkluderer fejl, platformen genforsøger, og kunden får krediteret to gange. En idempotens-nøgle eliminerer problemet ved at give den eksterne service en måde at genkende en allerede behandlet anmodning på.

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

Generér nøglen i workflow’et ved hjælp af workflow.uuid4(), hvilket garanterer, at den forbliver identisk fra én afspilning til en anden – en klassisk uuid.uuid4() ville producere en ny værdi ved hvert forsøg og ophæve al beskyttelse. Når den eksterne service ikke tilbyder denne mekanisme, findes der to andre veje: Upsert i databasen ved at bruge INSERT ... ON CONFLICT UPDATE i stedet for blot INSERT, eller pre-check-verifikation, hvilket indebærer at spørge til tilstanden før handling.

Tre konfigurationsprofiler

Værdierne kalibreres efter operationens art. En betaling eller notifikation skal enten lykkes hurtigt eller fejle hurtigt: kort timeout, tre forsøg, moderat 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

Langvarig behandling, såsom rapportgenerering eller tung inferens, vender logikken på hovedet: Hvert forsøg koster betydelig beregningstid, så du autoriserer færre forsøg med større afstand.

@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

Over for en ustabil tredjeparts-API, der er underlagt hastighedsbegrænsninger, må du endelig regne med udholdenhed: Fem forsøg, selvom det strækker sig over flere minutter.

@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

Vigtige pointer

  • Konfigurér altid start_to_close_timeout for at undgå blokerende aktiviteter
  • Eksponentiel backoff (retry_policy_backoff_coefficient) øger forsinkelsen mellem forsøg
  • retry_policy_max_attempts definerer det maksimale antal forsøg før endeligt fiasko
  • Aktiviteter med genforsøg skal være idempotente – samme resultat ved flere executioner
  • Brug idempotens-nøgler eller upserts for at garantere idempotens
  • Tilpas timeouts og antal genforsøg til operationstypen (hurtig vs. lang, stabil vs. ustabil)