Διαχείριση Σφαλμάτων και Ανάπτυξη σε Παραγωγή
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 με βάση την τεκμηρίωση βίντεο της xAI και τον κώδικα
xai-sdk1.21.0:client.video.generate(όχιclient.videos), το αποτέλεσμα επιστρέφεται στο πεδίοurl, οι αποτυχίες αναφέρονται μέσωVideoGenerationErrorμε κωδικό (invalid_argument,service_unavailable…), το όριο ρυθμού λαμβάνεται ωςgrpc.RpcErrorμε κωδικόRESOURCE_EXHAUSTED— η κλάσηRateLimitErrorκαι η κατάστασηexpiredδεν υπάρχουν. Συμπλήρωμα 3 Νοεμβρίου 2026: το όριο ρυθμού μετρά αιτήματα ανά δευτερόλεπτο (10 στο βασικό επίπεδο), όχι «60 RPM», και το πραγματικό κόστος ανά δημιουργία διαβάζεται από τοusage.cost_in_usd_ticks. Πηγές: Δημιουργία Βίντεο · Όρια Ρυθμού.
Προετοιμάστε την Εφαρμογή σας για Παραγωγή
Ένα σενάριο που δημιουργεί ένα βίντεο στον υπολογιστή σας και μια υπηρεσία που παράγει εκατοντάδες την ημέρα για πραγματικούς χρήστες δεν έχουν σχεδόν τίποτα κοινό. Η δεύτερη πρέπει να διαχειρίζεται αρνήσεις moderation, υπερβάσεις ποσοστώσεων, περιστατικά διακομιστή και λήξεις URL χωρίς ποτέ να χάνει σιωπηλά μια χρεώσιμη δημιουργία. Αυτό το μάθημα καλύπτει τους μηχανισμούς που κάνουν τη διαφορά: ταξινόμηση σφαλμάτων, στρατηγική επαναδοκιμής, αρχιτεκτονική ουράς και παρατηρησιμότητα.
Δύο Οικογένειες Σφαλμάτων, Δύο Χρονικές Στιγμές
Η πρώτη οικογένεια εμφανίζεται άμεσα, τη στιγμή της κλήσης POST. Πρόκειται για αυστηρά σφάλματα αιτήματος, και ο κωδικός HTTP αρκεί για να αποφασίσετε τι θα κάνετε.
| Κωδικός HTTP | Αιτία | Λύση |
|---|---|---|
| 400 | Μη έγκυρες παράμετροι (για παράδειγμα, άγνωστη φωνή στο reference_audios) | Διορθώστε το αίτημα |
| 401 | Μη έγκυρο ή ληγμένο κλειδί API | Επαληθεύστε τον έλεγχο ταυτότητας |
| 429 | Υπέρβαση ορίου ρυθμού (αιτήματα ανά δευτερόλεπτο, ανάλογα με το επίπεδο) | Υλοποιήστε backoff |
| 500 | Σφάλμα διακομιστή | Επαναδοκιμάστε με εκθετικό backoff |
Η δεύτερη οικογένεια εκδηλώνεται πολύ αργότερα, κατά την περιοδική επαλήθευση (polling), αφού το αίτημα έχει γίνει δεκτό και η δημιουργία έχει ξεκινήσει.
| Κατάσταση | Πιθανή Αιτία | Ενέργεια |
|---|---|---|
failed + invalid_argument ή permission_denied | Άρνηση αιτήματος ή περιεχομένου | Τροποποιήστε την εντολή (prompt) ή την πηγή |
failed + service_unavailable ή internal_error | Υπερφόρτωση υπηρεσίας, περιστατικό | Επαναδοκιμάστε αργότερα |
Αυτή η διάκριση δεν είναι ακαδημαϊκή: ένα 400 πρέπει να επιστρέφει άμεσα στον καλούντα επειδή το σφάλμα βρίσκεται στον κώδικα, ενώ μια κατάσταση failed συμβαίνει μετά από αρκετά λεπτά αναμονής και πρέπει να διαχειρίζεται στο πλαίσιο της εργασίας (job), όχι στο αίτημα HTTP που την πυροδότησε.
Επαναδοκιμάστε Έξυπνα
Η κοινή βάση είναι το εκθετικό backoff με κάποια διακύμανση (jitter). Ο διπλασιασμός της καθυστέρησης δίνει χρόνο σε ένα παροδικό περιστατικό να επιλυθεί, και η διακύμανση εμποδίζει όλες τις διεργασίες σας να επαναδοκιμάσουν την ίδια στιγμή μετά από μια αιχμή — ένα φαινόμενο που μετατρέπει μια μικροδιακοπή σε διαρκή αποτυχία.
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)
Αυτό το γενικό σχήμα δεν αρκεί, ωστόσο, επειδή δεν αξίζουν όλα τα σφάλματα την ίδια υπομονή. Μια υπέρβαση ποσόστωσης επιλύεται περιμένοντας ένα πλήρες λεπτό· μια άρνηση moderation δεν θα επιλυθεί ποτέ, και η επαναδοκιμή ισοδυναμεί με πληρωμή πολλαπλών φορές για την ίδια αποτυχία. Η παρακάτω συνάρτηση διαφοροποιεί τις περιπτώσεις.
import asyncio
from datetime import timedelta
import grpc
from xai_sdk.video import VideoGenerationError
# Failure codes that a retry will not fix
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)
Μια Ουρά για να Κρατήσετε τον Ρυθμό
Μόλις η υπηρεσία σας αρχίσει να λαμβάνει αιτήματα από πολλούς χρήστες, πρέπει να αποσυνδέσετε τη λήψη των αιτημάτων από την εκτέλεση και, πάνω απ’ όλα, να οριοθετήσετε τον ταυτόχρονο αριθμό εκτελέσεων για να παραμείνετε κάτω από το όριο ρυθμού του επιπέδου σας. Μια ουρά σε συνδυασμό με ένα semaphore καλύπτει και τις δύο ανάγκες: οι εργασίες στοιβάζονται ελεύθερα, αλλά το πολύ δέκα εκτελούνται ταυτόχρονα.
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)
}
Σημειώστε ότι κάθε εργασία διατηρεί το αποτέλεσμά της στο results, επιτυχία ή αποτυχία: μια δημιουργία που εξαφανίζεται χωρίς ίχνη είναι ένα περιστατικό που κανείς δεν μπορεί να διαγνώσει.
Ο δεύτερος ανακλαστικός κανόνας αρχιτεκτονικής αφορά την αποθήκευση. Επειδή τα URL των βίντεο είναι προσωρινά, η λήψη πρέπει να είναι αυτόματη και άμεση, με ονοματοδοσία βάσει χρονοσήμου που εγγυάται ότι δεν θα υπάρξει σύγκρουση μεταξύ δύο ταυτόχρονων δημιουργιών.
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
Επαληθεύστε το Κλειδί σας Πριν Εξαρτηθείτε από Αυτό
Το σημείο τελικού GET /v1/api-key σας ενημερώνει για την κατάσταση του κλειδιού σας. Η κλήση του κατά την εκκίνηση της υπηρεσίας αποφεύγει την ανακάλυψη ενός μπλοκαρισμένου κλειδιού μετά από είκοσι αποτυχημένα αιτήματα, ενώ οι χρήστες σας περιμένουν.
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")
Δείτε Τι Συμβαίνει σε Παραγωγή
Πέντε δείκτες αρκούν για να καθοδηγήσετε μια υπηρεσία δημιουργίας βίντεο. Το ποσοστό επιτυχίας, δηλαδή το μερίδιο των δημιουργιών που καταλήγουν σε done, μετρά τη γενική υγεία. Ο μέσος χρόνος δημιουργίας, μετρούμενος μεταξύ της υποβολής και της κατάστασης done, χρησιμεύει για τη βαθμονόμηση των χρονικών ορίων σας και την ενημέρωση των χρηστών σας. Το ποσοστό σφαλμάτων ανά τύπο — failed ανά κωδικό σφάλματος, χρονικό όριο, όριο ρυθμού — σας λέει πού να εστιάσετε την προσπάθεια: μια αύξηση στα χρονικά όρια χωρίς αύξηση στα failed σηματοδοτεί δημιουργίες πιο αργές από την προθεσμία αναμονής σας, για παράδειγμα, όχι αποτυχίες. Το σωρευτικό κόστος, που λαμβάνεται αθροίζοντας το πεδίο usage.cost_in_usd_ticks από κάθε αποτέλεσμα (ένα δολάριο ισούται με 10 δισεκατομμύρια ticks), ή εναλλακτικά πολλαπλασιάζοντας τις παραγόμενες διάρκειες με την τιμή του μοντέλου ανά δευτερόλεπτο, πρέπει να παρακολουθείται καθημερινά. Τέλος, η χρήση ποσόστωσης, σε αιτήματα ανά δευτερόλεπτο σε σχέση με το όριο του επιπέδου σας (10 στο βασικό επίπεδο για μοντέλα βίντεο), προβλέπει τον κορεσμό πριν αυτό μεταφραστεί σε 429.
Αυτές οι μετρικές χτίζονται φυσικά από ένα δομημένο αρχείο καταγραφής, όπου κάθε δημιουργία αφήνει μια γραμμή usable από το εργαλείο ανάλυσής σας.
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
}))
Πριν ανοίξετε την υπηρεσία σας στο κοινό, αναθεωρήστε τα πάντα από την αρχή. Η επαναδοκιμή με εκθετικό backoff και διακύμανση πρέπει να είναι ενεργή, και ο ταυτόχρονος αριθμός εκτελέσεων να οριοθετείται από ένα semaphore για να παραμείνετε κάτω από το όριο ρυθμού. Οι λήψεις βίντεο πρέπει να ενεργοποιούνται αυτόματα μόλις είναι έτοιμες, χωρίς να εξαρτώνται από ανθρώπινη ενέργεια. Κάθε δημιουργία πρέπει να αφήνει μια γραμμή καταγραφής που να φέρει το request_id, την κατάσταση και το κόστος της, διαφορετικά το ποσοστό σφαλμάτων και ο μέσος χρόνος δημιουργίας θα παραμείνουν μη επαληθεύσιμοι. Ελέγξτε την κατάσταση του κλειδιού API κατά την εκκίνηση και όχι κατά την πρώτη αποτυχία. Και ορίστε έναν προϋπολογισμό με ειδοποιήσεις υπέρβασης: στα 0,05 $ ανά δευτερόλεπτο, ένας απεριόριστος βρόχος επαναδοκιμής καταναλώνει πόρους γρηγορότερα από όσο νομίζετε.
Τιμολόγηση επαληθεύτηκε στις 3 Νοεμβρίου 2026 — οι τιμές εξελίσσονται τακτικά: πριν από οποιοδήποτε υπολογισμό προϋπολογισμού, επαληθεύστε το τρέχον πλέγμα στην επίσημη σελίδα μοντέλων και τιμολόγησης της xAI.
Βασικά σημεία
- Τα σφάλματα χωρίζονται σε σύγχρονα (αιτήματος) και ασύγχρονα (δημιουργίας)
- Δεν αξίζουν όλα τα σφάλματα επαναδοκιμή: το moderation είναι οριστικό
- Χρησιμοποιήστε ένα semaphore για να περιορίσετε τις ταυτόχρονες δημιουργίες
- Τα προσωρινά URL απαιτούν άμεση και συστηματική λήψη
- Παρακολουθήστε μετρικές κόστους, επιτυχίας και χρόνου δημιουργίας για να καθοδηγήσετε την υπηρεσία σας
Δοκιμάστε τις Γνώσεις σας
Δημιουργικό βίντεο σε παραγωγή: επικυρώστε την πλήρη ροή εργασίας.
1. Ποιες είναι οι ιδιαιτερότητες μιας εντολής (prompt) βίντεο;
Απάντηση: Περιγράψτε τη δράση και την κίνηση, όχι μόνο τη σκηνή: θέμα, μετατόπιση, ατμόσφαιρα, κάδρο — η χρονική διάσταση είναι αυτό που διακρίνει την εντολή βίντεο από την εντολή εικόνας.
2. Τι επιτρέπει η μετατροπή εικόνας σε βίντεο;
Απάντηση: Να εμψυχώσει μια υπάρχουσα εικόνα, ή να φέρει συγκεκριμένα άτομα και προϊόντα σε μια νέα σκηνή χρησιμοποιώντας εικόνες αναφοράς — και, στο grok-imagine-video-1.5, να καρφιτσώσετε την πρώτη, την τελευταία ή τις βασικές εικόνες: η οπτική σας ταυτότητα γίνεται σημείο εκκίνησης, όχι τυχαίο γεγονός.
3. Επεξεργασία και επέκταση: ποιες χρήσεις;
Απάντηση: Το /videos/edits τροποποιεί ένα παραγόμενο βίντεο, το /videos/extensions το παρατείνει — και τα δύο συνδυάζονται για να χτίσουν μακριές ακολουθίες μέσω επαναλήψεων.
4. Γιατί η ροή εργασίας είναι ασύγχρονη;
Απάντηση: Η δημιουργία βίντεο παίρνει χρόνο: υποβάλλετε μια εργασία, ελέγχετε περιοδικά την κατάστασή της και στη συνέχεια ανακτάτε το αποτέλεσμα — το xAI SDK αυτοματοποιεί αυτή την περιοδική επαλήθευση.
5. Τι να σχεδιάσετε για την παραγωγή;
Απάντηση: Διαχείριση σφαλμάτων και αποτυχημένων εργασιών, άμεση λήψη των εξόδων και παρακολούθηση κόστους (ανάλυση, διάρκεια, επαναλήψεις) — το βίντεο είναι η πιο ακριβή μορφή: πρέπει να προϋπολογίζεται.
Χρονική εντολή, οπτική αναφορά, κυριαρχημένο async: το δημιουργικό βίντεο γίνεται αγωγός — όχι λαχείο.