Kompleksowy potok end-to-end
Na tej stronie
Kurs zaktualizowany 2 listopada 2026 r. na podstawie dokumentacji xAI: rabat na wsady (batch) wynosi 20% dla kwalifikujących się modeli tekstowych (a nie 50%), przykłady korzystają z interfejsu REST oraz oficjalnego
xai-sdk(client.batch.*; interfejs Batch API xAI nie odpowiada formatowi 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.
Łączenie elementów
Poprzednie lekcje omawiały każdy krok osobno. Ta lekcja scala je w kompletny potok – od przygotowania danych po przetworzenie wyników. Na końcu otrzymasz skrypt, który dostosujesz do swojego przypadku użycia.
Kompleksowy potok w Pythonie
import json
import time
from xai_sdk import Client
client = Client() # klucz odczytany z XAI_API_KEY
# --- Krok 1: przygotowanie danych ---
documents = [
{"id": f"doc-{i}", "text": f"Tresc dokumentu {i}..."}
for i in range(100)
]
# --- Krok 2: zapis pliku JSONL ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
ligne = {
"custom_id": doc["id"],
"method": "POST",
"url": "/v1/responses",
"body": {
"model": "grok-4.3",
"input": [
{"role": "system", "content": "Stresc w dwoch zdaniach."},
{"role": "user", "content": doc["text"]},
],
"max_output_tokens": 200,
},
}
f.write(json.dumps(ligne, ensure_ascii=False) + "\n")
# --- Krok 3: przesłanie pliku ---
with open("batch_requests.jsonl", "rb") as f:
fichier = client.files.upload(f, filename="batch_requests.jsonl")
# --- Krok 4: utworzenie wsadu z pliku (jest teraz zamknięty) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Utworzono wsad: {batch.batch_id}")
# --- Krok 5: oczekiwanie na zakończenie przetwarzania ---
while True:
batch = client.batch.get(batch_id=batch.batch_id)
etat = batch.state
if batch.cancel_by_xai_message:
raise RuntimeError(f"Wsad anulowany przez xAI: {batch.cancel_by_xai_message}")
if etat.num_requests > 0 and etat.num_pending == 0:
break
print(f"{etat.num_success + etat.num_error}/{etat.num_requests} przetworzonych żądań")
time.sleep(300) # co 5 minut
# --- Krok 6: pobieranie wyników, strona po stronie ---
resultats, echecs = {}, []
jeton = None
while True:
page = client.batch.list_batch_results(
batch_id=batch.batch_id, limit=100, pagination_token=jeton
)
for r in page.succeeded:
resultats[r.batch_request_id] = r.response.content
echecs.extend(page.failed)
if page.pagination_token is None:
break
jeton = page.pagination_token
with open("batch_results.json", "w", encoding="utf-8") as f:
json.dump(resultats, f, ensure_ascii=False, indent=2)
print(f"{len(resultats)} wyników, {len(echecs)} niepowodzeń")
print("Całkowity koszt: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))
Trzy szczegóły mają kluczowe znaczenie. Warunek zatrzymania wymaga num_requests > 0, ponieważ wsad utworzony z pliku jest odczytywany w tle: zaraz po utworzeniu jego liczniki mogą wciąż wynosić zero. Pole cancel_by_xai_message sygnalizuje anulowanie przez xAI, na przykład z powodu nieprawidłowego wiersza. Koszt wyrażony jest w tickach, czyli dziesięciomiliardowych częściach dolara.
Potok cURL krok po kroku
Jeśli wolisz wiersz poleceń, oto odpowiednik w cURL (używający jq do odczytu odpowiedzi):
# 1. Przesłanie pliku JSONL
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
-H "Authorization: Bearer $XAI_API_KEY" \
-F file="@batch_requests.jsonl" | jq -r '.id')
echo "Plik: $FILE_ID"
# 2. Utworzenie wsadu z pliku
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Wsad: $BATCH_ID"
# 3. Odczyt liczników
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
-H "Authorization: Bearer $XAI_API_KEY" | jq '.state'
# 4. Pobranie pierwszej strony wyników
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
-H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json
Kolejne strony pobierasz, dodając &pagination_token=… z wartością zwróconą przez poprzednią stronę.
Obsługa błędów w środowisku produkcyjnym
Solidny potok rozróżnia trzy rodziny błędów:
Błędy przesyłania: nieudane przesłanie pliku lub utworzenie wsadu. Błędy przejściowe (limit czasu, limit częstotliwości, błąd serwera) należy ponawiać z rosnącym opóźnieniem: 1 s, 2 s, 4 s, 8 s.
Błędy przetwarzania: niektóre żądania wewnątrz wsadu kończą się niepowodzeniem. Pojawiają się one w page.failed wraz z komunikatem; należy je ponownie przesłać – i tylko je – w nowym wsadzie.
Limit czasu i wygaśnięcie: okno 24 godzin jest orientacyjne, a nie gwarantowane. Bezwzględny jest termin wygaśnięcia (expire_time): po tym momencie wyniki stają się niedostępne. Pobieraj je na bieżąco, zamiast czekać na wszystkie naraz na samym końcu.
# Nieudane żądania: zidentyfikuj je, aby ponownie przesłać w nowym wsadzie
for r in echecs:
print(f"Niepowodzenie: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}
Optymalizacja kosztów
Oszczędności kumulują się dzięki czterem dźwigniom. Wybór modelu jest najważniejszy i najpotężniejszy: według stawek standardowych z 2 listopada 2026 r. grok-4.3 kosztuje 1,25 USD za milion tokenów wejściowych i 2,50 USD za wyjściowe, podczas gdy grok-4.7 to odpowiednio 2 USD i 6 USD (dla promptów poniżej 200 000 tokenów). Do klasyfikacji lub krótkiej ekstrakcji często wystarczy lżejszy model, a rabat 20% na wsady dotyczy obu. Długość odpowiedzi jest kolejna: max_output_tokens zapobiega płaceniu za niepotrzebnie długie wyjścia – do klasyfikacji wystarczy kilka tokenów. Prompty: usunięcie dziesięciu tokenów z promptu powtórzonego 50 000 razy oszczędza 500 000 tokenów wejściowych. Wreszcie pamięć podręczna (cache): xAI automatycznie buforuje identyczne początki żądań, a rabat na wsady dotyczy również tokenów obsługiwanych z cache; dlatego umieszczaj wspólne instrukcje na początku każdego żądania, przed częścią zmienną.
Kluczowe wnioski
- Kompletny potok obejmuje sześć kroków: przygotowanie, JSONL, przesłanie, utworzenie, monitorowanie, pobieranie
- Wsad z pliku jest odczytywany w tle: poczekaj, aż
num_requests > 0, zanim uznasz go za zakończony - Obsługuj trzy rodziny błędów: przesyłania, przetwarzania, limitu czasu i wygaśnięcia
- Pobieraj i zapisuj wyniki na bieżąco, przed upływem
expire_time - Wybór modelu, długość wyjścia, krótkie prompty i wspólne prefiksy maksymalizują oszczędności