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

Batch API: Przetwarzanie asynchroniczne na dużą skalę

Lekcja 6 z 20 Zaktualizowano 3 listopada 2026 Zaawansowany
Na tej stronie
  1. Wymień opóźnienie na koszt
  2. Budowanie i uruchamianie partii (Batch)
  3. Zaplanuj częściowe awarie
  4. Mnożenie oszczędności
  5. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 na podstawie przewodnika Batch API oraz struktury odpowiedzi Responses API: odczyt wyników nie zakłada już, że pierwszy element output to wiadomość (może go poprzedzać element rozumowania), a klucz kodu błędu zapisany bez cudzysłowu powodował błąd NameError. Źródło: Batch API.

Wymień opóźnienie na koszt

Batch API działa na prostej zasadzie rynkowej: akceptujesz, że Twoje żądania zostaną przetworzone asynchronicznie w oknie czasowym do dwudziestu czterech godzin, a w zamian płacisz o pięćdziesiąt procent mniej. Wszystko, co nie musi obsługiwać człowieka czekającego przed ekranem, wpada do tej kategorii. Na dużą skalę nie jest to mikrooptymalizacja; to przecięcie linii budżetowej na pół.

Nawykiem, który warto wypracować w zespole, jest zadawanie przy każdym nowym zadaniu przetwarzania pytania, czy ktoś czeka na wynik. Analiza zasobu umów, generowanie kart produktowych do katalogu, uruchamianie benchmarków na tysiącach przypadków testowych, klasyfikacja półrocznego zaległości zgłoszeń, ekstrakcja pól z partii faktur: we wszystkich tych przypadkach odpowiedź ląduje w panelu sterowania lub bazie danych, a nie w interfejsie konwersacyjnym. Opóźnienie jest niewidoczne, ale oszczędności – nie.

Budowanie i uruchamianie partii (Batch)

Format wejściowy to plik JSONL: jedna linia na żądanie, gdzie każda linia jest kompletnym, niezależnym obiektem. Pole custom_id pozwala powiązać każdą odpowiedź z oryginalnym żądaniem, ponieważ nic nie gwarantuje kolejności w pliku wyjściowym. Wybierz ID, które jest stabilne i znaczące – identyfikator dokumentu z Twojej bazy danych, a nie numer iteracji – inaczej faza uzgadniania danych zamieni się w koszmar.

import json

requests = [
    {
        "custom_id": f"doc-{i}",
        "method": "POST",
        "url": "/v1/responses",
        "body": {
            "model": "gpt-5.6-luna",
            "input": f"Summarize this document in 3 key points: {doc}",
            "max_output_tokens": 500,
        },
    }
    for i, doc in enumerate(documents_list)
]

# Zapisz plik JSONL
with open("batch_input.jsonl", "w") as f:
    for request in requests:
        f.write(json.dumps(request) + "\n")

Następnie plik jest przesyłany i referencjonowany podczas tworzenia partii. Metadane nie służą żadnemu celowi technicznemu, ale uratują Ci skórę, gdy trzy partie będą działać równolegle i będziesz musiał ustalić, która odpowiada której wersji promptu.

import openai

client = openai.OpenAI()

# Prześlij plik
file_obj = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

# Utwórz partię
batch = client.batches.create(
    input_file_id=file_obj.id,
    endpoint="/v1/responses",
    completion_window="24h",
    metadata={"project": "contract-analysis", "version": "2.1"},
)

print(f"Batch created: {batch.id}")
print(f"Status: {batch.status}")

Monitorowanie polega na odpytywaniu stanu partii, dopóki nie wyjdzie ze stanu „w toku“, a następnie pobraniu pliku wyjściowego, który również ma format JSONL. Poniższa pętla rozróżnia trzy wyniki końcowe – failed, expired, cancelled – i dla każdego zgłasza wyjątek: wygasła partia to taka, w której okno dwudziestu czterech godzin upłynęło przed zakończeniem przetwarzania wszystkiego, a traktowanie tego jako cichego, częściowego sukcesu byłoby najgorszym rozwiązaniem.

import time

