Przewodnik po formacie JSONL dla OpenAI Batch API

Naucz się strukturyzować pliki JSONL dla OpenAI Batch API, aby zaoszczędzić 50% kosztów

Ostatnia aktualizacja: luty 2026

Czym jest OpenAI Batch API?

OpenAI Batch API umożliwia wysyłanie dużych wolumenów żądań API jako pojedyncze zadanie wsadowe. Zamiast wykonywać tysiące indywidualnych wywołań API, przesyłasz plik JSONL zawierający wszystkie żądania, a OpenAI przetwarza je asynchronicznie w ciągu 24 godzin.

Kluczowa korzyść to koszt: żądania wsadowe są o 50% tańsze niż wywołania API w czasie rzeczywistym. To sprawia, że Batch API jest idealne do zadań nie wymagających natychmiastowych odpowiedzi, takich jak generowanie treści, klasyfikacja danych, obliczanie embeddingów i potoki ewaluacyjne.

Format żądania JSONL

Każda linia w pliku wejściowym JSONL batch reprezentuje jedno żądanie API. Każda linia musi zawierać trzy wymagane pola i spełniać określoną strukturę.

custom_idUnikalny identyfikator każdego żądania. Używany do dopasowywania żądań z odpowiedziami. Może być dowolnym ciągiem znaków do 512 znaków.
methodMetoda HTTP. Obecnie obsługiwana jest tylko metoda POST.
urlŚcieżka endpointu API. Dla chat completions: /v1/chat/completions. Dla embeddingów: /v1/embeddings.
bodyTreść żądania. Ten sam format co treść żądania odpowiedniego endpointu API.
Podstawowa struktura żądania
{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}

Batch Chat Completions

Najczęstszym przypadkiem użycia Batch API jest wysyłanie wielu żądań chat completion. Każda linia zawiera pełne żądanie z modelem, wiadomościami i opcjonalnymi parametrami takimi jak max_tokens czy temperature.

Pojedyncze żądanie

Każda linia zawiera kompletne żądanie chat completion z modelem, wiadomościami i opcjonalnymi parametrami.

Pojedyncze żądanie
{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the benefits of renewable energy."}], "max_tokens": 500}}

Plik JSONL z wieloma żądaniami

Plik wsadowy zazwyczaj zawiera setki lub tysiące żądań. Oto plik z trzema różnymi zadaniami: podsumowaniem, klasyfikacją i tłumaczeniem.

Plik JSONL z wieloma żądaniami
{"custom_id": "summary-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Summarize: Solar energy is a renewable source of power that harnesses sunlight using photovoltaic cells."}], "max_tokens": 200}}
{"custom_id": "classify-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Classify this review as positive or negative: Great product, works perfectly!"}], "max_tokens": 50}}
{"custom_id": "translate-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Translate to French: Hello, how are you today?"}], "max_tokens": 100}}

Batch Embeddings

Batch API obsługuje również żądania embeddingów, co jest przydatne do przetwarzania dużych kolekcji dokumentów. Batch embeddingów używa tej samej struktury JSONL, ale kieruje żądania do endpointu /v1/embeddings.

Żądania embeddingów używają prostszej struktury body z modelem i tekstem wejściowym.

Format żądania embeddingów
{"custom_id": "embed-001", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL is a text format for storing structured data."}}
{"custom_id": "embed-002", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "Each line contains one valid JSON object."}}
{"custom_id": "embed-003", "method": "POST", "url": "/v1/embeddings", "body": {"model": "text-embedding-3-small", "input": "JSONL files use the .jsonl extension."}}

Format odpowiedzi

Po zakończeniu zadania wsadowego OpenAI udostępnia wyjściowy plik JSONL, w którym każda linia zawiera odpowiedź na jedno żądanie. Odpowiedź zawiera oryginalny custom_id, dzięki czemu można dopasować odpowiedzi do żądań.

Pomyślna odpowiedź

Pomyślna odpowiedź zawiera custom_id, kod statusu odpowiedzi i pełną treść odpowiedzi API.

