JSONL formátum, custom_id és fájlfeltöltés
Ezen az oldalon
Frissítve: 2026. november 3.: A
mistralaiSDK 3.7.0 verziójától afiles.uploadmetódus afile={"file_name": …, "content": …}paramétert várja (tuple átadásaValidationErrorhibát dob, még mielőtt bármilyen adat elküldésre kerülne), a fájlméret pedig asize_bytesmezőben érhető el.
A JSONL formátum: a batch lekérdezések gerince
A JSONL (JSON Lines) a szabványos formátum, amelyet a Mistral a batch kérések strukturálására használ. A fájl minden sora egy önálló JSON-objektum, amely egyetlen kérést reprezentál. Ez a kialakítás szándékos: így millió soros fájlt is folyamatosan generálhatsz anélkül, hogy az egészet a memóriába kellene töltened, soronként olvashatod vissza, és hiba esetén manuálisan is ellenőrizheted a konkrét bejegyzéseket. Ezzel szemben egy egyetlen hatalmas JSON-tömb arra kényszerítene, hogy az egész fájlt betöltsd csupán egy bejegyzés ellenőrzéséhez is, míg a JSONL lehetővé teszi a sor szintű munkavégzést.
A JSONL kérés szerkezete
A JSONL fájl minden sorának két kötelező mezőt kell tartalmaznia:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Foglald össze ezt a dokumentumot 3 pontban."}
]
}
}
A custom_id egy egyedi azonosító, amelyet te definiálsz minden egyes kéréshez. Ez teszi használhatóvá az eredményeket. A Mistral nem garantálja a feldolgozási sorrendet: a kimeneti fájl akár a 8472-es kéréssel is kezdődhet. custom_id nélkül csak egy halom válaszod lesz, fogalmad sem lesz arról, melyik dokumentumhoz tartozik melyik. Szoktasd rá magad, hogy ezt az azonosítót a saját referencia-rendszeredből képezd le – például doc-001, email-2024-03-15-042, product-sku-ABC123 –, ne pedig névtelen számlálót használj. Ha egy válasz problémát okoz, így közvetlenül visszavezetheted a forráshoz SQL-lekérdezés futtatása nélkül. Két gyakorlati szabály vonatkozik erre: az azonosítóknak egyedinek kell lenniük a fájlon belül, ellenkező esetben a feldolgozás hibát dob, és ésszerűen rövideknek kell lenniük, mivel egy 200 karakteres azonosító olvashatatlanná teszi a naplófájlokat.
A body mező nem igényel új ismereteket: pontosan azt a struktúrát tartalmazza, amelyet egy szinkron API-híváshoz használnál a célzott végponton. Ha a /v1/chat/completions végpontra céloz, a törzs (body) megegyezik azzal, amit egy client.chat.complete() hívásnál adnál át. Egy interaktívan validált prompt közvetlenül batch feladattá alakítható.
JSONL fájl generálása Pythonban
Így generálhatsz programozottan egy JSONL fájlt dokumentumok listájából:
import json
documents = [
{"id": "doc-001", "text": "A mesterséges intelligencia átalakítja..."},
{"id": "doc-002", "text": "Mély neurális hálózatok..."},
{"id": "doc-003", "text": "Természetes nyelvfeldolgozás..."},
]
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": "Olyan asszisztens vagy, aki szövegeket foglal össze."
},
{
"role": "user",
"content": f"Foglald össze ezt a szöveget: {doc['text']}"
}
]
}
}
f.write(json.dumps(request, ensure_ascii=False) + "\n")
Figyeld meg az ensure_ascii=False paramétert. Enélkül a json.dumps az ékezetes karaktereket \uXXXX szekvenciákká alakítja. A fájl érvényes marad, de emberek számára olvashatatlanná válik, így bármilyen francia korpuszon végzett hibakeresés megfejtési gyakorlattá silányul. Ezt tedd alapértelmezetté már a kód első sorától kezdve.
A fájl feltöltése a Mistralra
Éles környezetben a Python API-n keresztül töltsd fel a fájlt:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# A JSONL fájl feltöltése
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"Feltöltött fájl: {batch_file.id}")
print(f"Méret: {batch_file.size_bytes} bájt")
print(f"Cél: {batch_file.purpose}")
A purpose="batch" paraméter jelzi a Mistral számára, hogy ezt a fájlt batch feldolgozásra szánod, nem pedig egyéb funkciókhoz, mint például a finomhangolás (fine-tuning) vagy a RAG. Ez a szándéknyilatkozat határozza meg a továbbiakat: a rossz céllal feltöltött fájlt a feladat elutasítja.
Gyors teszteléshez vagy nem technikai csapatok számára az AI Studio ugyanezt a szolgáltatást kínálja grafikus felületen (GUI):
- Navigálj ide:
console.mistral.ai/build/files - Kattints az „Upload“ (Feltöltés) gombra
- Válaszd ki a JSONL fájlodat
- Válaszd a „Batch Processing“ (Batch feldolgozás) célt
A felület egy file_id-t ad vissza, pontosan úgy, mint az API, és ez az azonosító szükséges a batch feladat létrehozásához.
Fájlellenőrzés
Egy milliósoros batch, amely a 300. sorban elbukik egy duplikált custom_id miatt, egy teljes várakozási ciklust pazarol el. Néhány másodperc helyi validálás megelőzi ezt a veszteséget. Az alábbi szkript egyetlen átmenettel ellenőrzi a JSON érvényességét, a két kötelező mező jelenlétét és az azonosítók egyediségét:
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_num}. sor: Érvénytelen JSON - {e}")
continue
# Kötelező mezők ellenőrzése
if "custom_id" not in data:
errors.append(f"{line_num}. sor: hiányzó custom_id")
if "body" not in data:
errors.append(f"{line_num}. sor: hiányzó body")
# A custom_id egyediségének ellenőrzése
cid = data.get("custom_id")
if cid in seen_ids:
errors.append(f"{line_num}. sor: duplikált custom_id '{cid}'")
seen_ids.add(cid)
if errors:
print(f"{len(errors)} hiba található:")
for e in errors:
print(f" - {e}")
else:
print(f"A fájl érvényes: {len(seen_ids)} kérés áll készen.")
Tedd ezt rendszeres lépéssé az előkészítő pipeline-ban, közvetlenül a feltöltés előtt.
Korlátok és megszorítások
A fájlos batchelés fájlonként egymillió sorban maximalizálódik, ami azt jelenti, hogy a nagyobb korpuszokat több beküldésre kell szétbontanod. A kódolásnak UTF-8-nak kell lennie, és a formátum szigorúan megköveteli, hogy soronként egy JSON-objektum legyen: egy több sorra tördelt JSON-objektum, amelyet például egy helytelenül elhelyezett json.dumps(..., indent=2) hoz létre, megtöri a szerveroldali elemzést. Végül ne feledd a már említett két szabályt, mivel megszegésük a feladat meghiúsulásához vezet: a custom_id-nak egyedinek kell lennie a fájlon belül, a body-nak pedig meg kell felelnie a célzott végpont sémájának.
Főbb megállapítások
- A JSONL soronként egy JSON-objektummal strukturálja a batch kéréseidet
- Minden kéréshez szükséges egy egyedi
custom_idés a célzott végpont sémájának megfelelőbody - A feltöltés történhet a Python API-n (
client.files.upload) vagy az AI Studio felületén keresztül - Mindig validáld a fájlt beküldés előtt a feldolgozási hibák elkerülése érdekében
- Használd az
ensure_ascii=Falseparamétert a francia és egyéb ékezetes karakterek helyes kezeléséhez