Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Přidávání požadavků v JSON

Lekce 5 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Přidávání přes API
  2. Struktura požadavku
  3. Požadavek cURL
  4. Přidávání pomocí Python SDK
  5. Limity rychlosti při přidávání
  6. Kdy použít přidávání přes API
  7. Validace požadavků
  8. Klíčové poznatky

Aktualizováno 2. listopadu 2026 na základě dokumentace xAI: sleva pro dávkové zpracování činí 20 % u způsobilých textových modelů (nikoli 50 %), příklady se řídí REST API a oficiálním xai-sdk (client.batch.*; Batch API od xAI nepoužívá formát OpenAI, SDK OpenAI se tedy neaplikuje) a API Responses má přednost před Chat Completions, což je u xAI zastaralý koncový bod. Zdroje: Batch API · REST Reference · Batch Pricing.

Přidávání přes API

Jakmile je dávka vytvořena, přidáš do ní požadavky pomocí POST /v1/batches/{batch_id}/requests. Každý volání nese seznam požadavků a koncový bod můžeš volat opakovaně, dokud není dávka zrušena. Tento přístup funguje pro dávky budované postupně.

Struktura požadavku

Tělo volání obsahuje pole batch_requests. Každý prvek spojuje identifikátor (batch_request_id) se samotným požadavkem, který je uložen pod klíčem odpovídajícím jeho typu – responses pro API 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: Tvůj identifikátor, jedinečný v rámci dávky. Toto je klíč, který spojuje požadavek s jeho výsledkem; pokud chybí, xAI vygeneruje UUID.
  • batch_request: Požadavek pod klíčem odpovídajícím jeho typu; reference API dokumentuje také chat_get_completion pro formát Chat Completions.

Pro obrázky a videa použij SDK (lekce 9) nebo soubor JSONL (další lekce).

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

Přidávání pomocí Python SDK

Při práci se SDK vytvoříš každý požadavek jako běžnou konverzaci, přiřadíš mu batch_request_id a následně je přidáváš po blocích:

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)

# Přidání po blocích po 100: jedno volání API na blok
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Dokumentace nestanovuje maximální počet požadavků na jedno volání; mírná velikost bloků pouze omezuje množství dat, která je třeba znovu odeslat v případě výpadku sítě.

Limity rychlosti při přidávání

Tým může provést až 1 000 volání pro přidání každých 30 sekund v pohyblivém okně sdíleném mezi všemi jeho dávkami. Limit se týká volání, nikoli jednotlivých požadavků: při blocích po 100 požadavcích to již umožňuje více než 3 000 požadavků za sekundu. Důležitější jsou však další dvě omezení:

  • 25 MB maximum pro jednotlivý požadavek, což se týká především obrázků kódovaných v base64.
  • Při překročení 100 000 požadavků v jedné dávce může xAI zpomalit zpracování, aby zachovala stabilitu služby.

Kdy použít přidávání přes API

Přidávání přes API se hodí vždy, když je flexibilita důležitější než příprava předem. Stává se přirozenou volbou, když je dávka budována postupně: požadavky přicházející z fronty se přidávají, jakmile dorazí, zatímco soubor JSONL by vyžadoval znalost všech dat předem – a dávku by uzavřel. Je to také správná cesta pro prototypování, kdy chceš otestovat celý pracovní postup s pěti požadavky před jejich navýšením, a pro heterogenní dávky.

Validace požadavků

Zkontroluj stavový kód každého volání pro přidání: chyba v této fázi znamená, že blok nebyl uložen, a musíš jej znovu odeslat. Požadavek může také selhat později, během zpracování; v takovém případě se objeví ve výsledcích spolu se svou chybovou zprávou. Model, který nepřijímá dávkové zpracování, bude odmítnut se zprávou not supported for batch processing: před spuštěním velké dávky si ověř způsobilost na stránce modelu.

Klíčové poznatky

  • Přidávání probíhá přes POST /v1/batches/{id}/requests se seznamem batch_requests.
  • Každý požadavek nese jedinečné batch_request_id a svůj obsah pod klíčem odpovídajícím typu (responses, chat_get_completion).
  • SDK vytváří požadavky pomocí client.chat.create(..., batch_request_id=...) a přidává je přes client.batch.add.
  • Limit pro tým činí 1 000 volání pro přidání každých 30 sekund, přičemž každé volání může nést mnoho požadavků.
  • Na rozdíl od souboru JSONL ponechává přidávání přes API dávku otevřenou pro další doplňování.