Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Virheenkäsittely ja tuotantoon julkaisu

Oppitunti 12 / 12 Päivitetty 3. marraskuuta 2026 Keskitasoinen
Tällä sivulla
  1. Valmistele sovelluksesi tuotantokäyttöä varten
  2. Kaksi virheryhmää, kaksi ajankohtaa
  3. Yritä uudelleen älykkäästi
  4. Jono pitää tahdin yllä
  5. Tarkista avaimesi ennen kuin luotat siihen
  6. Näe mitä tuotannossa tapahtuu
  7. Keskeiset asiat
  8. Testaa tietämyksesi

Päivitetty 2. marraskuuta 2026 xAI:n videodokumentaation ja xai-sdk 1.21.0 -koodin perusteella: client.video.generate (ei client.videos), tulos kentässä url, epäonnistumiset ilmoitetaan VideoGenerationError-virheellä, jossa on koodi (invalid_argument, service_unavailable…), nopeusrajoitus saadaan grpc.RpcError-virheenä, jonka koodi on RESOURCE_EXHAUSTED — luokkaa RateLimitError ja tilaa expired ei ole olemassa. Täydennys 3. marraskuuta 2026: nopeusrajoitus laskee pyyntöjä sekunnissa (10 aloitustasolla), ei “60 RPM”, ja todellinen kustannus generaatiota kohden luetaan kentästä usage.cost_in_usd_ticks. Lähteet: Videogenerointi · Nopeusrajoitukset.

Valmistele sovelluksesi tuotantokäyttöä varten

Skriptillä, joka luo videon koneellasi, ja palvelulla, joka tuottaa satoja videoita päivässä oikeille käyttäjille, ei ole juuri mitään yhteistä. Jälkimmäisen on käsiteltävä moderointikieltäytyminen, kiintiöiden ylitykset, palvelinkatkokset ja vanhentuvat URL-osoitteet ilman, että laskutettu generaatio koskaan katoaa hiljaa. Tämä oppitunti kattaa mekanismit, jotka tekevät eron: virheiden luokittelu, uudelleenyritysstrategia, jonotusarkkitehtuuri ja havainnoitavuus.

Kaksi virheryhmää, kaksi ajankohtaa

Ensimmäinen ryhmä ilmestyy välittömästi POST-kutsun hetkellä. Nämä ovat tiukkoja pyyntövirheitä, ja HTTP-koodi riittää päättämään, mitä tehdä.

HTTP-koodiSyyRatkaisu
400Virheelliset parametrit (esim. tuntematon ääni kohdassa reference_audios)Korjaa pyyntö
401Virheellinen tai vanhentunut API-avainTarkista todennus
429Nopeusrajoitus ylitetty (pyynnöt sekunnissa tason mukaan)Toteuta backoff
500PalvelinvirheYritä uudelleen eksponentiaalisella viiveellä

Toinen ryhmä ilmenee paljon myöhemmin, pollauksen aikana, kun pyyntö on hyväksytty ja generointi on alkanut.

TilaTodennäköinen syyToimenpide
failed + invalid_argument tai permission_deniedPyyntö tai sisältö hylättyMuuta kehotetta tai lähdettä
failed + service_unavailable tai internal_errorPalvelu ylikuormitettu, häiriöYritä myöhemmin uudelleen

Tämä ero ei ole akateeminen: 400-virheen on palattava välittömästi kutsujalle, koska vika on koodissa, kun taas failed-tila ilmenee useiden minuuttien odotuksen jälkeen ja se on käsiteltävä työtehtävän kontekstissa, ei sen HTTP-pyynnön yhteydessä, joka sen laukaisi.

Yritä uudelleen älykkäästi

Yleinen perusta on eksponentiaalinen backoff, jossa on hieman satunnaisvaihtelua (jitter). Viiveen kaksinkertaistaminen antaa ohimenevälle häiriölle aikaa ratketa, ja satunnaisvaihtelu estää kaikkia prosessejasi yrittämästä uudelleen samaan hetkeen piikin jälkeen — ilmiö, joka muuttaa mikrokatkon pysyväksi vikatilanteeksi.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Suorittaa funktion uudelleenyrityksellä ja eksponentiaalisella backoffilla."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Eksponentiaalinen backoff jitterillä
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Yritys {attempt + 1} epäonnistui: {e}. Yritetään uudelleen {delay:.1f}s kuluttua")
            await asyncio.sleep(delay)

