Autor: Jerry Fan

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.

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.

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.
Podstawowa struktura żądania
{"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.

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 do przetwarzania wsadowego zwykle zawiera setki lub tysiące żądań. Poniższy plik zawiera trzy różne zadania: streszczanie, klasyfikację i tłumaczenie.

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}}

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.

Format żądań obliczania 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 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.

Odpowiedź na poprawnie wykonane żądanie
{"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ę.

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."}}

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.

  1. 1Utwórz plik JSONL z jednym żądaniem w każdej linii
  2. 2Prześlij plik przez Files API, ustawiając parametr purpose na batch
  3. 3Utwórz zadanie wsadowe, podając identyfikator przesłanego pliku
  4. 4Sprawdzaj okresowo status zadania, aż przyjmie wartość completed, failed lub cancelled
  5. 5Pobierz i sparsuj plik wynikowy JSONL, aby odczytać wyniki
Korzystanie z Batch API krok po kroku
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ść.

Cecha
Batch API
API w czasie rzeczywistym
Koszt
Rabat 50%
Standardowe ceny
Czas oczekiwania na odpowiedź
Do 24 godzin
Sekundy
Limity liczby żądań
Wyższe limity
Standardowe limity
Format wejściowy
Przesyłanie pliku JSONL
Pojedyncze wywołania API
Najlepsze zastosowania
Przetwarzanie masowe, ewaluacja, generowanie danych
Aplikacje interaktywne, czat w czasie rzeczywistym, strumieniowanie

Więcej o formacie JSONL do fine-tuningu modeli OpenAI znajdziesz w naszym poradniku: Przewodnik po formacie JSONL dla OpenAI.

Pracuj z plikami JSONL online

Przeglądaj, waliduj i konwertuj pliki JSONL o rozmiarze do 1GB bezpośrednio w przeglądarce. Bez wysyłania plików na serwer, ze 100% prywatnością.

Najczęściej zadawane pytania

Źródła