Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Kezelési hibák és éles környezetbe történő telepítés

12. lecke 12 közül Frissítve 2026. november 3. Középhaladó
Ezen az oldalon
  1. Alkalmazásod felkészítése az éles környezetre
  2. Két hibacsalád, két időpont
  3. Intelligens újrapróbálkozás
  4. Sor a tempó tartásához
  5. Ellenőrizd a kulcsodat, mielőtt támaszkodnál rá
  6. Lásd, mi történik az éles környezetben
  7. Főbb megállapítások
  8. Teszteld a tudásod

Frissítve: 2026. november 2. az xAI videódokumentációja és az xai-sdk 1.21.0 verziójú kódja alapján: client.video.generate (nem client.videos), az eredmény az url mezőben található, a hibákat a VideoGenerationError jelzi egy kóddal (invalid_argument, service_unavailable…), a sebességkorlátozást pedig a grpc.RpcError jelzi RESOURCE_EXHAUSTED kóddal — a RateLimitError osztály és az expired állapot nem létezik. Kiegészítés 2026. november 3.: a sebességkorlátozás másodpercenkénti kérésszámot jelent (belépő szinten 10), nem „60 RPM“-et, és a generálás tényleges költsége a usage.cost_in_usd_ticks mezőből olvasható ki. Források: Videogenerálás · Sebességkorlátok.

Alkalmazásod felkészítése az éles környezetre

Egy script, amely videót generál a gépeden, és egy szolgáltatás, amely valódi felhasználók számára naponta százakat állít elő, szinte semmiben sem hasonlít egymásra. Ez utóbbinak kezelnie kell a moderációs elutasításokat, a kvótatúllépéseket, a szerverincidenseket és a lejáró URL-címeket anélkül, hogy valaha is csendben elveszne egy számlázott generálás. Ez a lecke azokat a mechanizmusokat tárgyalja, amelyek számítanak: hibák osztályozása, újrapróbálkozási stratégia, sorarchitektúra és megfigyelhetőség.

Két hibacsalád, két időpont

Az első családbeli hiba azonnal megjelenik, a POST hívás pillanatában. Ezek szigorú kéréshibák, és a HTTP-kód elég ahhoz, hogy eldöntsd, mit tegyél.

HTTP-kódOkMegoldás
400Érvénytelen paraméterek (például ismeretlen hang a reference_audios listában)Javítsd a kérést
401Érvénytelen vagy lejárt API-kulcsEllenőrizd a hitelesítést
429Sebességkorlát túllépése (másodpercenkénti kérések, szinttől függően)Implementálj visszalépést (backoff)
500SzerverhibaPróbáld újra exponenciális visszalépéssel

A második családbeli hiba sokkal később jelentkezik, a lekérdezés (polling) során, miután a kérést elfogadták és a generálás elindult.

ÁllapotValószínű okTeendő
failed + invalid_argument vagy permission_deniedA kérést vagy tartalmat elutasítottákMódosítsd a promptot vagy a forrást
failed + service_unavailable vagy internal_errorA szolgáltatás túlterhelt, incidensPróbáld újra később

Ez a megkülönböztetés nem elméleti: a 400-as hibának azonnal vissza kell térnie a hívóhoz, mert a kód a hibás, míg a failed állapot több perc várakozás után következik be, és a feladat kontextusában kell kezelni, nem abban a HTTP-kérésben, amely kiváltotta.

Intelligens újrapróbálkozás

Az közös alap az exponenciális visszalépés (exponential backoff) némi zajjal (jitter). A késleltetés megduplázása időt ad egy átmeneti incidens megoldására, a zaj pedig megakadályozza, hogy minden folyamatod egyszerre próbálkozzon újra egy csúcs után — ez a jelenség egy mikro-kimaradást tartós hibává változtatna.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Végrehajt egy függvényt újrapróbálkozással és exponenciális visszalépéssel."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Exponenciális visszalépés zajjal
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"{attempt + 1}. próbálkozás sikertelen: {e}. Újrapróbálkozás {delay:.1f}s múlva")
            await asyncio.sleep(delay)

Ez az általános séma azonban nem elég, mert nem minden hiba érdemel ugyanannyi türelmet. Egy kvótatúllépés megoldódik, ha vársz egy teljes percet; egy moderációs elutasítás sosem oldódik meg, és az újrapróbálkozás annyit jelent, hogy többször fizetsz ugyanazért a hibáért. A következő függvény megkülönbözteti az eseteket.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Hibakódok, amelyeket az újrapróbálkozás nem javít meg
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Videogenerálás célzott újrapróbálkozással (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  # kérést vagy tartalmat elutasították: javítsd újraindítás előtt
            await asyncio.sleep(5 * (attempt + 1))  # szolgáltatás túlterhelt, incidens
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # sebességkorlát: visszalépés
        except TimeoutError:
            if is_last:
                raise
            # Több idő engedélyezése a következő próbálkozáshoz
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Sor a tempó tartásához

Amint a szolgáltatásod több felhasználótól fogad kéréseket, szét kell választanod a kérések fogadását a végrehajtástól, és mindenekelőtt korlátoznod kell a párhuzamosságot, hogy a szinted sebességkorlátján belül maradj. Egy sor, amelyet egy szemafórral párosítasz, mindkét igényt kielégíti: a feladatok szabadon halmozódhatnak, de egyszerre maximum tíz hajtódik végre.

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):
        """Hozzáad egy generálást a sorhoz."""
        self.queue.append((job_id, params))

    async def process(self):
        """Feldolgozza az összes függőben lévő generálást."""
        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):
        """Végrehajt egy generálást párhuzamosság-vezérléssel."""
        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)
                }

