Премини към основното съдържание
Български— Изберете език
Меню

Политика за повторни опити

Урок 12 от 14 Обновен 29 юли 2026 г. Напреднало
На тази страница
  1. Защо повторните опити са от съществено значение
  2. Конфигуриране на политика за повторни опити
  3. Никога не пропускайте start_to_close_timeout
  4. Идемпотентност: неизменно условие
  5. Три профила за конфигурация
  6. Ключови изводи

Защо повторните опити са от съществено значение

В разпределените системи преходните грешки са неизбежни: изтичане на времето за мрежова връзка, надвишаване на лимитите за честота, временно недостъпни услуги. Нито една от тези повреди не показва бъг във Вашия код, но всяка от тях може да доведе до провал на процеса, ако нищо не поеме удара. Политиката за повторни опити позволява на Вашите дейности да оцелеят при тези грешки без намеса от човек, като платформата автоматично ги стартира отново според конфигурацията, която дефинирате за всяка дейност.

Конфигуриране на политика за повторни опити

Декораторът @workflows.activity() приема параметри, които управляват това поведение. Ето пример за дейност за външно API обаждане, правилно подготвена за устойчивост.

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

Три параметъра, три допълващи се роли.

  • start_to_close_timeout — Максимална продължителност за едно изпълнение. Ако дейността не приключи в този timeframe, тя се счита за неуспешна и се стартира нов опит.

  • retry_policy_max_attempts — Максимален брой опити. Стойността по подразбиране зависи от платформата. След този брой опити дейността се проваля окончателно и работният поток получава грешка.

  • retry_policy_backoff_coefficient — Множител за забавянето между опитите. При коефициент 2.0 забавянията се удвояват с всеки опит (1 сек, 2 сек, 4 сек, 8 сек…). Това е експоненциално отстъпване (exponential backoff).

Този механизъм на отстъпване заслужава внимание, защото целта му не е просто изчакване: той дава време на затруднената услуга да се възстанови, вместо да я затрупвате със заявки. Прогресията на обаждане, което в крайна сметка успява, илюстрира това ясно.

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!

Срещу отговор “429 Too Many Requests” този механизъм е особено ефективен: политика, която прави повторен опит веднага, само ще поддържа претоварването, докато увеличаването на интервалите в крайна сметка спада под прага на доставчика.

Никога не пропускайте start_to_close_timeout

Този таймаут е критичен и трябва да присъства във всяка дейност, без изключение. Без него дейност, която заседне – задънена ситуация (deadlock), висяща връзка, услуга, която приема заявката, но никога не отговаря – чака безкрайно и замразява целия работен поток. По-лошо: не задейства повторен опит, тъй като от нейна гледна точка все още не е се е провалила.

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

За да зададете стойността, първо измерете нормалното време за изпълнение на дейността, след това добавете марж от два до три пъти, за да покриете бавните случаи. Накрая, уверете се, че вътрешният таймаут на HTTP клиента остава по-нисък от start_to_close_timeout – в горния пример 90 секунди срещу 2 минути – така че грешката да се разпространи чисто от Вашия код, вместо да бъде прекъсната от платформата.

Идемпотентност: неизменно условие

Тъй като една дейност може да бъде възпроизведена многократно със същите параметри, тя трябва да произвежда един и същ ефект независимо от броя на изпълненията. Това свойство се нарича идемпотентност и липсата ѝ превръща политиката за повторни опити в генератор на инциденти.

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

Опасният сценарий е често срещан: API за фактуриране обработва заявката правилно, но отговорът се губи в мрежата. Дейността заключава, че е неуспешна, платформата прави повторен опит и клиентът получава кредит два пъти. Ключът за идемпотентност елиминира проблема, като дава на отдалечената услуга начин да разпознае вече обработена заявка.

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

Генерирайте ключа в работния поток, използвайки workflow.uuid4(), което гарантира, че той остава идентичен от едно възпроизвеждане до друго – класически uuid.uuid4() би произвел нова стойност при всеки опит и би анулирал цялата защита. Когато отдалечената услуга не предлага този механизъм, съществуват два други пътя: upsert в базата данни, използвайки INSERT ... ON CONFLICT UPDATE вместо само INSERT, или проверка преди действие, което включва заявка на състоянието преди изпълнение.

Три профила за конфигурация

Стойностите се калибрират според естеството на операцията. Плащане или известие трябва да успеят бързо или да се провалят бързо: кратък таймаут, три опита, умерено отстъпване.

@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

Обработка с дълга продължителност, като генериране на отчети или тежко машинно обучение (inference), обръща логиката: всеки опит струва значително изчислително време, затова разрешавате по-малко опити с по-големи интервали.

@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

Срещу нестабилно API на трета страна, подлежащо на ограничаване на честотата, най-накрая залагате на постоянство: пет опита, дори ако това отнеме няколко минути.

@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

Ключови изводи

  • Винаги конфигурирайте start_to_close_timeout, за да избегнете блокиране на дейностите
  • Експоненциалното отстъпване (retry_policy_backoff_coefficient) увеличава забавянето между опитите
  • retry_policy_max_attempts дефинира максималния брой опити преди окончателен провал
  • Дейностите с повторни опити трябва да бъдат идемпотентни – един и същ резултат при многократно изпълнение
  • Използвайте ключове за идемпотентност или upserts, за да гарантирате идемпотентност
  • Адаптирайте таймаутите и броя на повторните опити към типа операция (бърза срещу дълга, стабилна срещу нестабилна)