Przejdź do głównej treści
Polski— Wybierz język
Menu

Obsługa błędów i wdrażanie produkcyjne

Lekcja 12 z 12 Zaktualizowano 3 listopada 2026 Średnio zaawansowani
Na tej stronie
  1. Przygotuj aplikację do środowiska produkcyjnego
  2. Dwie rodziny błędów, dwa momenty
  3. Ponawiaj próby inteligentnie
  4. Kolejka, by utrzymać tempo
  5. Zweryfikuj klucz, zanim zaczniesz od niego zależać
  6. Zobacz, co dzieje się w produkcji
  7. Kluczowe wnioski
  8. Sprawdź swoją wiedzę

Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji wideo xAI oraz kodu xai-sdk w wersji 1.21.0: client.video.generate (nie client.videos), wynik w polu url, błędy zgłaszane przez VideoGenerationError z kodem (invalid_argument, service_unavailable…), limit przepustowości otrzymywany jako grpc.RpcError z kodem RESOURCE_EXHAUSTED — klasa RateLimitError i status expired nie istnieją. Uzupełnienie z 3 listopada 2026 r.: limit przepustowości liczy żądania na sekundę (10 w warstwie wejściowej), a nie „60 RPM“, a rzeczywisty koszt generowania odczytuje się z pola usage.cost_in_usd_ticks. Źródła: Generowanie wideo · Limity przepustowości.

Przygotuj aplikację do środowiska produkcyjnego

Skrypt generujący wideo na Twoim komputerze a usługa produkująca setki filmów dziennie dla rzeczywistych użytkowników mają ze sobą niewiele wspólnego. Ta druga musi obsługiwać odmowy moderacji, przekroczenia limitów, awarie serwerów i wygasające adresy URL, nigdy po cichu nie tracąc płatnego generowania. Ta lekcja omawia mechanizmy, które robią różnicę: klasyfikację błędów, strategię ponawiania prób, architekturę kolejki i obserwowalność.

Dwie rodziny błędów, dwa momenty

Pierwsza rodzina pojawia się natychmiast, w momencie wywołania POST. Są to ścisłe błędy żądania, a kod HTTP wystarczy, by zdecydować, co zrobić.

Kod HTTPPrzyczynaRozwiązanie
400Nieprawidłowe parametry (np. nieznany głos w reference_audios)Napraw żądanie
401Nieprawidłowy lub wygasły klucz APIZweryfikuj uwierzytelnienie
429Przekroczony limit przepustowości (żądania na sekundę, zależnie od warstwy)Zaimplementuj wycofanie (backoff)
500Błąd serweraPonów próbę z wycofaniem wykładniczym

Druga rodzina manifestuje się znacznie później, podczas odpytywania (polling), po zaakceptowaniu żądania i rozpoczęciu generowania.

StatusPrawdopodobna przyczynaDziałanie
failed + invalid_argument lub permission_deniedOdrzucone żądanie lub treśćZmień prompt lub źródło
failed + service_unavailable lub internal_errorPrzeciążenie usługi, incydentPonów próbę później

To rozróżnienie nie jest akademickie: kod 400 musi natychmiast wrócić do wywołującego, ponieważ wina leży po stronie kodu, podczas gdy status failed występuje po kilku minutach oczekiwania i musi być obsłużony w kontekście zadania, a nie żądania HTTP, które je uruchomiło.

Ponawiaj próby inteligentnie

Wspólną podstawą jest wycofanie wykładnicze (exponential backoff) z pewnym losowym zaburzeniem (jitter). Podwojenie opóźnienia daje chwilowemu incydentowi czas na rozwiązanie, a jitter zapobiega sytuacji, w której wszystkie Twoje procesy ponawiają próbę w tym samym momencie po skoku obciążenia — zjawisku, które zamienia mikrowyłączenie w trwałą awarię.

import asyncio
import random

async def call_with_retry(func, max_retries=3, base_delay=2):
    """Wykonuje funkcję z ponawianiem prób i wycofaniem wykładniczym."""
    for attempt in range(max_retries + 1):
        try:
            return await func()
        except Exception as e:
            if attempt == max_retries:
                raise

            # Wycofanie wykładnicze z jitterem
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            print(f"Próba {attempt + 1} nieudana: {e}. Ponawianie za {delay:.1f}s")
            await asyncio.sleep(delay)

