Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Obvladovanje napak in uvajanje v proizvodnjo

Lekcija 12 od 12 Posodobljeno 3. november 2026 Srednje napredni
Na tej strani
  1. Priprava aplikacije za proizvodnjo
  2. Dve družini napak, dva trenutka
  3. Pametni ponovni poskusi
  4. Čakalna vrsta za ohranjanje tempa
  5. Preveri svoj ključ, preden se nanj zaneseš
  6. Vidi, kaj se dogaja v proizvodnji
  7. Ključne ugotovitve
  8. Preveri svoje znanje

Posodobljeno 2. novembra 2026 na podlagi dokumentacije za videoposnetke xAI in kode xai-sdk 1.21.0: client.video.generate (ne client.videos), rezultat v url, napake poroča VideoGenerationError s kodo (invalid_argument, service_unavailable…), omejitev hitrosti prejmeš kot grpc.RpcError s kodo RESOURCE_EXHAUSTED — razred RateLimitError in status expired ne obstajata. Dopolnilo 3. novembra 2026: omejitev hitrosti šteje zahteve na sekundo (10 pri osnovni ravni), ne “60 RPM”, dejanski strošek na generiranje pa se bere iz usage.cost_in_usd_ticks. Viri: Generiranje videoposnetkov · Omejitve hitrosti.

Priprava aplikacije za proizvodnjo

Skripta, ki na tvojem računalniku ustvari videoposnetek, in storitev, ki jih dnevno proizvede na stotine za prave uporabnike, nimata skoraj nič skupnega. Slednja mora obvladovati zavrnitve moderiranja, presežene kvote, incidente na strežniku in potekle URL-je, ne da bi kdaj tiho izgubila zaračunano generiranje. Ta lekcija pokriva mehanizme, ki delajo razliko: razvrščanje napak, strategija ponovnih poskusov, arhitektura čakalne vrste in opazljivost.

Dve družini napak, dva trenutka

Prva družina se pojavi takoj, v trenutku klica POST. To so stroge napake zahteve in koda HTTP zadošča za odločitev, kaj storiti.

Koda HTTPVzrokRešitev
400Neveljavni parametri (npr. neznan glas v reference_audios)Popravi zahtevo
401Neveljaven ali potekel ključ APIPreveri avtentikacijo
429Presežena omejitev hitrosti (zahteve na sekundo, odvisno od ravni)Uvedi zamik (backoff)
500Napaka strežnikaPonovni poskus z eksponentnim zamikom

Druga družina se pokaže veliko kasneje, med preverjanjem stanja (polling), potem ko je bila zahteva sprejeta in se je generiranje začelo.

StatusVerjeten vzrokUkrep
failed + invalid_argument ali permission_deniedZahteva ali vsebina zavrnjenaSpremeni poziv ali vir
failed + service_unavailable ali internal_errorStoritev preobremenjena, incidentPonovni poskus kasneje

Ta razlika ni akademsko vprašanje: koda 400 se mora takoj vrniti klicatelju, ker je napaka v kodi, medtem ko se status failed pojavi po več minutah čakanja in ga je treba obravnavati v kontekstu opravila, ne v HTTP-zahtevi, ki ga je sprožila.

Pametni ponovni poskusi

Skupna osnova je eksponentni zamik z nekaj naključnega nihanja (jitter). Podvojitev zamika da prehodnemu incidentu čas, da se razreši, nihanje pa prepreči, da bi vsi tvoji procesi poskusili znova ob istem trenutku po skoku obremenitve — pojav, ki mikroprekinitev spremeni v dolgotrajno okvaro.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Izvede funkcijo s ponovnimi poskusi in eksponentnim zamikom."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Eksponentni zamik z nihanjem
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Poskus {attempt + 1} ni uspel: {e}. Ponovni poskus čez {delay:.1f}s")
            await asyncio.sleep(delay)

Ta splošna shema sama po sebi ne zadošča, saj si ne zaslužijo vse napake enake potrpežljivosti. Presežek kvote se razreši s čakanjem polne minute; zavrnitev moderiranja se nikoli ne bo razrešila in ponovni poskus pomeni večkratno plačilo za isti neuspeh. Naslednja funkcija razlikuje med primeri.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Kode napak, ki jih ponovni poskus ne bo popravil
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Generiranje videoposnetka s ciljnimi ponovnimi poskusi (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  # zahteva ali vsebina zavrnjena: popravi pred ponovnim zagonom
            await asyncio.sleep(5 * (attempt + 1))  # storitev preobremenjena, incident
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # omejitev hitrosti: zamik
        except TimeoutError:
            if is_last:
                raise
            # Dovoli več časa za naslednji poskus
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Čakalna vrsta za ohranjanje tempa

Takoj ko tvoja storitev prejema zahteve več uporabnikov, moraš ločiti sprejemanje zahtev od izvajanja in predvsem omejiti sočasnost, da ostaneš pod omejitvijo hitrosti svoje ravni. Čakalna vrsta v povezavi s semaforjem zadovolji obe potrebi: opravila se poljubno kopičijo, vendar jih hkrati teče največ 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):
        """Doda generiranje v čakalno vrsto."""
        self.queue.append((job_id, params))

    async def process(self):
        """Obdela vsa čakajoča generiranja."""
        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):
        """Izvede generiranje z nadzorom sočasnosti."""
        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)
                }

