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_id — Unikalny identyfikator każdego żądania. Używany do dopasowywania żądań z odpowiedziami. Może być dowolnym ciągiem znaków do 512 znaków.method — Metoda HTTP. Obecnie obsługiwana jest tylko metoda POST.url — Ścieżka endpointu API. Dla chat completions: /v1/chat/completions. Dla embeddingów: /v1/embeddings.body — Treść żądania. Ten sam format co treść żądania odpowiedniego endpointu API.{"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.
{"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.
{"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.
{"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.
{"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.
{"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.
- 1Utwórz plik JSONL z jednym żądaniem na linię
- 2Prześlij plik za pomocą Files API z parametrem purpose ustawionym na batch
- 3Utwórz zadanie wsadowe odwołujące się do identyfikatora przesłanego pliku
- 4Sprawdzaj status zadania, aż osiągnie stan completed, failed lub cancelled
- 5Pobierz i sparsuj wyjściowy plik JSONL, aby wyodrębnić wyniki
from openai import OpenAIimport jsonimport timeclient = OpenAI()# Step 1: Create the JSONL batch fileprompts = ["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 filebatch_file = client.files.create(file=open("batch_input.jsonl", "rb"),purpose="batch",)# Step 3: Create the batchbatch = 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 completionwhile True:status = client.batches.retrieve(batch.id)print(f"Status: {status.status}")if status.status in ("completed", "failed", "cancelled"):breaktime.sleep(60)# Step 5: Download resultsif 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ść.
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.