Ten ogólny schemat jednak nie wystarcza, ponieważ nie wszystkie błędy zasługują na taką samą cierpliwość. Przekroczenie limitu rozwiązuje się poprzez odczekanie pełnej minuty; odmowa moderacji nigdy się nie rozwiąże, a ponawianie próby oznacza płacenie wielokrotnie za tę samą porażkę. Poniższa funkcja rozróżnia te przypadki.

import asyncio
from datetime import timedelta

import grpc
from xai_sdk.video import VideoGenerationError

# Kody błędów, których ponowienie nie naprawi
REQUIRES_FIX = {"invalid_argument", "permission_denied", "failed_precondition"}


async def generate_with_retry(client, params, max_retries=3):
    """Generowanie wideo z celowanym ponawianiem prób (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  # odrzucono żądanie lub treść: napraw przed ponownym uruchomieniem
            await asyncio.sleep(5 * (attempt + 1))  # usługa przeciążona, incydent
        except grpc.RpcError as e:
            if e.code() != grpc.StatusCode.RESOURCE_EXHAUSTED or is_last:
                raise
            await asyncio.sleep(2 ** attempt)  # limit przepustowości: backoff
        except TimeoutError:
            if is_last:
                raise
            # Pozwól na więcej czasu dla następnej próby
            params["timeout"] = params.get("timeout", timedelta(minutes=10)) + timedelta(minutes=2)

Kolejka, by utrzymać tempo

Gdy tylko Twoja usługa zacznie otrzymywać żądania od wielu użytkowników, musisz oddzielić przyjmowanie żądań od ich wykonania, a przede wszystkim ograniczyć współbieżność, aby pozostać w limicie przepustowości swojej warstwy. Kolejka w połączeniu z semaforem spełnia obie potrzeby: zadania stackują się swobodnie, ale jednocześnie wykonuje się maksymalnie dziesięć.

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):
        """Dodaje generowanie do kolejki."""
        self.queue.append((job_id, params))

    async def process(self):
        """Przetwarza wszystkie oczekujące generowania."""
        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):
        """Wykonuje generowanie z kontrolą współbieżności."""
        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)
                }

Zauważ, że każde zadanie przechowuje swój wynik w results, sukces lub porażkę: generowanie, które znika bez śladu, to incydent, którego nikt nie zdiagnozuje.

Drugi odruch architektoniczny dotyczy przechowywania. Ponieważ adresy URL wideo są tymczasowe, pobieranie musi być automatyczne i natychmiastowe, z nazewnictwem opatrzonym znacznikiem czasu, co gwarantuje brak kolizji między dwoma jednoczesnymi generowaniami.

import httpx
from pathlib import Path
from datetime import datetime

async def save_video(video_url, output_dir="./videos"):
    """Pobiera i zapisuje wygenerowane wideo."""
    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

Zweryfikuj klucz, zanim zaczniesz od niego zależać

Punkt końcowy GET /v1/api-key informuje o stanie Twojego klucza. Wywołanie go przy uruchamianiu usługi pozwala uniknąć odkrycia zablokowanego klucza po dwudziestu nieudanych żądaniach, podczas gdy Twoi użytkownicy czekają.

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("Klucz API lub zespół zablokowany, albo klucz wyłączony")

Zobacz, co dzieje się w produkcji

Pięć wskaźników wystarczy do sterowania usługą generowania wideo. Wskaźnik sukcesu, czyli udział generowań kończących się statusem done, mierzy ogólny stan zdrowia. Średni czas generowania, mierzony od zgłoszenia do statusu done, służy do kalibracji limitów czasu i informowania użytkowników. Wskaźnik błędów podzielony na typy — failed według kodu błędu, timeout, limit przepustowości — mówi Ci, gdzie skupić wysiłek: wzrost liczby timeoutów bez wzrostu liczby failed sygnalizuje na przykład, że generowania są wolniejsze niż Twój deadline oczekiwania, a nie że zawiodły. Skumulowany koszt, uzyskany przez zsumowanie pola usage.cost_in_usd_ticks z każdego wyniku (jeden dolar równa się 10 miliardom ticków) lub alternatywnie przez pomnożenie wygenerowanych czasów trwania przez cenę modelu za sekundę, musi być monitorowany codziennie. Wreszcie, wykorzystanie limitu, w żądaniach na sekundę względem limitu Twojej warstwy (10 w warstwie wejściowej dla modeli wideo), pozwala przewidzieć nasycenie, zanim przełoży się ono na kody 429.

Te metryki budują się naturalnie na podstawie ustrukturyzowanego logu, gdzie każde generowanie pozostawia linię użyteczną dla Twojego narzędzia analitycznego.

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

Zanim udostępnisz swoją usługę publicznie, przejrzyj całość od początku. Ponawianie prób z wycofaniem wykładniczym i jitterem musi być wdrożone, a współbieżność ograniczona przez semafor, aby pozostać w limicie przepustowości. Pobieranie wideo musi uruchamiać się automatycznie, gdy tylko są gotowe, bez zależności od działania człowieka. Każde generowanie musi pozostawić linię logu zawierającą request_id, status i koszt, w przeciwnym razie wskaźnik błędów i średni czas generowania pozostaną niesprawdzalne. Sprawdź stan klucza API przy uruchamianiu, a nie przy pierwszej awarii. I ustal budżet z alertami przekroczenia: przy 0,05 USD za sekundę, nieograniczona pętla ponawiania prób zużywa środki szybciej, niż myślisz.

Ceny zweryfikowane 3 listopada 2026 r. — ceny ewoluują regularnie: przed jakimkolwiek obliczeniem budżetu sprawdź aktualny cennik na oficjalnej stronie modeli i cen xAI.

Kluczowe wnioski

  • Błędy dzielą się na synchroniczne (żądanie) i asynchroniczne (generowanie)
  • Nie wszystkie błędy zasługują na ponowienie: moderacja jest ostateczna
  • Użyj semafora, aby ograniczyć współbieżne generowania
  • Tymczasowe adresy URL wymagają natychmiastowego i systematycznego pobierania
  • Śledź metryki kosztu, sukcesu i czasu generowania, aby sterować swoją usługą

Sprawdź swoją wiedzę

Generatywne wideo w produkcji: zwaliduj pełny przepływ pracy.

1. Jakie są szczególne cechy promptu wideo?

Odpowiedź: Opisz akcję i ruch, a nie tylko scenę: obiekt, przemieszczenie, atmosfera, kadrowanie — wymiar czasowy to właśnie to, co odróżnia prompt wideo od promptu obrazowego.

2. Co umożliwia obraz-do-wideo (image-to-video)?

Odpowiedź: Animowanie istniejącego obrazu lub wprowadzanie danych osób i produktów do nowej sceny przy użyciu obrazów referencyjnych — a w przypadku grok-imagine-video-1.5 przypinanie pierwszego, ostatniego lub kluczowych kadrów: Twoja identyfikacja wizualna staje się punktem wyjścia, a nie przypadkowym zdarzeniem.

3. Edycja i rozszerzanie: jakie zastosowania?

Odpowiedź: /videos/edits modyfikuje wygenerowane wideo, /videos/extensions przedłuża je — a oba łączą się, by budować długie sekwencje poprzez iteracje.

4. Dlaczego przepływ pracy jest asynchroniczny?

Odpowiedź: Generowanie wideo zajmuje czas: zgłaszasz zadanie, odpytujesz jego status, a następnie pobierasz wynik — SDK xAI automatyzuje to odpytywanie.

5. Co zaplanować dla produkcji?

Odpowiedź: Obsługę błędów i nieudanych zadań, natychmiastowe pobieranie wyników oraz śledzenie kosztów (rozdzielczość, czas trwania, iteracje) — wideo to najdroższy rodzaj treści: musi być budżetowane.

Prompt czasowy, odniesienie wizualne, opanowana asynchroniczność: generatywne wideo staje się potokiem przetwarzania — a nie loterią.