Kezelési hibák és éles környezetbe történő telepítés
Ezen az oldalon
Frissítve: 2026. november 2. az xAI videódokumentációja és az
xai-sdk1.21.0 verziójú kódja alapján:client.video.generate(nemclient.videos), az eredmény azurlmezőben található, a hibákat aVideoGenerationErrorjelzi egy kóddal (invalid_argument,service_unavailable…), a sebességkorlátozást pedig agrpc.RpcErrorjelziRESOURCE_EXHAUSTEDkóddal — aRateLimitErrorosztály és azexpiredá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 ausage.cost_in_usd_ticksmező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ód | Ok | Megoldá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-kulcs | Ellenőrizd a hitelesítést |
| 429 | Sebességkorlát túllépése (másodpercenkénti kérések, szinttől függően) | Implementálj visszalépést (backoff) |
| 500 | Szerverhiba | Pró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.
| Állapot | Valószínű ok | Teendő |
|---|---|---|
failed + invalid_argument vagy permission_denied | A kérést vagy tartalmat elutasították | Módosítsd a promptot vagy a forrást |
failed + service_unavailable vagy internal_error | A szolgáltatás túlterhelt, incidens | Pró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á.