Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Παρακολούθηση, Κατάσταση και Ακύρωση

Μάθημα 11 / 12 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Διαχείριση του κύκλου ζωής της παρτίδας
  2. Δύο επίπεδα κατάστασης
  3. Έλεγχος μετρητών
  4. Λίστα των παρτίδων σας
  5. Ανάκτηση αποτελεσμάτων
  6. Έλεγχος μεταδεδομένων αιτήματος
  7. Ακύρωση μιας παρτίδας
  8. Στρατηγική polling
  9. Βασικά σημεία

Ενημερώθηκε στις 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