Śledzenie postępu, statusy i anulowanie
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 odnoszą się do interfejsu REST API oraz oficjalnego
xai-sdk(client.batch.*; Batch API od xAI nie odpowiada formatowi OpenAI, więc SDK OpenAI nie ma zastosowania), a Responses API ma pierwszeństwo przed Chat Completions, które są przestarzałym punktem końcowym w xAI. Źródła: Batch API · REST Reference · Batch Pricing.
Zarządzanie cyklem życia partii
Po przesłaniu żądań musisz śledzić postęp przetwarzania, odczytywać statusy oraz wiedzieć, kiedy i jak anulować partię. Ta lekcja omawia wszystkie dostępne operacje zarządzania.
Dwa poziomy statusu
xAI śledzi postęp na dwóch poziomach. Sama partia nie posiada globalnego statusu typu „ukończono“ lub „niepowodzenie“: zawiera liczniki w obiekcie state. Każde żądanie ma natomiast swój własny status:
| Status żądania | Znaczenie | Działanie |
|---|---|---|
pending | W kolejce | Czekaj |
succeeded | Przetworzono, wynik dostępny | Pobierz wynik |
failed | Błąd podczas przetwarzania | Przeczytaj komunikat, ponów próbę, jeśli warto |
cancelled | Anulowano, np. wraz z partią | Wyślij ponownie, jeśli konieczne |
Partia jest w pełni przetworzona, gdy jej licznik num_pending spadnie do zera. Może zostać również anulowana lub wygasnąć: po upływie expire_time jej wyniki nie są już dostępne.
Sprawdzanie liczników
Wywołanie GET /v1/batches/{batch_id} zwraca partię i jej liczniki:
curl "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY"
Odpowiedź zawiera:
{
"batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
"name": "analyse_avis_clients",
"state": {
"num_requests": 500,
"num_pending": 155,
"num_success": 342,
"num_error": 3,
"num_cancelled": 0
}
}
Liczniki te śledzą postęp w czasie rzeczywistym, bez oczekiwania na zakończenie przetwarzania. Korzystając z SDK, odczytujesz je w client.batch.get(batch_id=...).state.
Wyświetlanie listy partii
Aby znaleźć partię lub sprawdzić historię:
curl "https://api.x.ai/v1/batches?limit=20" \
-H "Authorization: Bearer $XAI_API_KEY"
Lista jest paginowana za pomocą parametrów limit i pagination_token. Partie pozostają na liście aż do wygaśnięcia. Korzystając z SDK, client.batch.list(limit=20) zwraca listę batches, gdzie każdy element zawiera swoje name, batch_id i state. Konsola xAI oferuje ten sam widok w formie graficznej.
Pobieranie wyników
Wyniki możesz pobierać w dowolnym momencie, nawet podczas przetwarzania:
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. Nieudane żądania pojawiają się tam wraz z komunikatem o błędzie; w SDK właściwości succeeded i failed każdej strony rozdzielają te elementy.
Sprawdzanie metadanych żądań
Aby śledzić status każdego żądania:
curl "https://api.x.ai/v1/batches/$BATCH_ID/requests?limit=50" \
-H "Authorization: Bearer $XAI_API_KEY"
Każdy wpis zawiera identyfikator żądania, jego punkt końcowy, model, status oraz daty utworzenia i zakończenia. Jest to narzędzie diagnostyczne, gdy licznik utknął w miejscu, lub służy do weryfikacji tego, co zostało pomyślnie dodane.
Anulowanie partii
Jeśli musisz zatrzymać przetwarzanie w toku:
curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID:cancel" \
-H "Authorization: Bearer $XAI_API_KEY"
Anulowanie jest ostateczne: oczekujące żądania nie zostaną przetworzone i nie możesz już dodawać nowych żądań do partii. Żądania już przetworzone pozostają jednak dostępne w wynikach. Anuluj, jeśli:
- Wykryłeś błąd w swoich żądaniach po ich przesłaniu
- Partia nie jest już potrzebna (zmiana priorytetów)
- Chcesz przesłać poprawioną partię ponownie
Korzystając z SDK: client.batch.cancel(batch_id=...), co zwraca partię i jej liczniki w momencie anulowania.
Strategia odpytywania (Polling)
W środowisku produkcyjnym oczekuj na zakończenie, stosując odpytywanie z odpowiednimi odstępami czasu i maksymalnym opóźnieniem:
import time
def attendre_batch(client, batch_id, intervalle=300, delai_max=2 * 86400):
"""Wait until all requests in the batch are processed."""
debut = time.monotonic()
while time.monotonic() - debut < delai_max:
batch = client.batch.get(batch_id=batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Canceled by xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
return batch
print(f"{etat.num_success} succeeded, {etat.num_error} failed, "
f"{etat.num_pending} pending out of {etat.num_requests}")
time.sleep(intervalle)
raise TimeoutError(f"Batch not finished after {delai_max} s")
Interwał wynoszący kilka minut jest odpowiedni dla dużych partii; dokumentacja xAI w przykładach odpytuje co kilka sekund, co dotyczy małych partii. Ponieważ wyniki są dostępne w miarę ich pojawiania się, nic nie stoi na przeszkodzie, aby pobierać je w trakcie oczekiwania.
Kluczowe wnioski
- Odczytuj stan partii na podstawie liczników (
num_pending,num_success,num_error…); każde żądanie ma swój status:pending,succeeded,failed,cancelled GET /v1/batches/{id}podaje postęp,/resultszwraca wyniki, a/requestsszczegóły żądań- Anulowanie (
POST /v1/batches/{id}:cancel) jest nieodwracalne, ale zachowuje już wygenerowane wyniki - Listy i wyniki podlegają paginacji za pomocą
limitipagination_token - Odpytuj w odstępach kilku minut, z ustalonym maksymalnym czasem oczekiwania, i pobierz dane przed upływem
expire_time