Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pridávanie požiadaviek v JSON

Lekcia 5 z 12 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Pridávanie cez API
  2. Štruktúra požiadavky
  3. Požiadavka cURL
  4. Pridávanie pomocou Python SDK
  5. Limity rýchlosti pri pridávaní
  6. Kedy použiť pridávanie cez API
  7. Validácia požiadaviek
  8. Kľúčové poznatky

Aktualizované 2. novembra 2026 na základe dokumentácie xAI: zľava pre batchové spracovanie je 20 % na eligible textové modely (nie 50 %), príklady nasledujú REST API a oficiálny xai-sdk (client.batch.*; Batch API od xAI nepoužíva formát OpenAI, SDK od OpenAI sa neaplikuje) a Responses API má prednosť pred Chat Completions, čo je zastaraný koncový bod v xAI. Zdroje: Batch API · REST Reference · Batch Pricing.

Pridávanie cez API

Akonáhle je batch vytvorený, pridávaš doň požiadavky pomocou POST /v1/batches/{batch_id}/requests. Každý volanie nesie zoznam požiadaviek a koncový bod môžeš volať toľkokrát, koľkokrát potrebuješ, pokiaľ nie je batch zrušený. Tento prístup funguje pre batche budované prírastkovo.

Štruktúra požiadavky

Telo volania obsahuje pole batch_requests. Každý prvok spája identifikátor (batch_request_id) so samotnou požiadavkou, ktorá je uložená pod kľúčom zodpovedajúcim jej typu – responses pre 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: Tvoj identifikátor, jedinečný v rámci batchu. Toto je kľúč, ktorý spája požiadavku s jej výsledkom; ak chýba, xAI vygeneruje UUID.
  • batch_request: Požiadavka pod kľúčom pre jej typ; referenčná príručka API dokumentuje aj chat_get_completion pre formát Chat Completions.

Pre obrázky a videá použi SDK (lekcia 9) alebo súbor JSONL (ďalšia lekcia).

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

Pridávanie pomocou Python SDK

Pri použití SDK zostavíš každú požiadavku ako štandardnú konverzáciu, priradíš jej batch_request_id a následne ich pridávaš v chunkoch:

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)

# Pridávanie v chunkoch po 100: jedno API volanie na chunk
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Dokumentácia nestanovuje maximálny počet požiadaviek na jedno volanie; mierne veľkosti chunkov jednoducho obmedzujú množstvo dát, ktoré treba znovu odoslať v prípade výpadku siete.

Limity rýchlosti pri pridávaní

Tím môže vykonať až 1 000 volaní na pridanie každých 30 sekúnd v posuvnom okne zdieľanom medzi všetkými jeho batchmi. Limit sa vzťahuje na volania, nie na požiadavky: pri chunkoch po 100 požiadavkách to už umožňuje viac ako 3 000 požiadaviek za sekundu. Dôležitejšie sú však dve ďalšie obmedzenia:

  • 25 MB maximum pre jednotlivú požiadavku, čo sa týka najmä obrázkov kódovaných v base64.
  • Pri viac ako 100 000 požiadavkách v batchi môže xAI spomaliť spracovanie, aby zachovala stabilitu služby.

Kedy použiť pridávanie cez API

Pridávanie cez API funguje vždy, keď je flexibilita dôležitejšia ako príprava vopred. Stáva sa prirodzenou voľbou, keď sa batch buduje prírastkovo: požiadavky prichádzajúce z fronty sa pridávajú priebežne, zatiaľ čo súbor JSONL by si vyžadoval poznať všetko vopred – a batch by uzavrel. Je to tiež cesta pre prototypovanie, aby si otestoval celý workflow s piatimi požiadavkami pred škálovaním, a pre heterogénne batche.

Validácia požiadaviek

Skontroluj stavový kód každého volania na pridanie: chyba v tejto fáze znamená, že chunk nebol uložený a musíš ho znovu odoslať. Požiadavka môže zlyhať aj neskôr, počas spracovania; vtedy sa objaví vo výsledkoch so svojou chybovou správou. Model, ktorý neprijíma batch, bude odmietnutý so správou not supported for batch processing: pred spustením veľkého batchu skontroluj oprávnenosť na stránke modelu.

Kľúčové poznatky

  • Pridávanie prebieha cez POST /v1/batches/{id}/requests so zoznamom batch_requests.
  • Každá požiadavka nesie jedinečné batch_request_id a svoj obsah pod kľúčom pre svoj typ (responses, chat_get_completion).
  • SDK zostavuje požiadavky pomocou client.chat.create(..., batch_request_id=...) a pridáva ich cez client.batch.add.
  • Limit je 1 000 volaní na pridanie každých 30 sekúnd pre tím, pričom každé volanie môže niesť mnoho požiadaviek.
  • Na rozdiel od súboru JSONL necháva pridávanie cez API batch otvorený pre nové doplnenia.