Figyeld meg, hogy minden feladat megtartja az eredményét a results gyűjteményben, legyen az siker vagy hiba: egy nyom nélkül eltűnt generálás olyan incidens, amelyet senki sem tud diagnosztizálni.

A második architektúrális reflex a tárolásra vonatkozik. Mivel a videó URL-címek ideiglenesek, a letöltésnek automatikusnak és azonnalinak kell lennie, időbélyegzővel ellátott elnevezéssel, amely garantálja, hogy két egyidejű generálás között ne legyen ütközés.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Letölti és elmenti a generált videót."""
    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

Ellenőrizd a kulcsodat, mielőtt támaszkodnál rá

A GET /v1/api-key végpont tájékoztat a kulcsod állapotáról. Ha ezt a szolgáltatás indításakor hívod meg, elkerülheted, hogy húsz sikertelen kérés után fedezd fel a blokkolt kulcsot, miközben a felhasználóid várnak.

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-kulcs vagy csapat blokkolva, illetve kulcs letiltva")

Lásd, mi történik az éles környezetben

Öt mutató elég egy videogeneráló szolgáltatás irányításához. A sikerarány, vagyis a done állapottal végződő generálások aránya, az általános egészségi állapotot méri. Az átlagos generálási idő, amelyet a beküldés és a done állapot között mérünk, segít kalibrálni a time-outokat és tájékoztatni a felhasználókat. A hibaarány típusok szerint lebontva — failed hibakód szerint, time-out, sebességkorlát — megmutatja, hol kell összpontosítanod az erőfeszítéseket: a time-outok növekedése a failed hibák növekedése nélkül például arra utal, hogy a generálások lassabbak a várakozási határidődnél, nem pedig hibásak. A halmozott költség, amelyet az egyes eredmények usage.cost_in_usd_ticks mezőjének összegzésével kapsz meg (egy dollár 10 milliárd ticknek felel meg), vagy alternatív megoldásként a generált időtartamok és a modell másodpercenkénti árának szorzataként, napi szinten követendő. Végül a kvótafelhasználás, másodpercenkénti kérések száma a szinted korlátjához viszonyítva (videómodelleknél belépő szinten 10), előre jelzi a telítettséget, mielőtt az 429-es hibákban nyilvánulna meg.

Ezek a mutatók természetesen épülnek fel egy strukturált naplóból, ahol minden generálás egy, az elemzőeszközöd által használható sort hagy maga után.

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

Mielőtt szolgáltatásodat a nyilvánosság elé tárnád, nézd át az egészet az elejétől. Az exponenciális visszalépésnek és a zajnak helyén kell lennie, a párhuzamosságot pedig szemafórral kell korlátozni, hogy a sebességkorláton belül maradj. A videók letöltésének automatikusan el kell indulnia, amint elkészültek, emberi beavatkozás nélkül. Minden generálásnak hagynia kell egy naplósorot, amely tartalmazza a request_id-t, az állapotot és a költséget, különben a hibaarány és az átlagos generálási idő ellenőrizhetetlen marad. Indításkor ellenőrizd az API-kulcs állapotát, ne az első hiba esetén. És állíts be költségkeretet túllépési riasztásokkal: másodpercenként 0,05 dollárnál egy korlátlan újrapróbálkozási ciklus gyorsabban emészti fel a keretet, mint gondolnád.

Árazás ellenőrizve: 2026. november 3. — az árak rendszeresen változnak: bármilyen költségvetés-számítás előtt ellenőrizd az aktuális díjszabást a hivatalos xAI modellek és árazás oldalon.

Főbb megállapítások

  • A hibák szinkron (kérés) és aszinkron (generálás) típusokra oszlanak
  • Nem minden hiba érdemel újrapróbálkozást: a moderáció végleges
  • Használj szemafórt a párhuzamos generálások korlátozására
  • Az ideiglenes URL-címek azonnali és rendszeres letöltést igényelnek
  • Kövesd nyomon a költség-, siker- és generálási idő mutatókat szolgáltatásod irányításához

Teszteld a tudásod

Generatív videó éles környezetben: validáld a teljes munkafolyamatot.

1. Mik a videopromptok sajátosságai?

Válasz: Írd le a cselekvést és a mozgást, nem csak a jelenetet: téma, elmozdulás, hangulat, képkivágás — az időbeli dimenzió az, ami megkülönbözteti a videopromptot a képprompttól.

2. Mit tesz lehetővé a kép-videó (image-to-video) funkció?

Válasz: Egy meglévő kép animálását, vagy adott személyek és termékek új jelenetbe helyezését referenciaképek segítségével — és a grok-imagine-video-1.5 modellen rögzítheted az első, az utolsó vagy a kulcsképeket: a vizuális identitásod kiindulóponttá válik, nem véletlen egybeeséssé.

3. Szerkesztés és kiterjesztés: milyen felhasználási területek?

Válasz: A /videos/edits módosít egy generált videót, a /videos/extensions meghosszabbítja azt — és mindkettő kombinálható hosszú szekvenciák iteratív felépítésére.

4. Miért aszinkron a munkafolyamat?

Válasz: A videogenerálás időigényes: beküldesz egy feladatot, lekérdezed az állapotát, majd lekérjed az eredményt — az xAI SDK automatizálja ezt a lekérdezést.

5. Mit kell tervezni az éles környezethez?

Válasz: Hibakezelést és sikertelen feladatokat, a kimenetek azonnali letöltését, valamint a költségkövetést (felbontás, időtartam, iterációk) — a videó a legköltségesebb mód: ezt költségvetésbe kell foglalni.

Időbeli prompt, vizuális referencia, maîtrisé aszinkronitás: a generatív videó csővezetékké válik — nem lottóhúzássá.