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

Ροή εργασίας τεσσάρων βημάτων

Μάθημα 2 / 12 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Ο κύκλος ζωής μιας παρτίδας
  2. Βήμα 1: Δημιουργία παρτίδας
  3. Βήμα 2: Προσθήκη αιτημάτων
  4. Βήμα 3: Παρακολούθηση προόδου
  5. Βήμα 4: Ανάκτηση αποτελεσμάτων
  6. Η ροή εργασίας στην πράξη
  7. Διαχείριση σφαλμάτων στη ροή εργασίας
  8. Βασικά σημεία

Ενημερώθηκε στις 2 Νοεμβρίου 2026 με βάση την τεκμηρίωση της xAI: η έκπτωση για παρτίδες (batch) είναι 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.

Ο κύκλος ζωής μιας παρτίδας

Κάθε παρτίδα ακολουθεί τον ίδιο κύκλο: δημιουργία, προσθήκη αιτημάτων, επεξεργασία, ανάκτηση αποτελεσμάτων. Η κατανόηση αυτού του κύκλου είναι απαραίτητη πριν προχωρήσετε στην υλοποίηση, καθώς κάθε βήμα διαθέτει τους δικούς του περιορισμούς και βέλτιστες πρακτικές.

Βήμα 1: Δημιουργία παρτίδας

Όλα ξεκινούν με μια κλήση POST /v1/batches, με ένα απαιτούμενο πεδίο: το όνομα της παρτίδας. Το API επιστρέφει ένα μοναδικό αναγνωριστικό (batch_id) που θα χρησιμοποιήσετε για όλες τις επόμενες λειτουργίες.

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

Η απόκριση περιέχει επίσης τις ημερομηνίες δημιουργίας και λήξης της παρτίδας (create_time, expire_time) καθώς και ένα αντικείμενο state του οποίου οι μετρητές είναι αρχικά όλοι στο μηδέν.

Βήμα 2: Προσθήκη αιτημάτων

Υπάρχουν δύο μέθοδοι:

Μέσω του API: στέλνετε αιτήματα με POST /v1/batches/{batch_id}/requests. Κάθε κλήση μεταφέρει μια λίστα αιτημάτων και μπορείτε να συνεχίσετε να προσθέτετε όσα επιθυμείτε, αρκεί η παρτίδα να μην έχει ακυρωθεί. Αυτός είναι ο δρόμος για παρτίδες που δομούνται σταδιακά.

Μέσω αρχείου JSONL: προετοιμάζετε ένα αρχείο που περιέχει όλα τα αιτήματά σας, το ανεβάζετε μέσω του Files API και στη συνέχεια δημιουργείτε την παρτίδα από αυτό το αρχείο. Η παρτίδα τότε σφραγίζεται: δεν είναι δυνατή καμία περαιτέρω προσθήκη. Αυτός είναι ο δρόμος για μεγάλους όγκους δεδομένων που έχουν προετοιμαστεί εκ των προτέρων.

Κάθε αίτημα φέρει ένα μοναδικό αναγνωριστικό εντός της παρτίδας: batch_request_id στο API, custom_id στο αρχείο JSONL. Αν το παραλείψετε στο API, η xAI παράγει ένα UUID· δώστε το δικό σας αντίθετα (για παράδειγμα, ένα ID βάσης δεδομένων): λειτουργεί ως κλειδί συσχέτισης μεταξύ των δεδομένων σας και των αποτελεσμάτων και εγγυάται ότι ένα αίτημα θα επεξεργαστεί μόνο μία φορά.

Βήμα 3: Παρακολούθηση προόδου

Η επεξεργασία ξεκινά μόλις φτάσουν τα αιτήματα· δεν υπάρχει βήμα «έναρξης». Εν τω μεταξύ, το GET /v1/batches/{batch_id} επιστρέφει το αντικείμενο state και τους μετρητές του: num_requests (σύνολο), num_pending (σε εκκρεμότητα), num_success (επιτυχημένα), num_error (αποτυχημένα) και num_cancelled (ακυρωμένα).

curl https://api.x.ai/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $XAI_API_KEY"

