Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Zpracování chyb a nasazení do produkce

Lekce 12 z 12 Aktualizováno 3. listopadu 2026 Mírně pokročilý
Na této stránce
  1. Připrav svou aplikaci na produkci
  2. Dvě rodiny chyb, dva okamžiky
  3. Opakuj chytře
  4. Fronta pro udržení tempa
  5. Ověř svůj klíč, než se na něj spolehneš
  6. Vidět, co se děje v produkci
  7. Klíčové poznatky
  8. Ověř své znalosti

Aktualizováno 2. listopadu 2026 na základě dokumentace videa od xAI a kódu xai-sdk 1.21.0: client.video.generate (nikoli client.videos), výsledek v url, selhání hlášena pomocí VideoGenerationError s kódem (invalid_argument, service_unavailable…), omezení rychlosti přijato jako grpc.RpcError s kódem RESOURCE_EXHAUSTED — třída RateLimitError a stav expired neexistují. Doplněk z 3. listopadu 2026: omezení rychlosti počítá požadavky za sekundu (10 u vstupní úrovně), nikoli „60 RPM“, a skutečné náklady na generaci se čtou z usage.cost_in_usd_ticks. Zdroje: Generování videa · Omezení rychlosti.

Připrav svou aplikaci na produkci

Skript, který generuje video na tvém stroji, a služba, která vyrábí stovky videí denně pro skutečné uživatele, nemají téměř nic společného. Ta druhá musí zvládat odmítnutí moderací, překročení kvót, výpadky serverů a expiraci URL adres, aniž by kdy mlčky ztratila zpoplatněnou generaci. Tato lekce pokrývá mechanismy, které dělají rozdíl: klasifikace chyb, strategie opakování, architektura fronty a pozorovatelnost.

Dvě rodiny chyb, dva okamžiky

První rodina se objeví okamžitě, v momentě volání POST. Jde o striktní chyby požadavku a kód HTTP stačí k rozhodnutí, co dělat.

Kód HTTPPříčinaŘešení
400Neplatné parametry (například neznámý hlas v reference_audios)Oprav požadavek
401Neplatný nebo expirovaný klíč APIOvěř autentizaci
429Překročeno omezení rychlosti (požadavky za sekundu, závisí na úrovni)Implementuj backoff
500Chyba serveruOpakuj s exponenciálním backoffem

Druhá rodina se projeví mnohem později, během dotazování (polling), poté, co byl požadavek přijat a generování začalo.

StavPravděpodobná příčinaAkce
failed + invalid_argument nebo permission_deniedPožadavek nebo obsah odmítnutUprav prompt nebo zdroj
failed + service_unavailable nebo internal_errorPřetížená služba, incidentOpakuj později

Toto rozlišení není akademické: chyba 400 se musí okamžitě vrátit volajícímu, protože chyba je v kódu, zatímco stav failed nastane po několika minutách čekání a musí být zpracován v kontextu úlohy, nikoli v HTTP požadavku, který ji spustil.

Opakuj chytře

Společným základem je exponenciální backoff s určitým jitterem. Zdvojnásobení prodlevy dá přechodnému incidentu čas na vyřešení a jitter zabrání tomu, aby všechny tvé procesy opakovaly pokus ve stejný okamžik po špičce — jev, který mění mikrovýpadek v trvalé selhání.

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)

Tento obecný schéma však nestačí, protože ne všechny chyby si zaslouží stejnou trpělivost. Překročení kvóty se vyřeší čekáním celou minutu; odmítnutí moderací se nikdy nevyřeší a opakování znamená platit mnohokrát za stejné selhání. Následující funkce rozlišuje tyto případy.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Kódy selhání, které opakování neopraví
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)

Fronta pro udržení tempa

Jakmile tvoje služba začne přijímat požadavky od více uživatelů, musíš oddělit přijímání požadavků od jejich执行 a především omezit souběžnost, abys zůstal pod limitem rychlosti své úrovně. Fronta spárovaná se semaforem splňuje obě potřeby: úlohy se libovolně hromadí, ale najednou běží maximálně deset.

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

Všimni si, že každá úloha si uchovává svůj výsledek v results, ať už úspěch nebo selhání: generace, která zmizí bez stopy, je incident, který nikdo nedokáže diagnostikovat.

Druhým reflexem architektury je úložiště. Protože jsou URL adresy videí dočasné, stahování musí být automatické a okamžité, s pojmenováním podle časového razítka, které zaručí žádnou kolizi mezi dvěma současnými generacemi.

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

