Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Veahandlus ja tootmisse viimine

Õppetund 12 / 12 Värskendatud 3. november 2026 Kesktase
Sellel lehel
  1. Valmista oma rakendus tootmisse viimiseks ette
  2. Kaks veaperet, kaks erinevat momenti
  3. Proovi uuesti targalt
  4. Järjekord tempoga sammu pidamiseks
  5. Kontrolli oma võtit enne sellele tuginemist
  6. Näe, mis tootmises toimub
  7. Peamised punktid
  8. Testi oma teadmisi

Uuendatud 2. novembril 2026, tuginedes xAI video dokumentatsioonile ja xai-sdk 1.21.0 koodile: kasuta client.video.generate (mitte client.videos), tulemus on väljal url, tõrked teavitatakse VideoGenerationError kaudu koos koodiga (invalid_argument, service_unavailable jne), kiirusepiirang saadetakse kui grpc.RpcError koodiga RESOURCE_EXHAUSTED — klassi RateLimitError ja staatust expired ei eksisteeri. Täiendus 3. novembril 2026: kiirusepiirang loeb päringuid sekundis (sisetasemel 10), mitte “60 RPM”, ja tegelik kulu generatsiooni kohta loetakse väljalt usage.cost_in_usd_ticks. Allikad: Video Generation · Rate limits.

Valmista oma rakendus tootmisse viimiseks ette

Skript, mis genereerib video sinu arvutis, ja teenus, mis toodab sadu videoid päriskasutajatele, ei ole peaaegu millegi poolest sarnased. Viimane peab suutma käsitleda moderatsioonikeeldumisi, kvoodi ületamisi, serveriintsidente ja aeguvaid URL-e, kaotamata seejuures kunagi vaikselt maha ühtki arvestatud generatsiooni. See tund käsitleb mehhanisme, mis teevad erinevuse: vealiikide klassifitseerimine, uuesti proovimise strateegia, järjekorra arhitektuur ja jälgitavus.

Kaks veaperet, kaks erinevat momenti

Esimene perekond ilmneb koheselt POST-päringu tegemise hetkel. Need on ranged päringuvead ja HTTP-koodist piisab otsustamiseks, mida ette võtta.

HTTP-koodPõhjusLahendus
400Vigased parameetrid (näiteks tundmatu hääl reference_audios väljal)Paranda päringut
401Vigane või aegunud API-võtiKontrolli autentimist
429Kiirusepiirang ületatud (päringuid sekundis, sõltuvalt tasemest)Rakenda taganemist (backoff)
500ServerivigaProovi uuesti eksponentsiaalse taganemisega

Teine perekond avaldub palju hiljem, oleku pärimise (polling) käigus, pärast seda, kui päring on vastu võetud ja genereerimine on alanud.

StaatusTõenäoline põhjusTegevus
failed + invalid_argument või permission_deniedPäring või sisu lükati tagasiMuuda vihjet või allikat
failed + service_unavailable või internal_errorTeenus ülekoormatud, intsidentProovi hiljem uuesti

See eristus ei ole akadeemiline: 400 peab saatma kohese vastuse väljakutsujale, kuna viga on koodis, samas kui staatus failed ilmneb pärast mitmeminutilist ootamist ja seda tuleb käsitleda tööülesande kontekstis, mitte seda käivitanud HTTP-päringus.

Proovi uuesti targalt

Ühine alus on eksponentsiaalne taganemine (exponential backoff) koos väikese juhusliku kõrvalekaldega (jitter). Viivituse kahekordistamine annab ajutisele intsidendile aega laheneda, ning jitter hoiab ära olukorra, kus kõik sinu protsessid proovivad pärast tõusu samaaegselt uuesti – nähtus, mis muudab mikrokatkestuse püsivaks rikkeks.

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)

See üldine skeem ei ole siiski piisav, sest mitte kõik vead ei väärivat sama palju kannatlikkust. Kvoodi ületamine laheneb minuti ootamisega; moderatsioonikeeldumine ei lahene kunagi ja selle kordamine tähendaks sama vea eest mitu korda maksmist. Järgnev funktsioon eristab neid juhtumeid.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Tõrkekoodid, mida uuesti proovimine ei paranda
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)

Järjekord tempoga sammu pidamiseks

Niipea kui sinu teenus hakkab vastu võtma päringuid mitmelt kasutajalt, pead eraldama päringute vastuvõtu nende täitmisest ja eelkõige piirama samaaegsust, et jääda oma taseme kiirusepiirangu alla. Järjekord koos semaforiga rahuldab mõlemat vajadust: tööd kuhjuvad vabalt, kuid korraga täidetakse maksimaalselt kümmet.

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

Pane tähele, et iga töö hoiab oma tulemust massiivis results, olgu see siis edu või ebaõnnestumine: genereerimine, mis kaob jäljetult, on intsident, mida keegi diagnoosida ei saa.

Teine arhitektuuriline refleks puudutab salvestamist. Kuna video URL-id on ajutised, peab allalaadimine olema automaatne ja kohene, kasutades ajatemplitega failinimesid, mis garanteerivad, et kahe samaaegse generatsiooni vahel ei teki konflikte.

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

