Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Dodajanje zahtevkov v JSON

Lekcija 5 od 12 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Dodajanje prek API-ja
  2. Struktura zahtevka
  3. Zahtevek cURL
  4. Dodajanje s Python SDK-jem
  5. Omejitve hitrosti pri dodajanju
  6. Kdaj uporabiti dodajanje prek API-ja
  7. Preverjanje veljavnosti zahtevkov
  8. Ključne ugotovitve

Posodobljeno 2. novembra 2026 na podlagi dokumentacije xAI: popust za paketne obdelave znaša 20 % za ustrezne besedilne modele (ne 50 %), primeri sledijo REST API-ju in uradnemu paketu xai-sdk (client.batch.*; paketni API xAI ne uporablja formata OpenAI, zato SDK OpenAI ne velja), API Responses pa ima prednost pred Chat Completions, ki je pri xAI zastarela končna točka. Viri: Batch API · REST Reference · Batch Pricing.

Dodajanje prek API-ja

Ko je paket ustvarjen, mu zahtevke dodaš z POST /v1/batches/{batch_id}/requests. Vsak klic prenese seznam zahtevkov, končno točko pa lahko kličeš poljubno pogosto, dokler paket ni preklican. Ta pristop deluje za pakete, ki jih gradiš postopoma.

Struktura zahtevka

Telo klica vsebuje polje batch_requests. Vsak element povezuje identifikator (batch_request_id) z samim zahtevkom, ki je shranjen pod ključem, ki ustreza njegovi vrsti – responses za 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: Tvoj identifikator, edinstven znotraj paketa. To je ključ, ki povezuje zahtevek z njegovim rezultatom; če ga izpustiš, xAI samodejno ustvari UUID.
  • batch_request: Zahtevek pod ključem, ki ustreza njegovi vrsti; referenca API-ja dokumentira tudi chat_get_completion za format Chat Completions.

Za slike in videoposnetke uporabi SDK (lekcija 9) ali datoteko JSONL (naslednja lekcija).

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

Dodajanje s Python SDK-jem

S SDK-jem vsak zahtevek sestaviš kot običajen pogovor, mu dodeliš batch_request_id, nato pa jih dodaš v sklopih:

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)

# Dodajanje v sklopih po 100: en klic API-ja na sklop
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Dokumentacija ne določa največjega števila zahtevkov na klic; zmerni velikosti sklopov preprosto omejita količino podatkov, ki jih je treba ponovno poslati v primerom omrežne napake.

Omejitve hitrosti pri dodajanju

Ekipa lahko izvede do 1.000 klicev za dodajanje vsakih 30 sekund v drsečem oknu, ki je skupno za vse njene pakete. Omejitev velja za klice, ne za zahtevke: s sklopi po 100 zahtevkov to že omogoča več kot 3.000 zahtevkov na sekundo. Pomembnejši sta dve drugi meji:

  • Največ 25 MB na posamezen zahtevek, kar zadeva predvsem slike, kodirane v base64.
  • Pri več kot 100.000 zahtevkih v paketu lahko xAI upočasni obdelavo, da ohrani stabilnost storitve.

Kdaj uporabiti dodajanje prek API-ja

Dodajanje prek API-ja uporabiš, kadar je fleksibilnost pomembnejša od vnaprejšnje priprave. Postane naravna izbira, ko paket gradiš postopoma: zahtevki, ki prispevajo iz čakalne vrste, se dodajo sproti, medtem ko bi datoteka JSONL zahtevala poznavanje vseh podatkov vnaprej – in bi paket zaprla. To je tudi prava pot za prototipiranje, da preizkusiš celoten delovni tok s petimi zahtevki pred razširitvijo, ter za heterogene pakete.

Preverjanje veljavnosti zahtevkov

Preveri kodo stanja vsakega klica za dodajanje: napaka v tej fazi pomeni, da sklop ni bil shranjen in ga moraš ponovno poslati. Zahtevek lahko kasneje odpove tudi med obdelavo; takrat se pojavi v rezultatih s svojim sporočilom o napaki. Model, ki ne sprejema paketne obdelave, je zavrnjen s sporočilom not supported for batch processing: pred zagonom velikega paketa preveri ustreznost na strani modela.

Ključne ugotovitve

  • Dodajanje poteka prek POST /v1/batches/{id}/requests s seznamom batch_requests.
  • Vsak zahtevek vsebuje edinstven batch_request_id in svojo vsebino pod ključem, ki ustreza njegovi vrsti (responses, chat_get_completion).
  • SDK gradi zahtevke z client.chat.create(..., batch_request_id=...) in jih doda z client.batch.add.
  • Omejitev za ekipo znaša 1.000 klicev za dodajanje na 30 sekund; vsak klic lahko prenese veliko zahtevkov.
  • Za razliko od datoteke JSONL dodajanje prek API-ja pušča paket odprt za nove dodatke.