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

Πλήρης αγωγός end-to-end

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

Το μάθημα ενημερώθηκε στις 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.

Συναρμολόγηση των επιμέρους τμημάτων

Τα προηγούμενα μαθήματα κάλυψαν κάθε βήμα μεμονωμένα. Αυτό το μάθημα τα συναρμολογεί σε έναν πλήρη αγωγό, από την προετοιμασία των δεδομένων έως την επεξεργασία των αποτελεσμάτων. Στο τέλος, θα διαθέτετε ένα script που μπορείτε να προσαρμόσετε στη δική σας περίπτωση χρήσης.

Πλήρης αγωγός σε Python

import json
import time

from xai_sdk import Client

client = Client()  # key read from XAI_API_KEY

# --- Step 1: prepare data ---
documents = [
    {"id": f"doc-{i}", "text": f"Document content {i}..."}
    for i in range(100)
]

# --- Step 2: write the JSONL file ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Summarize in two sentences."},
                    {"role": "user", "content": doc["text"]},
                ],
                "max_output_tokens": 200,
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

# --- Step 3: upload the file ---
with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")

# --- Step 4: create the batch from the file (it is now sealed) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")

# --- Step 5: wait for processing to finish ---
while True:
    batch = client.batch.get(batch_id=batch.batch_id)
    etat = batch.state
    if batch.cancel_by_xai_message:
        raise RuntimeError(f"Batch canceled by xAI: {batch.cancel_by_xai_message}")
    if etat.num_requests > 0 and etat.num_pending == 0:
        break
    print(f"{etat.num_success + etat.num_error}/{etat.num_requests} requests processed")
    time.sleep(300)  # every 5 minutes

# --- Step 6: retrieve results, page by page ---
resultats, echecs = {}, []
jeton = None
while True:
    page = client.batch.list_batch_results(
        batch_id=batch.batch_id, limit=100, pagination_token=jeton
    )
    for r in page.succeeded:
        resultats[r.batch_request_id] = r.response.content
    echecs.extend(page.failed)
    if page.pagination_token is None:
        break
    jeton = page.pagination_token

with open("batch_results.json", "w", encoding="utf-8") as f:
    json.dump(resultats, f, ensure_ascii=False, indent=2)

print(f"{len(resultats)} results, {len(echecs)} failures")
print("Total cost: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Τρεις λεπτομέρειες έχουν σημασία. Η συνθήκη τερματισμού απαιτεί num_requests > 0, επειδή ένα batch που δημιουργείται από αρχείο διαβάζεται στο παρασκήνιο: αμέσως μετά τη δημιουργία, οι μετρητές του μπορεί να είναι ακόμη όλοι μηδέν. Το πεδίο cancel_by_xai_message σηματοδοτεί ακύρωση από την xAI, για παράδειγμα λόγω μη έγκυρης γραμμής. Και το κόστος εκφράζεται σε ticks, δηλαδή δέκα δισεκατομμυριοστά του δολαρίου.

Αγωγός βήμα προς βήμα με cURL

Αν προτιμάτε τη γραμμή εντολών, ορίστε το ισοδύναμο σε cURL (χρησιμοποιώντας το jq για την ανάγνωση των αποκρίσεων):

# 1. Upload the JSONL file
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl" | jq -r '.id')
echo "File: $FILE_ID"

# 2. Create the batch from the file
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Batch: $BATCH_ID"

# 3. Read counters
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $XAI_API_KEY" | jq '.state'

# 4. Retrieve the first page of results
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json

Λαμβάνετε τις επόμενες σελίδες προσθέτοντας &pagination_token=… με την τιμή που επιστρέφεται από την προηγούμενη σελίδα.

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

Ένας αξιόπιστος αγωγός διακρίνει τρεις οικογένειες σφαλμάτων:

Σφάλματα υποβολής: αποτυχία μεταφόρτωσης αρχείου ή δημιουργίας batch. Επαναλάβετε τα παροδικά σφάλματα (χρονικό όριο, όριο ρυθμού, σφάλμα διακομιστή) με αυξανόμενη καθυστέρηση: 1 δευτ., 2 δευτ., 4 δευτ., 8 δευτ.

Σφάλματα επεξεργασίας: ορισμένα αιτήματα αποτυγχάνουν εντός του batch. Εμφανίζονται στο page.failed μαζί με το μήνυμά τους· υποβάλετέ τα ξανά, και μόνο αυτά, σε ένα νέο batch.

Χρονικά όρια και λήξη: το παράθυρο των 24 ωρών είναι ενδεικτικό, όχι εγγυημένο. Αυτό που είναι αμείλικτο είναι η λήξη (expire_time): μετά από αυτό το σημείο, τα αποτελέσματα δεν είναι πλέον προσβάσιμα. Ανακτάτε τα καθώς έρχονται, αντί να τα παίρνετε όλα μαζί στο τέλος.

# Failed requests: identify them to resubmit in a new batch
for r in echecs:
    print(f"Failure: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}

Βελτιστοποίηση κόστους

Οι εξοικονομήσεις συσσωρεύονται μέσω τεσσάρων μοχλών. Η επιλογή μοντέλου έρχεται πρώτη, μακράν ο πιο ισχυρός παράγοντας: με την τυπική χρέωση της 2ας Νοεμβρίου 2026, το grok-4.3 κοστίζει 1,25 $ ανά εκατομμύριο tokens εισόδου και 2,50 $ για την έξοδο, έναντι 2 $ και 6 $ για το grok-4.7 (για prompts κάτω από 200.000 tokens). Για ταξινόμηση ή σύντομη εξαγωγή, το ελαφρύτερο μοντέλο συχνά αρκεί, και η έκπτωση batch 20% ισχύει και για τα δύο. Στη συνέχεια έρχεται το μήκος απόκρισης: το max_output_tokens αποτρέπει την πληρωμή για περιττά μεγάλες εξόδους· για ταξινόμηση, αρκούν μερικά tokens. Prompts: η αφαίρεση δέκα tokens από ένα prompt που επαναλαμβάνεται 50.000 φορές εξοικονομεί 500.000 tokens εισόδου. Τέλος, η cache: η xAI κάνει αυτόματα cache στην αρχή πανομοιότυπων αιτημάτων, και η έκπτωση batch ισχύει επίσης για τα tokens που εξυπηρετούνται από την cache· επομένως, τοποθετήστε κοινές οδηγίες στην αρχή κάθε αιτήματος, πριν από το μεταβαλλόμενο μέρος.

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

  • Ένας πλήρης αγωγός καλύπτει έξι βήματα: προετοιμασία, JSONL, μεταφόρτωση, δημιουργία, παρακολούθηση, ανάκτηση
  • Ένα batch από αρχείο διαβάζεται στο παρασκήνιο: περιμένετε έως ότου num_requests > 0 πριν συμπεράνετε ότι ολοκληρώθηκε
  • Διαχειριστείτε τις τρεις οικογένειες σφαλμάτων: υποβολή, επεξεργασία, χρονικό όριο και λήξη
  • Ανακτάτε και αποθηκεύετε τα αποτελέσματα καθώς έρχονται, πριν από το expire_time
  • Η επιλογή μοντέλου, το μήκος εξόδου, τα σύντομα prompts και τα κοινά προθέματα μεγιστοποιούν τις εξοικονομήσεις