Kontrolli oma võtit enne sellele tuginemist

Lõpp-punkt GET /v1/api-key annab teavet sinu võtme oleku kohta. Selle kutsumine teenuse käivitamisel hoiab ära olukorra, kus avastad blokeeritud võtme alles pärast kahtkümmet ebaõnnestunud päringut, samal ajal kui sinu kasutajad ootavad.

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

Näe, mis tootmises toimub

Video genereerimise teenuse juhtimiseks piisab viiest näitajast. Edu määr, ehk done staatusega lõppenud generatsioonide osakaal, mõõdab üldist tervist. Keskmine genereerimisaeg, mõõdetuna esitamisest kuni done staatuseni, aitab kalibreerida sinu aegumisi ja informeerida kasutajaid. Veamäär liigitatuna tüüpide kaupa – failed veakoodi, aegumise või kiirusepiirangu järgi – ütleb, kuhu jõupingutusi suunata: aegumiste tõus ilma failed juhtumite kasvuta annab märku, et generatsioonid on aeglasemad kui sinu ooteaeg, mitte et need oleksid ebaõnnestunud. Kumuleeruv kulu, saadud liites iga tulemuse välja usage.cost_in_usd_ticks (üks dollar võrdub 10 miljardi tikiga) või alternatiivselt korrutades genereeritud kestused mudeli hinnaga sekundi kohta, tuleb jälgida iga päev. Lõpuks annab kvoodi kasutus (päringuid sekundis võrreldes sinu taseme piiranguga, mis on videomudelite puhul sisetasemel 10) aimu küllastumisest enne, kui see väljendub 429-vigadena.

Need mõõdikud tekivad loomulikult struktureeritud logist, kus iga generatsioon jätab maha rea, mida sinu analüüsivahend saab kasutada.

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

Enne teenuse avalikkusele avamist vaata kogu protsess algusest lõpuni üle. Eksponentsiaalne taganemine koos jitteriga peab olema paigas ja samaaegsus peab olema semaforiga piiratud, et jääda kiirusepiirangu alla. Videote allalaadimine peab käivituma automaatselt niipea, kui need on valmis, sõltumata inimese tegevusest. Iga generatsioon peab jätma logirea, mis kannab endas request_id, staatust ja kulu, vastasel juhul jäävad veamäär ja keskmine genereerimisaeg kontrollimatuks. Kontrolli API-võtme olekut käivitamisel, mitte esimese vea korral. Ja kehtesta eelarve koos ületamise hoiatustega: hinnaga 0,05 dollarit sekundi kohta kulutab piiramatu uuesti proovimise tsükkel raha kiiremini, kui arvad.

Hinnad kontrollitud 3. novembril 2026 – hinnad muutuvad regulaarselt: enne eelarve arvutamist kontrolli kehtivat hinnakirja xAI ametlikul mudelite ja hindade lehel.

Peamised punktid

  • Vead jagunevad sünkroonseteks (päring) ja asünkroonseteks (generatsioon)
  • Mitte kõik vead ei väärivat uuesti proovimist: moderatsioon on lõplik
  • Kasuta semafori samaaegsete generatsioonide piiramiseks
  • Ajutised URL-id nõuavad koheseid ja süstemaatilisi allalaadimisi
  • Jälgi kulu, edu ja genereerimisaja mõõdikuid oma teenuse juhtimiseks

Testi oma teadmisi

Generatiivne video tootmises: valideeri kogu töövoog.

1. Millised on video vihje eripärad?

Vastus: Kirjelda tegevust ja liikumist, mitte ainult stseeni: subjekt, liikumine, atmosfäär, kaader – ajaline mõõde on see, mis eristab video vihjet pildi vihjest.

2. Mida võimaldab pilt-videoks (image-to-video)?

Vastus: Animeeri olemasolevat pilti või too antud inimesed ja tooted uude stseeni, kasutades referentspilte – ja mudelil grok-imagine-video-1.5 saad fikseerida esimese, viimase või võtmepildid: sinu visuaalne identiteet muutub lähtepunktiks, mitte juhuslikuks tulemuseks.

3. Redigeerimine ja pikendamine: millised kasutusviisid?

Vastus: /videos/edits muudab genereeritud videot, /videos/extensions pikendab seda – ja mõlemat saab kombineerida pikkade jadade loomiseks iteratsioonide kaudu.

4. Miks on töövoog asünkroonne?

Vastus: Video genereerimine võtab aega: esitad tööülesande, pärid selle staatust ja seejärel toimid tulemuse – xAI SDK automatiseerib selle oleku pärimise.

5. Mida planeerida tootmisse viimisel?

Vastus: Veahandlust ja ebaõnnestunud töid, väljundite koheseid allalaadimisi ja kulude jälgimist (lahutusvõime, kestus, iteratsioonid) – video on kõige kallim modaalsus: seda tuleb eelarvestada.

Ajaline vihje, visuaalne referents, valdatud asünkroonsus: generatiivsest videost saab torustik – mitte loterii.