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

Обработка на грешки и внедряване в продукция

Урок 12 от 12 Обновен 3 ноември 2026 г. Средно
На тази страница
  1. Подгответе приложението си за продукция
  2. Две семейства грешки, два момента
  3. Повтаряйте интелигентно
  4. Опашка, за да поддържате темпото
  5. Проверете ключа си, преди да разчитате на него
  6. Вижте какво се случва в продукция
  7. Ключови изводи
  8. Проверете знанията си

Актуализирано на 2 ноември 2026 г. въз основа на документацията за видео на xAI и кода на xai-sdk 1.21.0: client.video.generate (не client.videos), резултатът е в url, неуспехите се докладват чрез VideoGenerationError с код (invalid_argument, service_unavailable…), ограничението на скоростта се получава като grpc.RpcError с код RESOURCE_EXHAUSTED — класът RateLimitError и статусът expired не съществуват. Допълнение от 3 ноември 2026 г.: ограничението на скоростта брои заявките в секунда (10 за началното ниво), а не “60 RPM”, а действителната цена за генериране се чете от usage.cost_in_usd_ticks. Източници: Генериране на видео · Ограничения на скоростта.

Подгответе приложението си за продукция

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

Две семейства грешки, два момента

Първото семейство се появява веднага, в момента на POST повикването. Това са строги грешки в заявката и HTTP кодът е достатъчен, за да решите какво да предприемете.

HTTP КодПричинаРешение
400Невалидни параметри (например неизвестен глас в reference_audios)Поправете заявката
401Невалиден или изтекъл API ключПроверете удостоверяването
429Надвишено ограничение на скоростта (заявки в секунда, в зависимост от нивото)Приложете backoff (експоненциално забавяне)
500Грешка на сървъраПовторен опит с експоненциално забавяне

Второто семейство се проявява много по-късно, по време на анкетирането (polling), след като заявката е приета и генерирането е започнало.

СтатусВероятна причинаДействие
failed + invalid_argument или permission_deniedЗаявката или съдържанието са отхвърлениПроменете подканаващия текст (prompt) или източника
failed + service_unavailable или internal_errorПретоварена услуга, инцидентПовторен опит по-късно

Това разграничение не е академично: код 400 трябва незабавно да се върне на подателя, защото грешката е в кода, докато статус failed възниква след няколко минути чакане и трябва да се обработва в контекста на задачата, а не в HTTP заявката, която я е задействала.

Повтаряйте интелигентно

