Salt la conținutul principal
Română— Alege o limbă
Meniu

Adăugarea cererilor în format JSON

Lecția 5 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Adăugarea prin API
  2. Structura cererii
  3. Cerere cURL
  4. Adăugarea cu SDK-ul Python
  5. Limite de rată la adăugare
  6. Când să utilizați adăugarea prin API
  7. Validarea cererilor
  8. Puncte cheie

Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%), exemplele urmează API-ul REST și SDK-ul oficial xai-sdk (client.batch.*; API-ul Batch xAI nu folosește formatul OpenAI, iar SDK-ul OpenAI nu se aplică), iar API-ul Responses are prioritate față de Chat Completions, un punct final moștenit la xAI. Surse: Batch API · Referință REST · Prețuri Batch.

Adăugarea prin API

Odată creat lotul, adăugați cererile folosind POST /v1/batches/{batch_id}/requests. Fiecare apel conține o listă de cereri și puteți invoca punctul final de câte ori este necesar, atâta timp cât lotul nu este anulat. Această abordare funcționează pentru loturile construite incremental.

Structura cererii

Corpul apelului conține un tablou batch_requests. Fiecare element asociază un identificator (batch_request_id) cu cererea propriu-zisă, stocată sub cheia corespunzătoare tipului său – responses pentru API-ul 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: Identificatorul dumneavoastră, unic în cadrul lotului. Aceasta este cheia care face legătura între cerere și rezultatul său; dacă lipsește, xAI generează un UUID.
  • batch_request: Cererea, plasată sub cheia specifică tipului său; referința API documentează, de asemenea, chat_get_completion pentru formatul Chat Completions.

Pentru imagini și videoclipuri, utilizați SDK-ul (lecția 9) sau un fișier JSONL (lecția următoare).

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

Adăugarea cu SDK-ul Python

Cu SDK-ul, fiecare cerere este construită ca o conversație standard, i se atribuie un batch_request_id, iar apoi le adăugați în blocuri:

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)

# Adăugare în blocuri de 100: un apel API per bloc
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Documentația nu stabilește un număr maxim de cereri per apel; dimensiuni moderate ale blocurilor limitează pur și simplu ceea ce trebuie retrimis în cazul unui incident de rețea.

Limite de rată la adăugare

O echipă poate efectua până la 1.000 de apeluri de adăugare la fiecare 30 de secunde, într-o fereastră glisantă partajată între toate loturile sale. Limita se aplică apelurilor, nu cererilor: cu blocuri de 100 de cereri, acest lucru permite deja mai mult de 3.000 de cereri pe secundă. Două alte limite sunt mai relevante:

  • 25 MB maxim per cerere individuală, ceea ce privește în principal imaginile codificate în base64
  • Peste 100.000 de cereri într-un lot, xAI poate încetini procesarea pentru a păstra stabilitatea serviciului

Când să utilizați adăugarea prin API

Adăugarea prin API funcționează ori de câte ori flexibilitatea contează mai mult decât pregătirea inițială. Devine alegerea naturală când lotul este construit incremental: cererile care sosesc dintr-o coadă sunt adăugate pe măsură ce apar, în timp ce un fișier JSONL ar necesita cunoașterea tuturor datelor în avans – și ar închide lotul. Este, de asemenea, calea pentru prototipare, pentru a testa fluxul complet de lucru cu cinci cereri înainte de a scala, și pentru loturile eterogene.

Validarea cererilor

Verificați codul de stare al fiecărui apel de adăugare: o eroare în această etapă înseamnă că blocul nu a fost salvat și trebuie să îl retrimiteți. O cerere poate eșua, de asemenea, mai târziu, în timpul procesării; în acest caz, aceasta apare în rezultate împreună cu mesajul de eroare. Un model care nu acceptă lotul este respins cu mesajul not supported for batch processing: verificați eligibilitatea pe pagina modelului înainte de a lansa un lot de mari dimensiuni.

Puncte cheie

  • Adăugarea se face prin POST /v1/batches/{id}/requests, cu o listă batch_requests
  • Fiecare cerere conține un batch_request_id unic și conținutul său sub cheia specifică tipului (responses, chat_get_completion)
  • SDK-ul construiește cererile cu client.chat.create(..., batch_request_id=...) și le adaugă cu client.batch.add
  • Limita este de 1.000 de apeluri de adăugare la 30 de secunde pentru echipă; fiecare apel poate transporta multe cereri
  • Spre deosebire de fișierul JSONL, adăugarea prin API menține lotul deschis pentru noi adăugiri