Przepływ pracy w czterech krokach
Na tej stronie
Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji xAI: rabat na partie wynosi 20% dla kwalifikujących się modeli tekstowych (a nie 50%); przykłady wykorzystują interfejs REST oraz oficjalny pakiet
xai-sdk(client.batch.*; interfejs Batch API od xAI nie遵循 formatu OpenAI, więc SDK OpenAI nie ma zastosowania); a interfejs Responses API ma pierwszeństwo przed Chat Completions, który jest przestarzałym punktem końcowym w xAI. Źródła: Batch API · Dokumentacja REST · Cennik Batch API.
Cykl życia partii
Każda partia przechodzi przez ten sam cykl: utworzenie, dodanie żądań, przetworzenie, pobranie wyników. Zrozumienie tego cyklu jest kluczowe przed przejściem do implementacji, ponieważ każdy krok ma swoje własne ograniczenia i najlepsze praktyki.
Krok 1: Utworzenie partii
Wszystko zaczyna się od wywołania POST /v1/batches, z jednym wymaganym polem: nazwą partii. Interfejs API zwraca unikalny identyfikator (batch_id), którego używasz we wszystkich kolejnych operacjach.
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"}'
Odpowiedź zawiera również daty utworzenia i wygaśnięcia partii (create_time, expire_time) oraz obiekt state, którego liczniki są nadal ustawione na zero.
Krok 2: Dodawanie żądań
Istnieją dwie metody:
Poprzez interfejs API: wysyłasz żądania za pomocą POST /v1/batches/{batch_id}/requests. Każde wywołanie przenosi listę żądań i możesz je dodawać tak długo, jak długo partia nie zostanie anulowana. Jest to ścieżka dla partii budowanych przyrostowo.
Poprzez plik JSONL: przygotowujesz plik zawierający wszystkie swoje żądania, przesyłasz go przez Files API, a następnie tworzysz partię na podstawie tego pliku. Partia zostaje wtedy zapieczętowana: nie można dodać już żadnych elementów. Jest to ścieżka dla dużych woluminów przygotowanych wcześniej.
Każde żądanie posiada unikalny identyfikator w ramach partii: batch_request_id w interfejsie API lub custom_id w pliku JSONL. Jeśli pominiesz go w interfejsie API, xAI wygeneruje UUID; podaj własny (na przykład ID z bazy danych): służy on jako klucz dopasowania między Twoimi danymi a wynikami i gwarantuje, że żądanie zostanie przetworzone tylko raz.
Krok 3: Monitorowanie postępu
Przetwarzanie rozpoczyna się natychmiast po nadejściu żądań; nie ma osobnego kroku „start“. W międzyczasie GET /v1/batches/{batch_id} zwraca obiekt state i jego liczniki: num_requests (łącznie), num_pending (oczekujące), num_success (udane), num_error (nieudane) oraz num_cancelled (anulowane).
curl https://api.x.ai/v1/batches/$BATCH_ID \
-H "Authorization: Bearer $XAI_API_KEY"
Gdy num_pending spadnie do zera, wszystkie żądania zostały przetworzone, niezależnie od tego, czy zakończyły się sukcesem, czy nie. Wystarczy okresowe odpytywanie: kilka sekund dla małej partii testowej, kilka minut dla dużej partii.
Krok 4: Pobieranie wyników
Wyniki odczytuje się za pomocą GET /v1/batches/{batch_id}/results, bez oczekiwania na zakończenie partii: każde żądanie jest dostępne zaraz po jego przetworzeniu. Odpowiedź jest paginowana: limit ustawia rozmiar strony (maksymalnie 1000), a zwracany pagination_token służy do żądania kolejnej strony; jest on pusty na ostatniej stronie.
curl "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY"
Każdy wynik zawiera batch_request_id swojego żądania: pozwala to na odtworzenie mapowania między danymi wejściowymi a odpowiedziami modelu Grok.
Przepływ pracy w praktyce
W środowisku produkcyjnym przepływ pracy zazwyczaj przekłada się na dwa oddzielne procesy:
- Proces przesyłania, który tworzy partię, przygotowuje i dodaje żądania, a następnie przechowuje
batch_id - Proces pobierania, który okresowo sprawdza liczniki i pobiera wyniki, gdy tylko станут dostępne
Taki rozdział pozwala zintegrować Batch API z architekturami sterowanymi zdarzeniami lub istniejącymi potokami danych (zadania cron, Apache Airflow, kolejki).
Obsługa błędów w przepływie pracy
Partia nie posiada globalnego stanu „udana“ lub „nieudana“: odczytujesz go poprzez jej liczniki. Nieudane żądanie inkrementuje num_error i pojawia się w wynikach wraz z komunikatem o błędzie, nie blokując pozostałych. Dlatego musisz zbadać każdy wynik i obsługiwać awarie indywidualnie.
Dwa zdarzenia wpływają na całą partię. Pierwszym jest anulowanie, przez Ciebie lub przez xAI, co jest wtedy wyjaśniane w polu cancel_by_xai_message. Dzieje się tak w szczególności, gdy linia w pliku JSONL jest nieprawidłowa. Drugim jest wygaśnięcie (expire_time), po którym wyniki stają się niedostępne: pobierz je niezwłocznie.
Kluczowe wnioski
- Przepływ pracy przebiega w kolejności: utwórz (z nazwą), dodaj, monitoruj, pobierz
- Identyfikator żądania (
batch_request_idlubcustom_idw JSONL) jest Twoim kluczem dopasowania - Postęp odczytuje się z liczników
state; wszystko jest przetworzone, gdynum_pendingwynosi zero - Wyniki są paginowane (
limit,pagination_token) i dostępne w miarę ich przetwarzania - Błędy obsługuje się żądanie po żądaniu; anulowanie i wygaśnięcie wpływają na całą partię