Tämä yleinen malli ei kuitenkaan riitä, sillä kaikki virheet eivät ansaitse samaa kärsivällisyyttä. Kiintiön ylitys ratkeaa odottamalla minuutti; moderointikieltäytyminen ei koskaan ratkea, ja uudelleenyritys tarkoittaa vain samaan epäonnistumiseen maksamista useita kertoja. Seuraava funktio erottaa nämä tapaukset.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Virhekoodit, joita uudelleenyritys ei korjaa
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Videogenerointi kohdennetulla uudelleenyrityksellä (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  # pyyntö tai sisältö hylätty: korjaa ennen uudelleenkäynnistystä
            await asyncio.sleep(5 * (attempt + 1))  # palvelu ylikuormitettu, häiriö
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # nopeusrajoitus: backoff
        except TimeoutError:
            if is_last:
                raise
            # Anna enemmän aikaa seuraavalle yritykselle
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Jono pitää tahdin yllä

Heti kun palvelusi vastaanottaa pyyntöjä useilta käyttäjiltä, sinun on irrotettava pyyntöjen vastaanotto niiden suorittamisesta ja ennen kaikkea rajoitettava samanaikaisuutta pysyäksesi tasonsa nopeusrajoituksen puitteissa. Jono yhdistettynä semaforiin täyttää molemmat tarpeet: työt pinoutuvat vapaasti, mutta vain enintään kymmenen suoritetaan kerrallaan.

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):
        """Lisää generaation jonoon."""
        self.queue.append((job_id, params))

    async def process(self):
        """Käsittelee kaikki odottavat generaatiot."""
        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):
        """Suorittaa generaation samanaikaisuuden hallinnalla."""
        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)
                }

Huomaa, että jokainen työtehtävä pitää tuloksensa tallessa kohdassa results, onnistui se tai epäonnistuiko: generaatio, joka katoaa ilman jälkeä, on häiriö, jota kukaan ei voi diagnosoida.