Όταν το num_pending πέσει στο μηδέν, όλα τα αιτήματα έχουν επεξεργαστεί, είτε επιτυχώς είτε όχι. Η περιοδική polling επαρκεί: λίγα δευτερόλεπτα για μια μικρή παρτίδα δοκιμής, λίγα λεπτά για μια μεγάλη παρτίδα.

Βήμα 4: Ανάκτηση αποτελεσμάτων

Τα αποτελέσματα διαβάζονται με GET /v1/batches/{batch_id}/results, χωρίς να περιμένετε την ολοκλήρωση της παρτίδας: κάθε αίτημα είναι διαθέσιμο μόλις επεξεργαστεί. Η απόκριση είναι σελιδοποιημένη: το limit ορίζει το μέγεθος σελίδας (μέγιστο 1.000) και το επιστρεφόμενο pagination_token χρησιμοποιείται για την αίτηση της επόμενης σελίδας· είναι κενό στην τελευταία σελίδα.

curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY"

Κάθε αποτέλεσμα φέρει το batch_request_id του αιτήματός του: αυτό σας επιτρέπει να ανακατασκευάσετε τη χαρτογράφηση μεταξύ των δεδομένων εισόδου σας και των απαντήσεων του Grok.

Η ροή εργασίας στην πράξη

Σε μια παραγωγική διαδικασία (pipeline), η ροή εργασίας μεταφράζεται συνήθως σε δύο ξεχωριστές διαδικασίες:

  • Μια διαδικασία υποβολής που δημιουργεί την παρτίδα, προετοιμάζει και προσθέτει τα αιτήματα, και στη συνέχεια αποθηκεύει το batch_id
  • Μια διαδικασία ανάκτησης που ελέγχει περιοδικά τους μετρητές και κατεβάζει τα αποτελέσματα μόλις γίνουν διαθέσιμα

Αυτός ο διαχωρισμός σας επιτρέπει να ενσωματώσετε το Batch API σε αρχιτεκτονικές βασισμένες σε συμβάντα ή σε υπάρχουσες ροές δεδομένων (cron jobs, Apache Airflow, ουρές).

Διαχείριση σφαλμάτων στη ροή εργασίας

Μια παρτίδα δεν έχει μια γενική κατάσταση «επιτυχία» ή «αποτυχία»: την διαβάζετε μέσω των μετρητών της. Ένα αποτυχημένο αίτημα αυξάνει το num_error και εμφανίζεται στα αποτελέσματα με το μήνυμα σφάλματός του, χωρίς να εμποδίζει τα υπόλοιπα. Επομένως, πρέπει να εξετάζετε κάθε αποτέλεσμα και να χειρίζεστε τις αποτυχίες κατά περίπτωση.

Δύο γεγονότα επηρεάζουν ολόκληρη την παρτίδα. Το πρώτο είναι η ακύρωση, από εσάς ή από την xAI, η οποία τότε το εξηγεί στο πεδίο cancel_by_xai_message. Αυτό συμβαίνει ειδικότερα όταν μια γραμμή σε ένα αρχείο JSONL είναι μη έγκυρη. Το άλλο είναι η λήξη (expire_time), μετά την οποία τα αποτελέσματα δεν είναι πλέον προσβάσιμα: ανακτήστε τα άμεσα.

Βασικά σημεία

  • Η ροή εργασίας ακολουθεί τη σειρά: δημιουργία (με όνομα), προσθήκη, παρακολούθηση, ανάκτηση
  • Το αναγνωριστικό αιτήματος (batch_request_id, ή custom_id στο JSONL) είναι το κλειδί συσχέτισής σας
  • Η πρόοδος διαβάζεται από τους μετρητές state· όλα επεξεργάζονται όταν το num_pending είναι μηδέν
  • Τα αποτελέσματα είναι σελιδοποιημένα (limit, pagination_token) και διαθέσιμα καθώς επεξεργάζονται
  • Τα σφάλματα διαχειρίζονται αίτημα προς αίτημα· η ακύρωση και η λήξη επηρεάζουν ολόκληρη την παρτίδα