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

Προσθήκη αιτημάτων σε JSON

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

Ενημερώθηκε στις 2 Νοεμβρίου 2026 βάσει της τεκμηρίωσης της xAI: η έκπτωση για παρτίδες (batch) είναι 20% στα κατάλληλα μοντέλα κειμένου (όχι 50%), τα παραδείγματα ακολουθούν το REST API και το επίσημο xai-sdk (client.batch.*· το Batch API της xAI δεν χρησιμοποιεί τη μορφή OpenAI, οπότε το SDK της OpenAI δεν εφαρμόζεται), ενώ το Responses API έχει προτεραιότητα έναντι του Chat Completions, το οποίο αποτελεί παρωχημένο σημείο πρόσβασης στην xAI. Πηγές: Batch API · REST Reference · Batch Pricing.

Προσθήκη μέσω API

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

Δομή αιτήματος

Το σώμα της κλήσης περιέχει έναν πίνακα batch_requests. Κάθε στοιχείο συνδυάζει ένα αναγνωριστικό (batch_request_id) με το ίδιο το αίτημα, το οποίο αποθηκεύεται υπό το κλειδί που αντιστοιχεί στον τύπο του—responses για το Responses API:

{
  "batch_requests": [
    {
      "batch_request_id": "avis-001",
      "batch_request": {
        "responses": {
          "model": "grok-4.3",
          "input": [
            {"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
            {"role": "user", "content": "The product exceeded my expectations!"}
          ]
        }
      }
    }
  ]
}
  • batch_request_id: Το δικό σας αναγνωριστικό, μοναδικό εντός της παρτίδας. Αυτό είναι το κλειδί που συνδέει το αίτημα με το αποτέλεσμά του· αν λείπει, η xAI παράγει ένα UUID.
  • batch_request: Το αίτημα, υπό το κλειδί που αντιστοιχεί στον τύπο του· η αναφορά API τεκμηριώνει επίσης το chat_get_completion για τη μορφή Chat Completions.

Για εικόνες και βίντεο, χρησιμοποιήστε το SDK (μάθημα 9) ή ένα αρχείο JSONL (επόμενο μάθημα).

Αίτημα cURL

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_requests": [
      {
        "batch_request_id": "article-42",
        "batch_request": {
          "responses": {
            "model": "grok-4.3",
            "input": [
              {"role": "user", "content": "Classify this text: positive, neutral, or negative."}
            ]
          }
        }
      }
    ]
  }'

Προσθήκη με το Python SDK

Με το SDK, κάθε αίτημα δομείται όπως μια τυπική συνομιλία, εκχωρείται ένα batch_request_id και στη συνέχεια τα προσθέτετε σε τμήματα:

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()

documents = [
    {"id": "doc-1", "text": "First document to analyze..."},
    {"id": "doc-2", "text": "Second document to analyze..."},
    {"id": "doc-3", "text": "Third document to analyze..."},
]

batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"

requests = []
for doc in documents:
    chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
    chat.append(system("Summarize the document in two sentences."))
    chat.append(user(doc["text"]))
    requests.append(chat)

# Προσθήκη σε τμήματα των 100: μία κλήση API ανά τμήμα
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

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

Όρια ρυθμού κατά την προσθήκη

Μια ομάδα μπορεί να πραγματοποιήσει έως και 1.000 κλήσεις προσθήκης κάθε 30 δευτερόλεπτα, σε ένα κυλιόμενο παράθυρο που κοινοποιείται σε όλες τις παρτίδες της. Το όριο ισχύει για τις κλήσεις, όχι για τα αιτήματα: με τμήματα 100 αιτημάτων, αυτό επιτρέπει ήδη περισσότερα από 3.000 αιτήματα ανά δευτερόλεπτο. Δύο άλλοι περιορισμοί είναι πιο σημαντικοί:

  • 25 MB μέγιστο ανά μεμονωμένο αίτημα, γεγονός που αφορά κυρίως εικόνες κωδικοποιημένες σε base64.
  • Πέραν των 100.000 αιτημάτων σε μια παρτίδα, η xAI ενδέχεται να επιβραδύνει την επεξεργασία για να διατηρήσει τη σταθερότητα της υπηρεσίας.

Πότε να χρησιμοποιήσετε την προσθήκη μέσω API

Η προσθήκη μέσω API λειτουργεί όποτε η ευελιξία έχει μεγαλύτερη σημασία από την εκ των προτέρων προετοιμασία. Γίνεται η φυσική επιλογή όταν η παρτίδα δομείται σταδιακά: τα αιτήματα που φτάνουν από μια ουρά προστίθενται καθώς εισέρχονται, ενώ ένα αρχείο JSONL θα απαιτούσε να γνωρίζετε τα πάντα εκ των προτέρων—και θα έκλεινε την παρτίδα. Είναι επίσης η διαδρομή για τη δημιουργία πρωτοτύπων, ώστε να δοκιμάσετε την πλήρη ροή εργασίας με πέντε αιτήματα πριν την κλιμάκωση, καθώς και για ετερογενείς παρτίδες.

Επικύρωση αιτήματος

Ελέγξτε τον κωδικό κατάστασης κάθε κλήσης προσθήκης: ένα σφάλμα σε αυτό το στάδιο σημαίνει ότι το τμήμα δεν αποθηκεύτηκε και πρέπει να το στείλετε εκ νέου. Ένα αίτημα μπορεί επίσης να αποτύχει αργότερα, κατά την επεξεργασία· τότε εμφανίζεται στα αποτελέσματα με το μήνυμα σφάλματός του. Ένα μοντέλο που δεν δέχεται την παρτίδα απορρίπτεται με το μήνυμα not supported for batch processing: ελέγξτε τη καταλληλότητα στη σελίδα του μοντέλου πριν ξεκινήσετε μια μεγάλη παρτίδα.

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

  • Η προσθήκη γίνεται μέσω του POST /v1/batches/{id}/requests, με μια λίστα batch_requests.
  • Κάθε αίτημα φέρει ένα μοναδικό batch_request_id και το περιεχόμενό του υπό το κλειδί που αντιστοιχεί στον τύπο του (responses, chat_get_completion).
  • Το SDK δομεί τα αιτήματα με client.chat.create(..., batch_request_id=...) και τα προσθέτει με client.batch.add.
  • Το όριο είναι 1.000 κλήσεις προσθήκης ανά 30 δευτερόλεπτα για την ομάδα· κάθε κλήση μπορεί να μεταφέρει πολλά αιτήματα.
  • Σε αντίθεση με το αρχείο JSONL, η προσθήκη μέσω API αφήνει την παρτίδα ανοιχτή για νέες προσθήκες.