Format JSONL, custom_id i przesyłanie plików
Na tej stronie
Zaktualizowano 3 listopada 2026: W SDK
mistralaiw wersji 3.7.0 metodafiles.uploadoczekuje argumentufile={"file_name": …, "content": …}(przekazanie krotki powoduje błądValidationErrorprzed wysłaniem jakichkolwiek danych), a rozmiar pliku jest dostępny w polusize_bytes.
Format JSONL: Kręgosłup wnioskowania wsadowego
JSONL (JSON Lines) to standardowy format używany przez Mistral do strukturyzowania żądań wsadowych. Każdy wiersz w pliku stanowi samodzielny obiekt JSON reprezentujący pojedyncze żądanie. Taki projekt nie jest przypadkowy: pozwala na strumieniowe generowanie pliku liczącego milion wierszy bez konieczności ładowania go w całości do pamięci, odczytywanie go linia po linii oraz ręczne inspekcjonowanie konkretnych wpisów w przypadku awarii żądania. W przeciwieństwie do pojedynczej, ogromnej tablicy JSON, która zmusza do załadowania całego pliku tylko po to, by zweryfikować jeden wpis, JSONL pozwala pracować na poziomie pojedynczych linii.
Struktura żądania JSONL
Każdy wiersz w pliku JSONL musi zawierać dwa wymagane pola:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Podsumuj ten dokument w 3 punktach."}
]
}
}
custom_id to unikalny identyfikator, który Ty definiujesz dla każdego żądania. To właśnie on sprawia, że wyniki są użyteczne. Mistral nie gwarantuje kolejności przetwarzania: plik wyjściowy może zaczynać się od żądania nr 8472. Bez custom_id otrzymasz stertę odpowiedzi bez możliwości ustalenia, któremu dokumentowi każda z nich odpowiada. Wyrobij sobie nawyk wyprowadzania tego ID z własnego systemu referencyjnego – np. doc-001, email-2024-03-15-042, product-sku-ABC123 – zamiast używania anonimowego licznika. Gdy odpowiedź spowoduje problemy, będziesz mógł ją prześledzić do źródła bez konieczności uruchamiania zapytania SQL. Obowiązują tu dwie praktyczne zasady: identyfikatory muszą być unikalne w obrębie pliku (w przeciwnym razie przetwarzanie zwróci błąd) i powinny być rozsądnie krótkie, ponieważ identyfikator liczący 200 znaków uczyni logi nieczytelnymi.
Pole body nie wymaga nowej wiedzy: zawiera dokładnie taką samą strukturę, jakiej użyłbyś w synchronicznym wywołaniu API do docelowego punktu końcowego. Jeśli celujesz w /v1/chat/completions, treść body jest identyczna z tą, którą przekazałbyś w wywołaniu client.chat.complete(). Prompt zwalidowany interaktywnie przekłada się bezpośrednio na zadanie wsadowe.
Programowe generowanie pliku JSONL w Pythonie
Oto sposób na programowe wygenerowanie pliku JSONL z listy dokumentów:
import json
documents = [
{"id": "doc-001", "text": "Sztuczna inteligencja zmienia..."},
{"id": "doc-002", "text": "Głębokie sieci neuronowe..."},
{"id": "doc-003", "text": "Przetwarzanie języka naturalnego..."},
]
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
for doc in documents:
request = {
"custom_id": doc["id"],
"body": {
"model": "mistral-small-latest",
"max_tokens": 200,
"messages": [
{
"role": "system",
"content": "Jesteś asystentem, który podsumowuje teksty."
},
{
"role": "user",
"content": f"Podsumuj ten tekst: {doc['text']}"
}
]
}
}
f.write(json.dumps(request, ensure_ascii=False) + "\n")
Zwróć uwagę na parametr ensure_ascii=False. Bez niego funkcja json.dumps zamienia znaki akcentowane na sekwencje \uXXXX. Plik pozostaje poprawny, ale staje się niemożliwy do odczytania przez człowieka, zamieniając wszelkie debugowanie na korpusie francuskim w ćwiczenie z deszyfracji. Uczyń to swoim domyślnym ustawieniem od pierwszej linii kodu.
Przesyłanie pliku do Mistral
W środowisku produkcyjnym przesyłaj plik przez API Pythona:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Prześlij plik JSONL
with open("batch_requests.jsonl", "rb") as f:
batch_file = client.files.upload(
file={"file_name": "batch_requests.jsonl", "content": f},
purpose="batch"
)
print(f"Przesłany plik: {batch_file.id}")
print(f"Rozmiar: {batch_file.size_bytes} bajtów")
print(f"Przeznaczenie: {batch_file.purpose}")
Parametr purpose="batch" informuje Mistral, że plik jest przeznaczony do przetwarzania wsadowego, a nie do innych funkcji, takich jak dostrajanie (fine-tuning) czy RAG. Ta deklaracja intencji dyktuje dalszy przebieg zdarzeń: plik przesłany z niewłaściwym przeznaczeniem zostanie odrzucony przez zadanie.
Do szybkiego testu lub dla zespołów nietechnicznych AI Studio oferuje tę samą usługę przez interfejs graficzny (GUI):
- Przejdź do
console.mistral.ai/build/files - Kliknij „Upload“ (Prześlij)
- Wybierz swój plik JSONL
- Wybierz przeznaczenie „Batch Processing“ (Przetwarzanie wsadowe)
Interfejs zwraca file_id, dokładnie tak jak API, i jest to identyfikator, którego używasz do utworzenia zadania wsadowego.
Walidacja pliku
Zadanie wsadowe liczące milion linii, które powiedzie się na linii 300 z powodu zduplikowanego custom_id, kosztuje Cię pełny czas oczekiwania na cykl przetwarzania. Kilka sekund lokalnej walidacji zapobiega tej stracie. Poniższy skrypt wykonuje pojedyncze przejście, sprawdzając poprawność JSON, obecność dwóch wymaganych pól oraz unikalność identyfikatorów:
import json
errors = []
seen_ids = set()
with open("batch_requests.jsonl", "r", encoding="utf-8") as f:
for line_num, line in enumerate(f, 1):
try:
data = json.loads(line)
except json.JSONDecodeError as e:
errors.append(f"Line {line_num}: Invalid JSON - {e}")
continue
# Sprawdź wymagane pola
if "custom_id" not in data:
errors.append(f"Line {line_num}: missing custom_id")
if "body" not in data:
errors.append(f"Line {line_num}: missing body")
# Sprawdź unikalność custom_id
cid = data.get("custom_id")
if cid in seen_ids:
errors.append(f"Line {line_num}: duplicate custom_id '{cid}'")
seen_ids.add(cid)
if errors:
print(f"{len(errors)} error(s) found:")
for e in errors:
print(f" - {e}")
else:
print(f"File valid: {len(seen_ids)} requests ready.")
Uczyń to systematycznym krokiem w swoim procesie przygotowań, wykonywanym tuż przed przesłaniem pliku.
Limity i ograniczenia
Przetwarzanie wsadowe plików jest ograniczone do miliona linii na plik, co oznacza, że większe korpusy musisz podzielić na wiele zgłoszeń. Kodowanie musi być w formacie UTF-8, a format ściśle wymaga jednego obiektu JSON na linię: obiekt JSON rozciągnięty na wiele linii, np. przez misplaced json.dumps(..., indent=2), łamie parsowanie po stronie serwera. Pamiętaj również o dwóch wcześniej wspomnianych zasadach, ponieważ ich naruszenie powoduje niepowodzenie zadania: custom_id musi być unikalne w obrębie pliku, a body musi odpowiadać schematowi docelowego punktu końcowego.
Kluczowe wnioski
- JSONL strukturyzuje Twoje żądania wsadowe, umieszczając jeden obiekt JSON na linię
- Każde żądanie wymaga unikalnego
custom_idorazbodyzgodnego ze schematem docelowego punktu końcowego - Przesyłaj plik przez API Pythona (
client.files.upload) lub za pośrednictwem AI Studio - Zawsze waliduj swój plik przed przesłaniem, aby uniknąć błędów przetwarzania
- Używaj
ensure_ascii=Falsedla języka francuskiego i znaków akcentowanych