Flux de lucru în patru pași
Pe această pagină
Actualizat la 2 noiembrie 2026 pe baza documentației xAI: reducerea pentru loturi este de 20% la modelele de text eligibile (nu 50%); exemplele utilizează API-ul REST și SDK-ul oficial
xai-sdk(client.batch.*; API-ul Batch de la xAI nu respectă formatul OpenAI, deci 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.
Ciclul de viață al unui lot
Fiecare lot urmează același ciclu: creare, adăugare cereri, procesare, preluare rezultate. Înțelegerea acestui ciclu este esențială înainte de a trece la implementare, deoarece fiecare pas are propriile constrângeri și bune practici.
Pasul 1: Crearea unui lot
Totul începe cu un apel POST /v1/batches, care necesită un singur câmp obligatoriu: numele lotului. API-ul returnează un identificator unic (batch_id) pe care îl veți utiliza pentru toate operațiunile ulterioare.
curl -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "customer_review_analysis"}'
Răspunsul conține, de asemenea, datele de creare și expirare ale lotului (create_time, expire_time) și un obiect state ale cărui contoare sunt încă toate la zero.
Pasul 2: Adăugarea cererilor
Există două metode:
Prin API: trimiteți cereri folosind POST /v1/batches/{batch_id}/requests. Fiecare apel transportă o listă de cereri și le puteți adăuga continuu atâta timp cât lotul nu este anulat. Aceasta este calea pentru loturile construite incremental.
Printr-un fișier JSONL: pregătiți un fișier care conține toate cererile dumneavoastră, îl încărcați prin API-ul Files, apoi creați lotul din acel fișier. Lotul este apoi sigilat: nu mai sunt posibile adăugări. Aceasta este calea pentru volumele mari pregătite în avans.
Fiecare cerere include un identificator unic în cadrul lotului: batch_request_id în API, custom_id în fișierul JSONL. Dacă îl omiteți în API, xAI generează un UUID; furnizați-l pe al dumneavoastră în schimb (un ID din baza de date, de exemplu): acesta servește drept cheie de corespondență între datele dumneavoastră și rezultate și garantează că o cerere este procesată o singură dată.
Pasul 3: Monitorizarea progresului
Procesarea începe imediat ce sosesc cererile; nu există un pas de „start“. Între timp, GET /v1/batches/{batch_id} returnează obiectul state și contoarele sale: num_requests (total), num_pending (în așteptare), num_success (reușite), num_error (eșuate) și num_cancelled (anulate).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Când num_pending scade la zero, toate cererile au fost procesate, cu succes sau nu. Interogarea periodică este suficientă: câteva secunde pentru un lot mic de test, câteva minute pentru un lot mare.
Pasul 4: Preluarea rezultatelor
Rezultatele se citesc cu GET /v1/batches/{batch_id}/results, fără a aștepta finalizarea lotului: fiecare cerere este disponibilă imediat ce este procesată. Răspunsul este paginat: limit stabilește dimensiunea paginii (maxim 1.000), iar pagination_token returnat se utilizează pentru a solicita pagina următoare; acesta este gol pe ultima pagină.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Fiecare rezultat conține batch_request_id al cererii sale: acest lucru vă permite să reconstruiți corespondența dintre datele de intrare și răspunsurile Grok.
Fluxul de lucru în practică
Într-un pipeline de producție, fluxul de lucru se traduce, în general, în două procese separate:
- Un proces de submitere care creează lotul, pregătește și adaugă cererile, apoi stochează
batch_id - Un proces de preluare care verifică periodic contoarele și descarcă rezultatele pe măsură ce devin disponibile
Această separare vă permite să integrați API-ul Batch în arhitecturi conduse de evenimente sau în pipeline-uri de date existente (job-uri cron, Apache Airflow, cozi).
Gestionarea erorilor în fluxul de lucru
Un lot nu are o stare globală de „reușit“ sau „eșuat“: o citiți prin intermediul contoarelor sale. O cerere eșuată incrementează num_error și apare în rezultate cu mesajul său de eroare, fără a bloca celelalte. Prin urmare, trebuie să examinați fiecare rezultat și să gestionați eșecurile caz cu caz.
Două evenimente afectează întregul lot. Primul este anularea, de către dumneavoastră sau de către xAI, care explică apoi motivul în câmpul cancel_by_xai_message. Acest lucru se întâmplă în special atunci când o linie dintr-un fișier JSONL este invalidă. Celălalt este expirarea (expire_time), după care rezultatele nu mai sunt accesibile: preluați-le prompt.
Puncte cheie
- Fluxul de lucru urmează ordinea: creare (cu un nume), adăugare, monitorizare, preluare
- Identificatorul cererii (
batch_request_idsaucustom_idîn JSONL) este cheia dumneavoastră de corespondență - Progresul se citește din contoarele
state; totul este procesat cândnum_pendingeste zero - Rezultatele sunt paginate (
limit,pagination_token) și disponibile pe măsură ce sunt procesate - Erorile se gestionează cerere cu cerere; anularea și expirarea afectează întregul lot