- Strona główna
- Przewodnik
- Przewodnik po formacie JSONL dla OpenAI Batch API
Przewodnik po formacie JSONL dla OpenAI Batch API
Dowiedz się, jak przygotować pliki JSONL dla OpenAI Batch API i obniżyć koszty o 50%
Czym jest OpenAI Batch API?
OpenAI Batch API pozwala wysłać dużą liczbę żądań API w ramach jednego zadania wsadowego. Zamiast wykonywać tysiące osobnych wywołań API, przesyłasz plik JSONL ze wszystkimi żądaniami, a OpenAI przetwarza je asynchronicznie w ciągu 24 godzin.
Główną zaletą są niższe koszty: żądania przetwarzane wsadowo są o 50% tańsze od wywołań API w czasie rzeczywistym. Batch API świetnie sprawdza się więc w zadaniach, które nie wymagają natychmiastowej odpowiedzi, takich jak generowanie treści, klasyfikacja danych, obliczanie embeddingów czy procesy ewaluacji.
Format żądań w pliku JSONL
Każda linia wejściowego pliku JSONL zawiera jedno żądanie API. Musi ono mieć trzy wymagane pola i określoną strukturę.
custom_id — Unikalny identyfikator żądania. Służy do przyporządkowania odpowiedzi do żądania. Może to być dowolny ciąg o długości 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 w takim samym formacie, jakiego wymaga dany endpoint API.{"custom_id": "req-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}}Wsadowe żądania Chat Completions
Batch API najczęściej służy do wysyłania wielu żądań do Chat Completions. 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 pełne żądanie do Chat Completions 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 do przetwarzania wsadowego zwykle zawiera setki lub tysiące żądań. Poniższy plik zawiera trzy różne zadania: streszczanie, klasyfikację i tłumaczenie.
{"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}}Wsadowe obliczanie embeddingów
Batch API obsługuje też żądania obliczania embeddingów, co przydaje się przy przetwarzaniu dużych zbiorów dokumentów. Takie zadania wsadowe korzystają z tej samej struktury JSONL, ale żądania są kierowane do endpointu /v1/embeddings.
Żądania obliczania embeddingów mają prostszą treść: zawierają model i tekst wejściowy.
{"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 plik wynikowy JSONL. Każda jego linia zawiera odpowiedź na jedno żądanie. W odpowiedzi znajduje się pierwotny identyfikator custom_id, dzięki któremu możesz przyporządkować ją do żądania.
Odpowiedź na poprawnie wykonane żądanie
Odpowiedź na poprawnie wykonane żądanie zawiera custom_id, kod statusu odpowiedzi oraz 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
Jeśli żądanie zakończy się błędem, odpowiedź zawiera obiekt error z kodem błędu i komunikatem wyjaśniającym jego przyczynę.
{"id": "batch_req_def456", "custom_id": "task-002", "response": null, "error": {"code": "invalid_request_error", "message": "The model 'gpt-5' does not exist."}}Korzystanie z Batch API krok po kroku
Poniżej znajdziesz cały proces korzystania z Batch API za pomocą SDK dla Pythona w pięciu krokach: od utworzenia pliku JSONL po pobranie i parsowanie wyników.
- 1Utwórz plik JSONL z jednym żądaniem w każdej linii
- 2Prześlij plik przez Files API, ustawiając parametr purpose na batch
- 3Utwórz zadanie wsadowe, podając identyfikator przesłanego pliku
- 4Sprawdzaj okresowo status zadania, aż przyjmie wartość completed, failed lub cancelled
- 5Pobierz i sparsuj plik wynikowy JSONL, aby odczytać wyniki
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 a API działające w czasie rzeczywistym
Wybór między Batch API a standardowym API działającym w czasie rzeczywistym pozwala zoptymalizować zarówno koszty, jak i wydajność.
Więcej o formacie JSONL do fine-tuningu modeli OpenAI znajdziesz w naszym poradniku: Przewodnik po formacie JSONL dla OpenAI.
Przygotuj pliki wsadowe
Skorzystaj z naszych bezpłatnych narzędzi, aby utworzyć pliki JSONL do przetwarzania wsadowego, zweryfikować ich poprawność i przejrzeć zawartość przed wysłaniem do OpenAI.
Pełny przewodnik po przygotowywaniu plików JSONL dla OpenAI. Poznaj format danych do fine-tuningu, żądania Batch API, typowe błędy i wskazówki dotyczące walidacji.
Podziel duze pliki JSONL na mniejsze, latwiejsze do zarzadzania czesci wedlug liczby wierszy.
Waliduj pliki JSONL linia po linii. Od razu wykrywaj błędy składni, problemy z kodowaniem i niezgodności z formatem.
Sposoby przetwarzania gigabajtów danych JSONL: odczyt strumieniowy, zarządzanie pamięcią, dzielenie plików, kompresja i narzędzia online.
Dowiedz się, jak przygotować dane treningowe JSONL do fine-tuningu modeli AI/ML. Poznaj formaty zbiorów danych OpenAI, Anthropic Claude i HuggingFace, ich walidację oraz pipeline’y przygotowywania danych.