Ověř svůj klíč, než se na něj spolehneš

Koncový bod GET /v1/api-key tě informuje o stavu tvého klíče. Jeho zavolání při startu služby ti zabrání objevit zablokovaný klíč až po dvaceti neúspěšných požadavcích, zatímco tvoji uživatelé čekají.

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

Vidět, co se děje v produkci

Pět ukazatelů stačí k řízení služby pro generování videa. Míra úspěšnosti, tedy podíl generací končících stavem done, měří celkové zdraví. Průměrná doba generování, měřená mezi odesláním a stavem done, slouží ke kalibraci tvých časových limitů a informování uživatelů. Míra chyb rozdělená podle typu — failed podle kódu chyby, časový limit, omezení rychlosti — ti říká, kam soustředit úsilí: nárůst časových limitů bez nárůstu failed signalizuje například generace pomalejší než tvůj čekací deadline, nikoli selhání. Kumulativní náklady, získané sečtením pole usage.cost_in_usd_ticks z každého výsledku (jeden dolar se rovná 10 miliardám tiků), nebo alternativně vynásobením vygenerovaných délek cenou modelu za sekundu, musí být sledovány denně. Nakonec využití kvóty, v požadavcích za sekundu vůči limitu tvé úrovně (10 u vstupní úrovně pro video modely), předvídá nasycení dříve, než se projeví jako chyby 429.

Tyto metriky přirozeně vznikají ze strukturovaného logu, kde každá generace zanechá řádek použitelný pro tvůj analytický nástroj.

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

Než otevřeš svou službu veřejnosti, zkontroluj vše od začátku. Opakování s exponenciálním backoffem a jitterem musí být na místě a souběžnost omezena semaforem, aby zůstala pod limitem rychlosti. Stahování videí se musí spustit automaticky, jakmile jsou připravena, bez závislosti na lidském zásahu. Každá generace musí zanechat řádek v logu nesoucí své request_id, stav a náklady, jinak míra chyb a průměrná doba generování zůstanou neověřitelné. Zkontroluj stav klíče API při startu, nikoli až při prvním selhání. A nastav rozpočet s alerty při překročení: při 0,05 $ za sekundu spotřebuje neomezená smyčka opakování peníze rychleji, než si myslíš.

Ceny ověřeny 3. listopadu 2026 — ceny se pravidelně vyvíjejí: před jakýmkoli výpočtem rozpočtu ověř aktuální ceník na oficiální stránce modelů a cen xAI.

Klíčové poznatky

  • Chyby se dělí na synchronní (požadavek) a asynchronní (generování)
  • Ne všechny chyby si zaslouží opakování: moderace je definitivní
  • Použij semafor k omezení souběžných generací
  • Dočasné URL vyžadují okamžité a systematické stahování
  • Sleduj metriky nákladů, úspěšnosti a doby generování pro řízení své služby

Ověř své znalosti

Generativní video v produkci: validuj celý pracovní postup.

1. Jaké jsou zvláštnosti video promptu?

Odpověď: Popiš akci a pohyb, nejen scénu: subjekt, přesun, atmosféra, záběr — časová dimenze je tím, co odlišuje video prompt od obrazového promptu.

2. Co umožňuje image-to-video?

Odpověď: Animovat existující obrázek nebo vložit dané lidi a produkty do nové scény pomocí referenčních obrázků — a na grok-imagine-video-1.5 připnout první, poslední nebo klíčové snímky: tvá vizuální identita se stává výchozím bodem, nikoli náhodnou událostí.

3. Úpravy a rozšíření: jaká využití?

Odpověď: /videos/edits upravuje vygenerované video, /videos/extensions jej prodlužuje — a obojí se kombinuje k budování dlouhých sekvencí iteracemi.

4. Proč je pracovní postup asynchronní?

Odpověď: Generování videa trvá čas: odešleš úlohu, dotazuješ se na její stav a poté získáš výsledek — SDK xAI toto dotazování automatizuje.

5. Co plánovat pro produkci?

Odpověď: Zpracování chyb a selhané úlohy, okamžité stažení výstupů a sledování nákladů (rozlišení, délka, iterace) — video je nejdražší modalita: musí být rozpočtováno.

Časový prompt, vizuální reference, zvládnutá asynchronita: generativní video se stává pipeline — ne loterií.