Παρακολούθηση, Κατάσταση και Ακύρωση
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 βάσει της τεκμηρίωσης της xAI: η έκπτωση παρτίδας είναι 20% στα eligible μοντέλα κειμένου (όχι 50%), τα παραδείγματα ακολουθούν το REST API και το επίσημο
xai-sdk(client.batch.*· το Batch API της xAI δεν ταιριάζει με τη μορφή της OpenAI, οπότε το SDK της OpenAI δεν εφαρμόζεται), και το Responses API υπερισχύει του Chat Completions, το οποίο αποτελεί legacy endpoint στην xAI. Πηγές: Batch API · REST Reference · Batch Pricing.
Διαχείριση του κύκλου ζωής της παρτίδας
Μόλις υποβάλετε τα αιτήματά σας, πρέπει να παρακολουθείτε την πρόοδο της επεξεργασίας, να διαβάζετε τις καταστάσεις και να γνωρίζετε πότε και πώς να ακυρώσετε μια παρτίδα. Αυτό το μάθημα καλύπτει όλες τις διαθέσιμες λειτουργίες διαχείρισης.
Δύο επίπεδα κατάστασης
Η xAI παρακολουθεί την πρόοδο σε δύο επίπεδα. Η ίδια η παρτίδα δεν διαθέτει γενική κατάσταση όπως «ολοκληρώθηκε» ή «απέτυχε»: μεταφέρει μετρητές στο αντικείμενο state της. Κάθε αίτημα, ωστόσο, έχει τη δική του κατάσταση:
| Κατάσταση αιτήματος | Σημασία | Ενέργεια |
|---|---|---|
pending | Σε ουρά | Αναμονή |
succeeded | Επεξεργάστηκε, αποτέλεσμα διαθέσιμο | Ανάκτηση αποτελέσματος |
failed | Σφάλμα κατά την επεξεργασία | Ανάγνωση μηνύματος, επανάληψη αν χρήσιμο |
cancelled | Ακυρώθηκε, για παράδειγμα με την παρτίδα του | Επανυποβολή αν χρειάζεται |
Η παρτίδα έχει επεξεργαστεί πλήρως όταν ο μετρητής num_pending μηδενιστεί. Μπορεί επίσης να ακυρωθεί ή να λήξει: μετά το expire_time, τα αποτελέσματά της δεν είναι πλέον προσβάσιμα.
Έλεγχος μετρητών
Η κλήση GET /v1/batches/{batch_id} επιστρέφει την παρτίδα και τους μετρητές της:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Η απόκριση περιλαμβάνει:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Αυτοί οι μετρητές παρακολουθούν την πρόοδο σε πραγματικό χρόνο, χωρίς να περιμένετε την ολοκλήρωση της επεξεργασίας. Με το SDK, τα διαβάζετε στο client.batch.get(batch_id=...).state.
Λίστα των παρτίδων σας
Για να βρείτε μια παρτίδα ή να ελέγξετε το ιστορικό:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Η λίστα είναι σελιδοποιημένη μέσω των limit και pagination_token. Οι παρτίδες παραμένουν εκεί μέχρι τη λήξη τους. Με το SDK, το client.batch.list(limit=20) επιστρέφει μια λίστα batches όπου κάθε στοιχείο φέρει το name, το batch_id και το state του. Η κονσόλα της xAI προσφέρει την ίδια προβολή, σε οπτική μορφή.
Ανάκτηση αποτελεσμάτων
Μπορείτε να ανακτήσετε αποτελέσματα ανά πάσα στιγμή, ακόμη και κατά τη διάρκεια της επεξεργασίας:
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Κάθε αποτέλεσμα φέρει το batch_request_id του αιτήματός του. Τα αποτυχημένα αιτήματα εμφανίζονται εκεί με το μήνυμά τους· με το SDK, οι ιδιότητες succeeded και failed κάθε σελίδας τα διαχωρίζουν.
Έλεγχος μεταδεδομένων αιτήματος
Για να παρακολουθείτε την κατάσταση κάθε αιτήματος:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Κάθε εγγραφή παρέχει το αναγνωριστικό του αιτήματος, το endpoint του, το μοντέλο, την κατάσταση, καθώς και τις ημερομηνίες δημιουργίας και λήξης. Αυτό είναι το εργαλείο διάγνωσης όταν ένας μετρητής σταματά, ή για να επαληθεύσετε τι προστέθηκε επιτυχώς.
Ακύρωση μιας παρτίδας
Εάν χρειάζεται να σταματήσετε την επεξεργασία που βρίσκεται σε εξέλιξη:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Η ακύρωση είναι οριστική: τα εκκρεμή αιτήματα δεν θα επεξεργαστούν και δεν μπορείτε πλέον να προσθέσετε αιτήματα στην παρτίδα. Τα αιτήματα που έχουν ήδη επεξεργαστεί, ωστόσο, παραμένουν διαθέσιμα στα αποτελέσματα. Ακυρώστε εάν:
- Εντοπίσατε σφάλμα στα αιτήματά σας μετά την υποβολή
- Η παρτίδα δεν χρειάζεται πλέον (αλλαγή προτεραιότητας)
- Θέλετε να επανυποβάλετε μια διορθωμένη παρτίδα
Με το SDK: client.batch.cancel(batch_id=...), το οποίο επιστρέφει την παρτίδα και τους μετρητές της τη στιγμή της ακύρωσης.
Στρατηγική polling
Σε περιβάλλον παραγωγής, περιμένετε την ολοκλήρωση με αραιό polling και μέγιστη καθυστέρηση:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Ένα διάστημα λίγων λεπτών ταιριάζει σε μεγάλες παρτίδες· η τεκμηρίωση της xAI κάνει polling κάθε λίγα δευτερόλεπτα στα παραδείγματά της, τα οποία καλύπτουν μικρές παρτίδες. Και καθώς τα αποτελέσματα είναι διαθέσιμα μόλις φτάνουν, τίποτα δεν εμποδίζει την ανάκτησή τους κατά την αναμονή.
Βασικά σημεία
- Διαβάστε την παρτίδα μέσω των μετρητών της (
num_pending,num_success,num_error…): κάθε αίτημα έχει τη δική του κατάσταση:pending,succeeded,failed,cancelled - Το
GET /v1/batches/{id}δίνει την πρόοδο, το/resultsτα αποτελέσματα, το/requestsτις λεπτομέρειες του αιτήματος - Η ακύρωση (
POST /v1/batches/{id}:cancel) είναι μη αναστρέψιμη, αλλά διατηρεί τα αποτελέσματα που έχουν ήδη παραχθεί - Οι λίστες και τα αποτελέσματα σελιδοποιούνται με
limitκαιpagination_token - Κάντε polling σε διαστήματα λίγων λεπτών, με μέγιστη καθυστέρηση, και ανακτήστε τα πριν το
expire_time