Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Kérések hozzáadása JSON-ban

5. lecke 12 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Hozzáadás az API-n keresztül
  2. Kérés szerkezete
  3. cURL kérés
  4. Hozzáadás a Python SDK-val
  5. Hozzáadási sebességkorlátok
  6. Mikor használd az API-s hozzáadást?
  7. Kérésérvényesítés
  8. Főbb megállapítások

Frissítve: 2026. november 2. az xAI dokumentációja alapján: a kötegelt kedvezmény 20% a jogosult szöveges modelleknél (nem 50%), a példák a REST API-t és a hivatalos xai-sdk-t (client.batch.*) követik (az xAI Batch API nem az OpenAI formátumot használja, az OpenAI SDK nem alkalmazható), és a Responses API elsőbbséget élvez a Chat Completions felett, amely az xAI-nál már elavult végpont. Források: Batch API · REST Referencia · Batch Árazás.

Hozzáadás az API-n keresztül

Miután létrehoztad a köteget, a POST /v1/batches/{batch_id}/requests végponttal adhatsz hozzá kéréseket. Minden hívás egy kérésekkel teli listát tartalmaz, és addig hívhatod meg a végpontot, ahányszor csak szükséges, amíg a köteget nem mondták le. Ez a megközelítés az inkrementálisan felépített kötegeknél működik.

Kérés szerkezete

A hívás törzse egy batch_requests tömböt tartalmaz. Minden elem egy azonosítót (batch_request_id) párosít magával a kéréssel, amely a típusának megfelelő kulcs alatt található – a Responses API esetén ez a responses:

{
  "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: A te azonosítód, amely egyedi kell legyen a kötegen belül. Ez a kulcs kapcsolja össze a kérést az eredménnyel; ha hiányzik, az xAI generál egy UUID-t.
  • batch_request: Maga a kérés, a típusának megfelelő kulcs alatt; az API-referencia a chat_get_completion kulcsot is dokumentálja a Chat Completions formátumhoz.

Képek és videók esetén használd az SDK-t (9. lecke) vagy egy JSONL fájlt (következő lecke).

cURL kérés

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."}
            ]
          }
        }
      }
    ]
  }'

Hozzáadás a Python SDK-val

Az SDK segítségével minden kérést egy szabványos beszélgetésként építesz fel, hozzárendelsz egy batch_request_id-t, majd csoportokban adod hozzá őket:

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)

# Hozzáadás 100-as csoportokban: egy API-hívás csoportonként
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

A dokumentáció nem határoz meg maximális kérésszámot hívásonként; a mérsékelt csoportméretek egyszerűen korlátozzák azt a mennyiséget, amelyet hálózati hiba esetén újra kell küldeni.

Hozzáadási sebességkorlátok

Egy csapat legfeljebb 1000 hozzáadó hívást indíthat 30 másodpercenként, egy csúszó ablakban, amely az összes kötegére érvényes. A korlát a hívásokra vonatkozik, nem a kérésekre: 100 kérésből álló csoportok esetén ez már másodpercenként több mint 3000 kérést tesz lehetővé. Két másik korlát azonban fontosabb:

  • 25 MB maximális méret egyedi kérésenként, ami főleg a base64-ben kódolt képeket érinti
  • 100 000 kérés felett egy kötegen belül az xAI lassíthatja a feldolgozást a szolgáltatás stabilitásának megőrzése érdekében

Mikor használd az API-s hozzáadást?

Az API-s hozzáadás akkor működik jól, amikor a rugalmasság fontosabb, mint az előzetes előkészítés. Természetes választássá válik, amikor a köteget inkrementálisan építed fel: a sorból érkező kéréseket beérkezésükkor adod hozzá, míg egy JSONL fájl megkövetelné, hogy előre ismerj mindent – és lezárná a köteget. Ez az út a prototípus-készítéshez is, hogy öt kéréssel teszteld a teljes munkafolyamatot a skálázás előtt, valamint vegyes összetételű kötegeknél.

Kérésérvényesítés

Ellenőrizd minden hozzáadó hívás állapotkódját: egy ilyen hiba azt jelenti, hogy a csoportot nem mentette el a rendszer, és újra el kell küldened. Egy kérés később, feldolgozás közben is sikertelen lehet; ekkor a hibaüzenetével együtt jelenik meg az eredmények között. Ha egy modell nem fogadja el a köteget, a rendszer a not supported for batch processing üzenettel utasítja el: a nagy köteg indítása előtt ellenőrizd a jogosultságot a modell oldalán.

Főbb megállapítások

  • A hozzáadás a POST /v1/batches/{id}/requests végponton történik, egy batch_requests listával
  • Minden kérés tartalmaz egy egyedi batch_request_id-t és a tartalmát a típusának megfelelő kulcs alatt (responses, chat_get_completion)
  • Az SDK a client.chat.create(..., batch_request_id=...) segítségével építi fel a kéréseket, és a client.batch.add metódussal adja hozzá őket
  • A korlát csapatonként 1000 hozzáadó hívás 30 másodpercenként, ahol minden hívás sok kérést hordozhat
  • A JSONL fájllal ellentétben az API-s hozzáadás nyitva hagyja a köteget az új elemek számára