def wait_for_batch(batch_id: str, interval: int = 60) -> list:
    """Czeka na zakończenie partii i zwraca wyniki."""
    while True:
        batch = client.batches.retrieve(batch_id)
        print(
            f"Status: {batch.status} | "
            f"Completed: {batch.request_counts.completed}/"
            f"{batch.request_counts.total} | "
            f"Failed: {batch.request_counts.failed}"
        )

        if batch.status == "completed":
            break
        elif batch.status in ("failed", "expired", "cancelled"):
            raise RuntimeError(f"Batch failed: {batch.status}")

        time.sleep(interval)

    # Pobierz wyniki
    content = client.files.content(batch.output_file_id)
    results = []
    for line in content.text.strip().split("\n"):
        results.append(json.loads(line))

    return results


results = wait_for_batch(batch.id)

# Przetwórz wyniki
for result in results:
    custom_id = result["custom_id"]
    response = result["response"]
    if response["status_code"] == 200:
        # output może zawierać inne elementy przed wiadomością
        # (np. rozumowanie): szukaj tekstu wiadomości
        text = next(
            part["text"]
            for item in response["body"]["output"] if item["type"] == "message"
            for part in item["content"] if part["type"] == "output_text"
        )
        print(f"{custom_id}: {text[:100]}...")
    else:
        print(f"{custom_id}: ERROR {response['status_code']}")

Zaplanuj częściowe awarie

W dużej partii niektóre żądania ulegną niepowodzeniu: ucięty dokument, przekroczenie kontekstu lub przejściowy błąd po stronie serwera. Partia nigdy nie jest więc po prostu „udana“ lub „nieudana“ – jest częściowo udana i musisz umieć wyizolować brakującą część. Wzorzec do przyjęcia polega na natychmiastowym oddzieleniu sukcesów od porażek i wygenerowaniu pliku JSONL gotowego do ponownego uruchomienia, zamiast grzebania w logach trzy dni później, aby odtworzyć braki.

def handle_batch_errors(results: list[dict]) -> tuple[list, list]:
    """Rozdziela sukcesy od porażek w celu ponownego przetworzenia."""
    successes = []
    failures = []

    for r in results:
        if r["response"]["status_code"] == 200:
            successes.append(r)
        else:
            failures.append(r)

    if failures:
        print(f"Warning: {len(failures)} failed requests out of {len(results)}")
        # Przypisz plik JSONL z nieudanymi żądaniami do ponownej próby
        with open("batch_retry.jsonl", "w") as f:
            for failure in failures:
                original_request = {
                    "custom_id": failure["custom_id"],
                    "method": "POST",
                    "url": "/v1/responses",
                    "body": failure["request"]["body"],
                }
                f.write(json.dumps(original_request) + "\n")

    return successes, failures

Mnożenie oszczędności

Przy przetwarzaniu dziesięciu tysięcy dokumentów za pomocą GPT-5.6 Luna, synchroniczne API stanowi koszt bazowy, Batch API to połowa tej kwoty, a buforowanie promptów (prompt caching) dodaje kolejne oszczędności, ponieważ tokeny z cache również korzystają z własnej redukcji. Te dwa mechanizmy nie konkurują ze sobą: jeśli Twoje dziesięć tysięcy żądań współdzieli ten sam długi prompt systemowy, ustrukturyzuj go jako stabilny prefiks, a pomnożysz oba efekty.

Pozostaje jeszcze kwestia dzielenia. Partia nie powinna być nieskończona, a wygodniej jest monitorować kilka zarządzalnych partii niż jeden monolit, którego awaria kosztuje cały dzień. Poniższa funkcja dzieli listę żądań na partie o ograniczonym rozmiarze.

def create_optimized_batches(
    requests: list[dict],
    max_size: int = 50_000,
) -> list[list[dict]]:
    """Dzieli na partie o optymalnym rozmiarze."""
    batches = []
    current_batch = []

    for request in requests:
        current_batch.append(request)
        if len(current_batch) >= max_size:
            batches.append(current_batch)
            current_batch = []

    if current_batch:
        batches.append(current_batch)

    return batches

Kluczowe wnioski

  • Batch API oferuje redukcję kosztów o 50% dla przetwarzania nie wymagającego czasu rzeczywistego
  • Przygotuj żądania w pliku JSONL z unikalnym custom_id dla każdego żądania
  • Zaplanuj mechanizm ponawiania dla nieudanych żądań
  • Połącz z buforowaniem promptów, aby zmaksymalizować oszczędności