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

Kompleksowy potok end-to-end

Lekcja 7 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Łączenie elementów
  2. Kompleksowy potok w Pythonie
  3. Potok cURL krok po kroku
  4. Obsługa błędów w środowisku produkcyjnym
  5. Optymalizacja kosztów
  6. Kluczowe wnioski

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