Przejdź do głównej treści
Polski— Wybierz język
Menu

Format JSONL i przesyłanie przez Files API

Lekcja 6 z 12 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Przetwarzanie wsadowe z użyciem JSONL
  2. Struktura pliku JSONL
  3. Generowanie pliku JSONL w Pythonie
  4. Przesyłanie przez Files API
  5. Tworzenie wsadu na podstawie pliku
  6. Ograniczenia formatu JSONL
  7. Generowanie pliku JSONL w JavaScript
  8. Walidacja i debugowanie
  9. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 r. na podstawie dokumentacji xAI: rabat na wsady (batch) wynosi 20% dla kwalifikujących się modeli tekstowych (a nie 50%), przykłady odnoszą się do REST API oraz oficjalnego xai-sdk (client.batch.*; Batch API od xAI nie używa formatu OpenAI, więc SDK OpenAI nie ma zastosowania), a Responses API ma pierwszeństwo przed Chat Completions, które są przestarzałym punktem końcowym w xAI. Źródła: Batch API · Referencje REST · Cennik Batch.

Przetwarzanie wsadowe z użyciem JSONL

W przypadku dużych wolumenów danych przygotowanych wcześniej, plik JSONL jest najprostszą drogą. Zapisujesz wszystkie swoje żądania w pliku, przesyłasz go przez Files API, a następnie tworzysz wsad na podstawie tego pliku. Pojedynczy plik może zawierać do 50 000 żądań.

Struktura pliku JSONL

Plik JSONL (JSON Lines) zawiera jeden obiekt JSON w każdej linii. Każda linia reprezentuje kompletne żądanie z czterema polami:

{"custom_id": "req-1", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Summarize this text in one sentence: ..."}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": [{"role": "user", "content": "Classify this ticket: bug, feature, or question. ..."}]}}
{"custom_id": "req-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "grok-4.3", "messages": [{"role": "user", "content": "Translate into English: ..."}]}}
  • custom_id: unikalny identyfikator w obrębie pliku; staje się batch_request_id w wynikach
  • method: zawsze "POST"
  • url: docelowy punkt końcowy, jeden z siedmiu akceptowanych
  • body: treść żądania, zgodna z referencjami API dla danego punktu końcowego

Każda linia musi być poprawnym, samowystarczalnym kodem JSON: bez przecinków rozdzielających, bez nawiasów zamykających całość. Punkty końcowe mogą być mieszane w tym samym pliku; każde żądanie jest routowane niezależnie.

Generowanie pliku JSONL w Pythonie

import json

documents = [
    {"id": "doc-001", "text": "First article to summarize..."},
    {"id": "doc-002", "text": "Second article to summarize..."},
    # ... do 50 000 dokumentów na plik
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Summarize in three sentences."},
                    {"role": "user", "content": doc["text"]},
                ],
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

Przesyłanie przez Files API

Przesyłasz plik przez punkt końcowy /v1/files, bez żadnych innych parametrów:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl"

Z użyciem Python SDK:

from xai_sdk import Client

client = Client()

with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")
print(f"Uploaded file: {fichier.id}")

Tworzenie wsadu na podstawie pliku

Plik nie jest dodawany do istniejącego wsadu: wskazujesz go w momencie tworzenia, używając input_file_id:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "article_summaries", "input_file_id": "file-abc123"}'
batch = client.batch.create(batch_name="article_summaries", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")

Plik jest następnie odczytywany w tle. Jeśli nawet jedna linia jest nieprawidłowa, wsad zostaje anulowany z komunikatem o błędzie. Śledzenie i pobieranie wyników działa dokładnie tak samo jak w przypadku wsadu przesłanego bezpośrednio przez API.

Ograniczenia formatu JSONL

  • Maksymalnie 50 000 żądań na plik
  • Maksymalnie 200 MB na plik
  • Unikalne custom_id dla każdej linii
  • Wsad utworzony z pliku jest zapieczętowany: nie możesz dodać do niego później danych przez API

Jeśli Twój wsad przekracza te limity, podziel go na wiele plików i utwórz jeden wsad na plik. Nie ma limitu liczby wsadów na zespół.

Generowanie pliku JSONL w JavaScript

import fs from "fs";

const documents = [
  { id: "doc-001", text: "First article..." },
  { id: "doc-002", text: "Second article..." },
];

const lines = documents.map(doc => JSON.stringify({
  custom_id: doc.id,
  method: "POST",
  url: "/v1/responses",
  body: {
    model: "grok-4.3",
    input: [
      { role: "user", content: `Summarize: ${doc.text}` }
    ]
  }
}));

fs.writeFileSync("batch_requests.jsonl", lines.join("\n") + "\n");

Walidacja i debugowanie

Jedna nieprawidłowa linia anuluje cały wsad: zwaliduj plik przed jego przesłaniem. Prosty skrypt pokrywa podstawowe aspekty:

import json
import os

ENDPOINTS = {
    "/v1/responses", "/v1/chat/completions",
    "/v1/images/generations", "/v1/images/edits",
    "/v1/videos/generations", "/v1/videos", "/v1/videos/edits", "/v1/videos/extensions",
}

def valider_jsonl(chemin: str) -> list[str]:
    erreurs, ids = [], set()
    if os.path.getsize(chemin) > 200 * 1024 * 1024:
        erreurs.append("file larger than 200 MB")
    with open(chemin, encoding="utf-8") as f:
        for i, ligne in enumerate(f, 1):
            try:
                obj = json.loads(ligne)
            except json.JSONDecodeError as e:
                erreurs.append(f"line {i}: invalid JSON ({e})")
                continue
            cid = obj.get("custom_id")
            if not cid or cid in ids:
                erreurs.append(f"line {i}: missing or duplicate custom_id")
            ids.add(cid)
            if obj.get("method") != "POST" or obj.get("url") not in ENDPOINTS:
                erreurs.append(f"line {i}: invalid method or url")
            if not isinstance(obj.get("body"), dict):
                erreurs.append(f"line {i}: missing body")
    if len(ids) > 50_000:
        erreurs.append("more than 50,000 requests")
    return erreurs

print(valider_jsonl("batch_requests.jsonl") or "File is valid")

Kluczowe wnioski

  • Format JSONL zawiera jeden obiekt JSON w każdej linii: custom_id, method, url, body
  • Przesyłasz plik przez /v1/files, a następnie wskazujesz go podczas tworzenia wsadu (input_file_id)
  • Maksymalnie 50 000 żądań i 200 MB na plik; powyżej tych limitów tworzy się jeden wsad na plik
  • Wsad utworzony z pliku jest zapieczętowany, a jedna nieprawidłowa linia anuluje go w całości
  • Zweryfikuj plik przed przesłaniem