Pomyślna odpowiedź
{"id": "batch_req_abc123", "custom_id": "task-001", "response": {"status_code": 200, "body": {"id": "chatcmpl-xyz", "object": "chat.completion", "choices": [{"index": 0, "message": {"role": "assistant", "content": "Renewable energy provides numerous benefits including reduced greenhouse gas emissions, lower long-term costs, and energy independence."}}]}}, "error": null}

Odpowiedź z błędem

Nieudane żądania zawierają obiekt error z kodem i komunikatem wyjaśniającym, co poszło nie tak.

Odpowiedź z błędem
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}

Kompletny przepływ pracy Batch API

Oto kompletny pięcioetapowy przepływ pracy korzystania z Batch API z Python SDK, od tworzenia pliku JSONL po pobieranie i parsowanie wyników.

  1. 1Utwórz plik JSONL z jednym żądaniem na linię
  2. 2Prześlij plik za pomocą Files API z parametrem purpose ustawionym na batch
  3. 3Utwórz zadanie wsadowe odwołujące się do identyfikatora przesłanego pliku
  4. 4Sprawdzaj status zadania, aż osiągnie stan completed, failed lub cancelled
  5. 5Pobierz i sparsuj wyjściowy plik JSONL, aby wyodrębnić wyniki
Python — Batch API Workflow
from openai import OpenAI
import json
import time
client = OpenAI()
# Step 1: Create the JSONL batch file
prompts = [
"Summarize the benefits of renewable energy.",
"Classify this text as positive or negative: Great product!",
"Translate to French: Hello, how are you?",
]
requests = [
{
"custom_id": f"req-{i}",
"method": "POST",
"url": "/v1/chat/completions",
"body": {
"model": "gpt-4o-mini",
"messages": [{"role": "user", "content": prompt}],
"max_tokens": 200,
},
}
for i, prompt in enumerate(prompts)
]
with open("batch_input.jsonl", "w") as f:
for req in requests:
f.write(json.dumps(req) + "\n")
# Step 2: Upload the file
batch_file = client.files.create(
file=open("batch_input.jsonl", "rb"),
purpose="batch",
)
# Step 3: Create the batch
batch = client.batches.create(
input_file_id=batch_file.id,
endpoint="/v1/chat/completions",
completion_window="24h",
)
print(f"Batch created: {batch.id}")
# Step 4: Poll for completion
while True:
status = client.batches.retrieve(batch.id)
print(f"Status: {status.status}")
if status.status in ("completed", "failed", "cancelled"):
break
time.sleep(60)
# Step 5: Download results
if status.output_file_id:
content = client.files.content(status.output_file_id)
with open("batch_output.jsonl", "wb") as f:
f.write(content.read())

Batch API vs API czasu rzeczywistego

Zrozumienie, kiedy używać Batch API zamiast standardowego API czasu rzeczywistego, pomaga zoptymalizować zarówno koszty, jak i wydajność.

Funkcja
Batch API
API czasu rzeczywistego
Koszt
50% zniżki
Standardowa cena
Opóźnienie
Do 24 godzin
Sekundy
Limity częstotliwości
Wyższe limity
Standardowe limity
Format wejściowy
Przesyłanie pliku JSONL
Indywidualne wywołania API
Najlepsze dla
Przetwarzanie masowe, ewaluacja, generowanie danych
Aplikacje interaktywne, czat w czasie rzeczywistym, strumieniowanie

Aby poznać szczegóły formatu JSONL do fine-tuningu OpenAI, zobacz nasz Przewodnik po formacie JSONL OpenAI.

Przygotuj pliki wsadowe

Użyj naszych bezpłatnych narzędzi do tworzenia, walidacji i inspekcji plików JSONL wsadowych przed przesłaniem do OpenAI.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL do 1GB bezpośrednio w przeglądarce. Bez przesyłania, 100% prywatności.

Najczęściej zadawane pytania

Format JSONL OpenAI Batch API — żądania, odpowiedzi i lim...