Batch API: Przetwarzanie asynchroniczne na dużą skalę
Na tej stronie
Zaktualizowano 3 listopada 2026 na podstawie przewodnika Batch API oraz struktury odpowiedzi Responses API: odczyt wyników nie zakłada już, że pierwszy element
outputto wiadomość (może go poprzedzać element rozumowania), a klucz kodu błędu zapisany bez cudzysłowu powodował błądNameError. Ź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_iddla każdego żądania - Zaplanuj mechanizm ponawiania dla nieudanych żądań
- Połącz z buforowaniem promptów, aby zmaksymalizować oszczędności