Общата основа е експоненциалното забавяне (exponential backoff) с известно разсейване (jitter). Удвояването на закъснението дава време на преходен инцидент да се разреши, а разсейването предотвратява всички ваши процеси да правят повторен опит в един и същи момент след пик — явление, което превръща микро-прекъсването в траен срив.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Executes a function with retry and exponential backoff."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Exponential backoff with jitter
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Attempt {attempt + 1} failed: {e}. Retrying in {delay:.1f}s")
            await asyncio.sleep(delay)

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

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Failure codes that a retry will not fix
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Video generation with targeted retry (client: xai_sdk.AsyncClient)."""
    for attempt in range(max_retries + 1):
        is_last = attempt == max_retries
        try:
            return await client.video.generate(**params)
        except VideoGenerationError as e:
            if e.code.lower() in REQUIRES_FIX or is_last:
                raise  # request or content refused: fix before relaunching
            await asyncio.sleep(5 * (attempt + 1))  # service overloaded, incident
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # rate limit: backoff
        except TimeoutError:
            if is_last:
                raise
            # Allow more time for the next attempt
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Опашка, за да поддържате темпото

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

import asyncio
from collections import deque

class VideoGenerationQueue:
    def __init__(self, client, max_concurrent=10):
        self.client = client
        self.queue = deque()
        self.semaphore = asyncio.Semaphore(max_concurrent)
        self.results = {}

    async def add(self, job_id, params):
        """Adds a generation to the queue."""
        self.queue.append((job_id, params))

    async def process(self):
        """Processes all pending generations."""
        tasks = []
        while self.queue:
            job_id, params = self.queue.popleft()
            task = asyncio.create_task(
                self._execute(job_id, params)
            )
            tasks.append(task)
        await asyncio.gather(*tasks, return_exceptions=True)

    async def _execute(self, job_id, params):
        """Executes a generation with concurrency control."""
        async with self.semaphore:
            try:
                result = await generate_with_retry(
                    self.client, params
                )
                self.results[job_id] = {
                    "status": "done",
                    "url": result.url
                }
            except Exception as e:
                self.results[job_id] = {
                    "status": "failed",
                    "error": str(e)
                }

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

Вторият рефлекс на архитектурата касае съхранението. Тъй като URL адресите на видеоклиповете са временни, изтеглянето трябва да бъде автоматично и незабавно, с именуване с времеви печат, което гарантира липсата на сблъсък между две едновременни генерирания.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Downloads and saves a generated video."""
    Path(output_dir).mkdir(parents=True, exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = f"{output_dir}/video_{timestamp}.mp4"

    async with httpx.AsyncClient() as client:
        resp = await client.get(video_url)
        resp.raise_for_status()
        Path(file_path).write_bytes(resp.content)

    return file_path

Проверете ключа си, преди да разчитате на него

Крайната точка GET /v1/api-key ви информира за състоянието на вашия ключ. Извикването ѝ при стартиране на услугата избягва откриването на блокиран ключ след двадесет неуспешни заявки, докато потребителите ви чакат.

resp = httpx.get(
    "https://api.x.ai/v1/api-key",
    headers={"Authorization": f"Bearer {api_key}"}
).json()

if resp.get("api_key_blocked") or resp.get("api_key_disabled") or resp.get("team_blocked"):
    raise RuntimeError("API key or team blocked, or key disabled")

Вижте какво се случва в продукция

Пет индикатора са достатъчни, за да управлявате услуга за генериране на видео. Степента на успех, т.е. дялът на генериранията, завършващи със статус done, измерва общото здраве на системата. Средното време за генериране, измерено между подаването и статуса done, служи за калибриране на вашите таймаути и информиране на потребителите ви. Степента на грешки, разбита по типове — failed по код на грешка, таймаут, ограничение на скоростта — ви казва къде да насочите усилията: повишаване на таймаутите без повишаване на failed сигнализира за генерирания, по-бавни от вашия краен срок за изчакване, например, а не за неуспехи. Кумулативната цена, получена чрез сумиране на полето usage.cost_in_usd_ticks от всеки резултат (един долар е равен на 10 милиарда тикове), или алтернативно чрез умножаване на генерираните продължителности по цената на модела за секунда, трябва да се следи ежедневно. Накрая, използването на квотата, в заявки в секунда спрямо ограничението на вашето ниво (10 за началното ниво за видео модели), предвижда насищането, преди то да се превърне в 429 грешки.

Тези метрики се изграждат естествено от структуриран дневник (log), където всяко генериране оставя ред, използваем от вашия инструмент за анализ.

import logging
import json

logger = logging.getLogger("video-generation")

def log_generation(request_id, status, duration_s, cost, time_ms):
    logger.info(json.dumps({
        "event": "video_generation",
        "request_id": request_id,
        "status": status,
        "duration_seconds": duration_s,
        "cost_usd": cost,
        "processing_time_ms": time_ms
    }))

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

Цените са проверени на 3 ноември 2026 г. — цените се променят редовно: преди всяко изчисление на бюджета, проверете текущата тарифа на официалната страница за модели и цени на xAI.

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

  • Грешките се разделят на синхронни (заявка) и асинхронни (генериране)
  • Не всички грешки заслужават повторен опит: модерирането е окончателно
  • Използвайте семафор, за да ограничите едновременните генерирания
  • Временните URL адреси изискват незабавно и систематично изтегляне
  • Следете метриките за разходи, успех и време за генериране, за да управлявате услугата си

Проверете знанията си

Генеративно видео в продукция: валидирайте целия работен поток.

1. Какви са особеностите на подканаващия текст (prompt) за видео?

Отговор: Опишете действието и движението, а не само сцената: обект, преместване, атмосфера, кадриране — времевото измерение е това, което отличава видео подканата от тази за изображение.

2. Какво позволява функцията „изображение към видео“?

Отговор: Анимиране на съществуващо изображение или въвеждане на дадени хора и продукти в нова сцена чрез референтни изображения — и, при grok-imagine-video-1.5, закрепване на първото, последното или ключовите изображения: вашата визуална идентичност става отправна точка, а не случайност.

3. Редактиране и разширяване: какви употреби?

Отговор: /videos/edits модифицира генерирано видео, /videos/extensions го удължава — и двете се комбинират, за да изградят дълги последователности чрез итерации.

4. Защо работният поток е асинхронен?

Отговор: Генерирането на видео отнема време: подавате задача, проверявате статуса ѝ, след което извличате резултата — xAI SDK автоматизира това анкетиране.

5. Какво да планирате за продукция?

Отговор: Обработка на грешки и неуспешни задачи, незабавно изтегляне на изходните данни и проследяване на разходите (резолюция, продължителност, итерации) — видеото е най-скъпият модалитет: то трябва да бъде бюджетирано.

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