Upoštevaj, da vsako opravilo hrani svoj izid v results, uspeh ali neuspeh: generiranje, ki izgine brez sledu, je incident, ki ga nihče ne more diagnosticirati.

Drugi refleks arhitekture se nanaša na shranjevanje. Ker so URL-ji videoposnetkov začasni, mora biti prenos samodejen in takojšen, z imenovanjem z časovnim žigom, ki zagotavlja, da med dvema sočasnima generiranjema ne pride do trka.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Prenese in shrani ustvarjeni videoposnetek."""
    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

Preveri svoj ključ, preden se nanj zaneseš

Končna točka GET /v1/api-key te obvesti o stanju tvojega ključa. Klic ob zagonu storitve prepreči, da bi odkril blokiran ključ po dvajsetih neuspelih zahtevah, medtem ko tvoji uporabniki čakajo.

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("Ključ API ali ekipa blokirana, ali ključ onemogočen")

Vidi, kaj se dogaja v proizvodnji

Pet kazalnikov zadošča za vodenje storitve generiranja videoposnetkov. Stopnja uspešnosti, torej delež generiranj, ki se končajo z done, meri splošno zdravje. Povprečni čas generiranja, izmerjen med oddajo in statusom done, služi umerjanju časovnih omejitev in obveščanju uporabnikov. Stopnja napak, razčlenjena po vrsti — failed po kodi napake, časovna omejitev, omejitev hitrosti — ti pove, kam usmeriti trud: porast časovnih omejitev brez porasta failed na primer signalizira generiranja, ki so počasnejša od tvoje čakalne roke, ne pa napak. Kumulativni strošek, dobljen s seštevanjem polja usage.cost_in_usd_ticks iz vsakega rezultata (en dolar je enak 10 milijardam tikov) ali alternativno z množenjem ustvarjenih trajanj s ceno modela na sekundo, je treba spremljati dnevno. Nazadnje, uporaba kvote, v zahtevah na sekundo glede na omejitev tvoje ravni (10 pri osnovni ravni za video modele), predvidi zasičenost, preden se ta prevede v kode 429.

Ti metrik se naravno gradijo iz strukturiranega dnevnika, kjer vsako generiranje pusti vrstico, uporabno za tvoje analizno orodje.

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

Preden svojo storitev odpreš javnosti, pregledaj vse od začetka. Eksponentni zamik z nihanjem mora biti vzpostavljen, sočasnost pa omejena s semaforjem, da ostaneš pod omejitvijo hitrosti. Prenosi videoposnetkov se morajo sprožiti samodejno, takoj ko so pripravljeni, brez odvisnosti od človeškega dejanja. Vsako generiranje mora zapustiti vrstico dnevnika, ki nosi svoj request_id, status in strošek, sicer bosta stopnja napak in povprečni čas generiranja ostala nepreverljiva. Stanje ključa API preveri ob zagonu in ne ob prvem neuspehu. In določi proračun z opozorili ob presežku: pri 0,05 $ na sekundo neomejena zanka ponovnih poskusov porabi sredstva hitreje, kot misliš.

Cene preverjene 3. novembra 2026 — cene se redno spreminjajo: pred vsakim izračunom proračuna preveri trenutni cenik na uradni strani modelov in cen xAI.

Ključne ugotovitve

  • Napake se delijo na sinhrona (zahteva) in asinhrona (generiranje)
  • Ne vse napake si zaslužijo ponovni poskus: moderiranje je dokončno
  • Uporabi semafor za omejitev sočasnih generiranj
  • Začasni URL-ji zahtevajo takojšen in sistematičen prenos
  • Spremljaj metrike stroškov, uspešnosti in časa generiranja za vodenje svoje storitve

Preveri svoje znanje

Generativni video v proizvodnji: potrdi celoten potek dela.

1. Kaj so posebnosti poziva za video?

Odgovor: Opiši dejanje in gibanje, ne le prizora: subjekt, premik, vzdušje, kadrovanje — časovna razsežnost je tisto, kar loči poziv za video od poziva za sliko.

2. Kaj omogoča pretvorba slike v video?

Odgovor: Animira obstoječo sliko ali vnese dane ljudi in izdelke v novo sceno z uporabo referenčnih slik — in pri grok-imagine-video-1.5 pripne prvo, zadnjo ali ključne slike: tvoja vizualna identiteta postane izhodišče, ne naključje.

3. Urejanje in razširjanje: kakšne uporabe?

Odgovor: /videos/edits spremeni ustvarjeni videoposnetek, /videos/extensions ga podaljša — in oboje se združi za gradnjo dolgih zaporedij z iteracijami.

4. Zakaj je potek dela asinhron?

Odgovor: Generiranje videa traja: oddaš opravilo, preverjaš njegovo stanje, nato pa pridobiš rezultat — SDK xAI avtomatizira to preverjanje.

5. Kaj načrtovati za proizvodnjo?

Odgovor: Obvladovanje napak in neuspelih opravil, takojšen prenos izhodov in sledenje stroškom (ločljivost, trajanje, iteracije) — video je najdražji način: proračunati ga je treba.

Časovni poziv, vizualna referenca, obvladan asinhroni potek: generativni video postane cevovod — ne loterija.