tenacity-retry

--- name: tenacity-retry description: "Retry с tenacity: декораторы, backoff, jitter, async. Триггеры: 'retry', 'tenacity', 'backoff', 'exponential backoff', 'jitter', 'retry decorator', 'повторные попытки', 'rate limit retry'. НЕ для LangGraph RetryPolicy — используй langgraph-core." --- # Tenacity Retry — устойчивость к сбоям в PDF Framework ## Обзор Tenacity — стандартная Python-библиотека для retry-логики (15M+ скачиваний/неделю). Декораторный подход, работает с sync и async, поддерживает exponential backoff, jitter, условные retries. В PDF Framework есть готовые декораторы в `src/pdf_framework/utils/retry.py`. --- ## Быстрый справочник | Задача | Действие | |--------|----------| | Retry LLM вызова | `@retry_llm_call` (5 попыток, exp jitter, 120s max) | | Retry embedding | `@retry_embedding` (5 попыток, 90s max, +RuntimeError) | | Retry БД операции | `@retry_db_operation` (3 попытки, 0.5s fixed) | | Retry HTTP запроса | `@retry_network` (4 попытки, exp jitter, 60s max) | | Кастомный retry | `create_retry(max_attempts=N, ...)` | | Установка | `pip install tenacity` (>=9.1.4, Python >=3.10) | --- ## Готовые декораторы фреймворка ```python from src.pdf_framework.utils.retry import ( retry_llm_call, retry_embedding, retry_db_operation, retry_network, create_retry, ) ``` ### retry_llm_call — для API вызовов к LLM ```python @retry_llm_call async def call_claude(prompt: str) -> str: return await client.messages.create( model="claude-sonnet-4-5-20250929", messages=[{"role": "user", "content": prompt}], ) ``` | Параметр | Значение | |----------|----------| | Попытки | 5 или 120s (что раньше) | | Ожидание | Exponential jitter: 1s, 2s, 4s ... max 60s, +/-2s | | Retries на | `TimeoutError`, `ConnectionError`, `OSError` | | reraise | True (оригинальное исключение) | ### retry_embedding — для embedding API ```python @retry_embedding async def embed_text(text: str) -> list[float]: return await embedder.embed_query(text) ``` Отличие от LLM: короче таймауты (90s), ловит `RuntimeError` (CUDA/model loading). ### retry_db_operation — для Qdrant/SQLite ```python @retry_db_operation async def upsert_points(collection: str, points: list) -> None: await qdrant.upsert(collection_name=collection, points=points) ``` 3 попытки, fixed 0.5s — БД-операции быстрые, длинный backoff не нужен. ### retry_network — для HTTP ```python @retry_network async def fetch_url(url: str) -> bytes: async with httpx.AsyncClient() as client: resp = await client.get(url) resp.raise_for_status() return resp.content ``` ### create_retry — фабрика кастомных конфигов ```python retry_heavy = create_retry( max_attempts=10, max_delay=300.0, initial_wait=2.0, max_wait=120.0, jitter=5.0, retry_on=(TimeoutError, ConnectionError), ) @retry_heavy async def heavy_operation() -> None: ... ``` | Параметр | По умолчанию | Описание | |----------|-------------|----------| | `max_attempts` | 3 | Макс попыток | | `max_delay` | None | Общий таймаут (секунды) | | `initial_wait` | 1.0 | Начальная задержка (секунды) | | `max_wait` | 60.0 | Макс задержка (секунды) | | `jitter` | 1.0 | Случайный разброс (секунды) | | `retry_on` | Timeout+Connection+OS | Типы исключений для retry | --- ## Tenacity API — основные компоненты ### Wait-стратегии ```python from tenacity import ( wait_fixed, # Постоянная задержка wait_random, # Случайная в диапазоне wait_exponential, # Экспоненциальный backoff wait_random_exponential, # Full Jitter (AWS стиль) wait_exponential_jitter, # Google Cloud стиль wait_chain, # Последовательная цепочка wait_combine, # Суммирование стратегий ) # Комбинирование через + wait = wait_fixed(3) + wait_random(0, 2) # 3-5 секунд # Параметры wait_exponential_jitter (рекомендуется) wait = wait_exponential_jitter( initial=1, # Начальная задержка max=60, # Потолок exp_base=2, # База экспоненты jitter=2, # +/- случайный разброс ) ``` ### Stop-стратегии ```python from tenacity import stop_after_attempt, stop_after_delay # Комбинирование через | stop = stop_after_attempt(5) | stop_after_delay(120) # Что наступит раньше ``` ### Retry-условия ```python from tenacity import ( retry_if_exception_type, # Retry на конкретные exceptions retry_if_not_exception_type, # Retry на ВСЕ кроме указанных retry_if_result, # Retry если результат = predicate retry_if_exception_message, # Retry если message содержит строку retry_any, retry_all, # Комбинаторы ) # Комбинирование через | и & retry = ( retry_if_exception_type(TimeoutError) | retry_if_result(lambda x: x is None) ) ``` ### Callbacks ```python from tenacity import before_log, after_log, before_sleep_log @retry( before=before_log(logger, logging.DEBUG), after=after_log(logger, logging.DEBUG), before_sleep=before_sleep_log(logger, logging.WARNING), ) def fn(): ... # Кастомный callback def my_callback(retry_state): print(f"Attempt #{retry_state.attempt_number}") print(f"Exception: {retry_state.outcome.exception()}") print(f"Elapsed: {retry_state.seconds_since_start}s") ``` ### Runtime override ```python @retry(stop=stop_after_attempt(3)) def fn(): ... # Переопределить параметры для одного вызова fn.retry_with(stop=stop_after_attempt(10))() # Статистика fn.retry.statistics # {"attempt_number": 3, ...} ``` ### Async — бесшовная поддержка ```python # @retry автоматически определяет async @retry(stop=stop_after_attempt(3)) async def async_fn(): await some_operation() # Или через AsyncRetrying context manager from tenacity import AsyncRetrying async for attempt in AsyncRetrying(stop=stop_after_attempt(3)): with attempt: result = await some_operation() ``` --- ## Шаблоны ### Шаблон 1: Retry с rate limit (LLM API) ```python from tenacity import retry, wait_random_exponential, stop_after_attempt, retry_if_exception_type @retry( wait=wait_random_exponential(min=1, max=60), stop=stop_after_attempt(6), retry=retry_if_exception_type((TimeoutError, ConnectionError)), reraise=True, ) async def call_api(prompt: str) -> str: return await [CLIENT].messages.create( model="[MODEL]", messages=[{"role": "user", "content": prompt}], ) ``` ### Шаблон 2: Retry с fallback значением ```python from tenacity import retry, stop_after_attempt, retry_if_exception_type @retry( stop=stop_after_attempt(3), retry=retry_if_exception_type(ConnectionError), retry_error_callback=lambda state: "[DEFAULT_VALUE]", ) def fetch_with_fallback() -> str: return requests.get("[URL]").text ``` ### Шаблон 3: Code block retry (без декоратора) ```python from tenacity import Retrying, stop_after_attempt for attempt in Retrying(stop=stop_after_attempt(3)): with attempt: result = dangerous_operation() # result доступен после цикла ``` --- ## Диагностика | Проблема | Причина | Решение | |----------|---------|---------| | Бесконечный retry | Нет stop condition | Добавить `stop=stop_after_attempt(N)` | | RetryError вместо оригинального | `reraise=False` (default) | Установить `reraise=True` | | Retry на ValueError/TypeError | Слишком широкий retry condition | Использовать `retry_if_exception_type(...)` | | Thundering herd при восстановлении | Фиксированный wait без jitter | Использовать `wait_exponential_jitter` | | Retry не работает с async | Старая версия tenacity | Обновить до >=9.0 | | Логи не показывают retries | Нет callback | Добавить `before_sleep=before_sleep_log(...)` | --- ## Антипаттерны | Плохо | Почему | Как правильно | |-------|--------|---------------| | `@retry` без параметров | Бесконечный retry без задержки | `@retry(stop=stop_after_attempt(5), wait=...)` | | `retry_if_exception_type(Exception)` | Retry на программные ошибки | Только transient: TimeoutError, ConnectionError | | `wait_fixed(1)` для API | Thundering herd | `wait_exponential_jitter(initial=1, max=60)` | | `from tenacity import *` | Wildcard import | Явные импорты | | Свой retry-цикл вместо tenacity | Boilerplate, нет jitter | Использовать декораторы из utils/retry.py | --- ## Ссылки | Ресурс | URL | |--------|-----| | Документация | https://tenacity.readthedocs.io/ | | GitHub | https://github.com/jd/tenacity | | PyPI | https://pypi.org/project/tenacity/ | | API Reference | https://tenacity.readthedocs.io/en/latest/api.html | | AWS Exponential Backoff | https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/ |