Przejdź do głównej treści
Polski— Wybierz język
Menu

Śledzenie postępu, statusy i anulowanie

Lekcja 11 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Zarządzanie cyklem życia partii
  2. Dwa poziomy statusu
  3. Sprawdzanie liczników
  4. Wyświetlanie listy partii
  5. Pobieranie wyników
  6. Sprawdzanie metadanych żądań
  7. Anulowanie partii
  8. Strategia odpytywania (Polling)
  9. Kluczowe wnioski

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 żądaniaZnaczenieDziałanie
pendingW kolejceCzekaj
succeededPrzetworzono, wynik dostępnyPobierz wynik
failedBłąd podczas przetwarzaniaPrzeczytaj komunikat, ponów próbę, jeśli warto
cancelledAnulowano, 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, /results zwraca wyniki, a /requests szczegóły żądań
  • Anulowanie (POST /v1/batches/{id}:cancel) jest nieodwracalne, ale zachowuje już wygenerowane wyniki
  • Listy i wyniki podlegają paginacji za pomocą limit i pagination_token
  • Odpytuj w odstępach kilku minut, z ustalonym maksymalnym czasem oczekiwania, i pobierz dane przed upływem expire_time