Veahandlus ja tootmisse viimine
Sellel lehel
Uuendatud 2. novembril 2026, tuginedes xAI video dokumentatsioonile ja
xai-sdk1.21.0 koodile: kasutaclient.video.generate(mitteclient.videos), tulemus on väljalurl, tõrked teavitatakseVideoGenerationErrorkaudu koos koodiga (invalid_argument,service_unavailablejne), kiirusepiirang saadetakse kuigrpc.RpcErrorkoodigaRESOURCE_EXHAUSTED— klassiRateLimitErrorja staatustexpiredei eksisteeri. Täiendus 3. novembril 2026: kiirusepiirang loeb päringuid sekundis (sisetasemel 10), mitte “60 RPM”, ja tegelik kulu generatsiooni kohta loetakse väljaltusage.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-kood | Põhjus | Lahendus |
|---|---|---|
| 400 | Vigased parameetrid (näiteks tundmatu hääl reference_audios väljal) | Paranda päringut |
| 401 | Vigane või aegunud API-võti | Kontrolli autentimist |
| 429 | Kiirusepiirang ületatud (päringuid sekundis, sõltuvalt tasemest) | Rakenda taganemist (backoff) |
| 500 | Serveriviga | Proovi 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.
| Staatus | Tõenäoline põhjus | Tegevus |
|---|---|---|
failed + invalid_argument või permission_denied | Päring või sisu lükati tagasi | Muuda vihjet või allikat |
failed + service_unavailable või internal_error | Teenus ülekoormatud, intsident | Proovi 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.