Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

JSONL formátum, custom_id és fájlfeltöltés

2. lecke 16 közül Frissítve 2026. november 3. Haladó
Ezen az oldalon
  1. A JSONL formátum: a batch lekérdezések gerince
  2. A JSONL kérés szerkezete
  3. JSONL fájl generálása Pythonban
  4. A fájl feltöltése a Mistralra
  5. Fájlellenőrzés
  6. Korlátok és megszorítások
  7. Főbb megállapítások

Frissítve: 2026. november 3.: A mistralai SDK 3.7.0 verziójától a files.upload metódus a file={"file_name": …, "content": …} paramétert várja (tuple átadása ValidationError hibát dob, még mielőtt bármilyen adat elküldésre kerülne), a fájlméret pedig a size_bytes mező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):

  1. Navigálj ide: console.mistral.ai/build/files
  2. Kattints az „Upload“ (Feltöltés) gombra
  3. Válaszd ki a JSONL fájlodat
  4. 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=False paramétert a francia és egyéb ékezetes karakterek helyes kezeléséhez