Toinen arkkitehtuurinen perusrefleksi koskee tallennusta. Koska video-URL-osoitteet ovat väliaikaisia, lataamisen on oltava automaattista ja välitöntä, ja nimeämisen on käytettävä aikaleimaa, joka takaa ettei kahden samanaikaisen generaation välillä tapahdu törmäyksiä.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Lataa ja tallentaa luodun videon."""
    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

Tarkista avaimesi ennen kuin luotat siihen

Päätepiste GET /v1/api-key kertoo avaimesi tilan. Sen kutsuminen palvelun käynnistyksessä estää tilanteen, jossa huomaat avaimen olevan estetty vasta kahdenkymmenen epäonnistuneen pyynnön jälkeen käyttäjiesi odottaessa.

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-avain tai tiimi estetty, tai avain poistettu käytöstä")

Näe mitä tuotannossa tapahtuu

Viisi indikaattoria riittää video-generointipalvelun ohjaamiseen. Onnistumisaste, eli niiden generaatioiden osuus, jotka päättyvät tilaan done, mittaa yleistä terveyttä. Keskimääräinen generointiaika, mitattuna lähetyksen ja done-tilan välillä, auttaa kalibroimaan aikakatkaisusi ja informoimaan käyttäjiäsi. Virheaste eriteltynä tyypeittäin — failed virhekoodin, aikakatkaistun tai nopeusrajoituksen mukaan — kertoo, mihin effortti kannattaa kohdistaa: aikakatkaisujen nousu ilman failed-virheiden nousua signaloi esimerkiksi generaatioiden olevan hitaampia kuin odotusaikasi, ei varsinaisia epäonnistumisia. Kumulatiivinen kustannus, joka saadaan summaamalla kenttä usage.cost_in_usd_ticks jokaisesta tuloksesta (yksi dollari vastaa 10 miljardia tickiä), tai vaihtoehtoisesti kertomalla luodut kestot mallin hintaa sekunnilta, on seurattava päivittäin. Lopuksi kiintiön käyttö, eli pyynnöt sekunnissa suhteessa tason rajoitukseen (10 aloitustasolla videomalleille), ennakoi kyllästymisen ennen kuin se muuttuu 429-virheiksi.

Nämä mittarit rakentuvat luontevasti strukturoidusta lokista, jossa jokainen generaatio jättää analyysityökalusi käyttökelpoisen rivin.

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

Ennen kuin avaat palvelusi yleisölle, käy koko kokonaisuus alusta loppuun läpi. Eksponentiaalisen backoffin ja jitterin on oltava käytössä, ja samanaikaisuus on rajoitettava semaforilla pysyäksesi nopeusrajoituksen puitteissa. Videoiden latausten on käynnistyttävä automaattisesti heti kun ne ovat valmiita ilman ihmisen toimintaa. Jokaisen generaation on jätettävä lokirivi, joka sisältää sen request_id:n, tilan ja kustannuksen, muuten virheastetta ja keskimääräistä generointiaikaa ei voida varmentaa. Tarkista API-avaimen tila käynnistyksessä äläkä vasta ensimmäisen virheen yhteydessä. Ja aseta budjetti ylityshälytyksineen: hinnalla 0,05 $ sekunnilta rajaton uudelleenyrityssilmukka kuluttaa rahaa nopeammin kuin arvaatkaan.

Hinnoittelu tarkistettu 3. marraskuuta 2026 — hinnat muuttuvat säännöllisesti: ennen kuin teet budjettilaskelmia, tarkista nykyinen hinnasto xAI:n viralliselta mallit ja hinnoittelu -sivulta.

Keskeiset asiat

  • Virheet jakautuvat synkronisiin (pyyntö) ja asynkronisiin (generointi)
  • Kaikki virheet eivät ansaitse uudelleenyritystä: moderointi on lopullinen
  • Käytä semaforia rajoittaaksesi samanaikaisia generaatioita
  • Väliaikaiset URL-osoitteet vaativat välitöntä ja systemaattista lataamista
  • Seuraa kustannus-, onnistumis- ja generointiaikamittareita palvelusi ohjaamiseksi

Testaa tietämyksesi

Generatiivinen video tuotannossa: valido koko työnkulku.

1. Mitkä ovat videokehotteen erityispiirteet?

Vastaus: Kuvaile toimintaa ja liikettä, ei vain kohtausta: subjekti, siirtyminen, tunnelma, kuvakulma — aikaulottuvuus on se, mikä erottaa videokehotteen kuvakehotteesta.

2. Mitä kuva-videoksi-muunnos mahdollistaa?

Vastaus: Animoi olemassa olevan kuvan tai tuo annettuja ihmisiä ja tuotteita uuteen kohtaukseen käyttämällä referenssikuvia — ja mallilla grok-imagine-video-1.5 voit kiinnittää ensimmäisen, viimeisen tai avainkuvat: visuaalisesta identiteetistäsi tulee lähtökohta, ei sattuma.

3. Muokkaus ja jatkaminen: mitä käyttötarkoituksia?

Vastaus: /videos/edits muokkaa luotua videota, /videos/extensions pidentää sitä — ja molemmat yhdistettynä mahdollistavat pitkien sekvenssien rakentamisen iteratiivisesti.

4. Miksi työnkulku on asynkroninen?

Vastaus: Videogenerointi vie aikaa: lähetät työtehtävän, kysyt sen tilaa ja haet sitten tuloksen — xAI SDK automatisoi tämän pollauksen.

5. Mitä on suunniteltava tuotantoa varten?

Vastaus: Virheenkäsittely ja epäonnistuneet työt, tulosteiden välitön lataaminen ja kustannusten seuranta (resoluutio, kesto, iteraatiot) — video on kallein modaliteetti: se on budjetoitava.

Aikainen kehote, visuaalinen referenssi, hallittu asynkronisuus: generatiivisesta videosta tulee putki — ei arpapeliä.