Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Format JSONL, custom_id in nalaganje datotek

Lekcija 2 od 16 Posodobljeno 3. november 2026 Napredni
Na tej strani
  1. Format JSONL: hrbtenica serijskega sklepanja
  2. Struktura zahtevka JSONL
  3. Programsko ustvarjanje datoteke JSONL v Pythonu
  4. Nalaganje datoteke v Mistral
  5. Validacija datoteke
  6. Omejitve in omejevalni dejavniki
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026: Pri SDK mistralai različice 3.7.0 metoda files.upload pričakuje file={"file_name": …, "content": …} (podajanje terca sproži ValidationError, preden se pošljejo kakršni koli podatki), velikost datoteke pa je na voljo v size_bytes.

Format JSONL: hrbtenica serijskega sklepanja

JSONL (JSON Lines) je standardni format, ki ga Mistral uporablja za strukturiranje serijskih zahtevkov. Vsaka vrstica v datoteki je samostojen objekt JSON, ki predstavlja en sam zahtevek. Ta zasnova je namerna: datoteko z milijonom vrstic lahko ustvarite s pretokom, ne da bi jo celotno naložili v pomnilnik, jo ponovno prebrali vrstico za vrstico in ročno pregledali specifične vnose, ko zahtevek odpove. Za razliko od enega samega ogromnega polja JSON, ki vas prisili, da naložite celotno datoteko zgolj za preverjanje enega vnosa, vam JSONL omogoča delo na ravni vrstice.

Struktura zahtevka JSONL

Vsaka vrstica v vaši datoteki JSONL mora vsebovati dve obvezni polji:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Povzemi ta dokument v 3 točkah."}
    ]
  }
}

custom_id je edinstven identifikator, ki ga določiš ti za vsak zahtevek. Prav to omogoča uporabnost rezultatov. Mistral ne zagotavlja vrstnega reda obdelave: izhodna datoteka se lahko začne z zahtevkom št. 8.472. Brez custom_id končaš z kupom odgovorov in brez načina, da bi vedel, kateremu dokumentu pripada kateri odgovor. Naj ti postane navada, da ta ID izpelješ iz lastnega referenčnega sistema – doc-001, email-2024-03-15-042, product-sku-ABC123 – namesto uporabe anonimnega števca. Ko odgovor povzroči težave, ga lahko izslediš nazaj do vira brez zagona poizvedbe SQL. Tu veljata dve praktični pravili: ID-ji morajo biti znotraj datoteke edinstveni, sicer bo obdelava vrnila napako, in morajo biti razumno kratki, saj identifikator z 200 znaki naredi dnevnike neberljive.

Polje body ne zahteva novega učenja: vsebuje točno strukturo, ki bi jo uporabil za sinhroni klic API-ja do ciljne končne točke. Če ciljaš na /v1/chat/completions, je telo identično tistemu, ki bi ga podal v klicu client.chat.complete(). Poziv, validiran interaktivno, se neposredno prevede v serijsko opravilo.

Programsko ustvarjanje datoteke JSONL v Pythonu

Tako programsko ustvariš datoteko JSONL iz seznama dokumentov:

import json

documents = [
    {"id": "doc-001", "text": "Umetna inteligenca spreminja..."},
    {"id": "doc-002", "text": "Globoke nevronske mreže..."},
    {"id": "doc-003", "text": "Obdelava naravnega jezika..."},
]

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": "Si pomočnik, ki povzema besedila."
                    },
                    {
                        "role": "user",
                        "content": f"Povzemi to besedilo: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Upoštevaj parameter ensure_ascii=False. Brez njega json.dumps ubežne znake z naglasi pretvori v zaporedja \uXXXX. Datoteka ostane veljavna, a postane za ljudi neberljiva, kar vsako razhroščevanje na francoskem korpusu spremeni v vadbo dešifriranja. To naj bo tvoja privzeta nastavitev že od prve vrstice kode.

Nalaganje datoteke v Mistral

V produkcijskem okolju nalaganje izvedi prek API-ja Python:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Naloži datoteko 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"Naložena datoteka: {batch_file.id}")
print(f"Velikost: {batch_file.size_bytes} bajtov")
print(f"Namen: {batch_file.purpose}")

Parameter purpose="batch" pove Mistralu, da je ta datoteka namenjena serijski obdelavi, ne drugim funkcijam, kot sta fino uglaševanje ali RAG. Ta izjava o namenu določa, kaj se zgodi nato: datoteka, naložena z napačnim namenom, bo zavrnjena s strani opravila.

Za hiter test ali za netehnične ekipe AI Studio ponuja isto storitev prek grafičnega vmesnika:

  1. Pojdi na console.mistral.ai/build/files
  2. Klikni „Upload”
  3. Izberi svojo datoteko JSONL
  4. Izberi namen „Batch Processing”

Vmesnik vrne file_id, popolnoma kot API, in to je identifikator, ki ga uporabiš za ustvarjanje serijskega opravila.

Validacija datoteke

Serijsko opravilo z milijonom vrstic, ki odpove pri vrstici 300 zaradi podvojenega custom_id, te stane celoten čakalni cikel. Nekaj sekund lokalne validacije prepreči to izgubo. Naslednja skripta opravi en sam prehod za preverjanje veljavnosti JSON, prisotnosti dveh obveznih polj in edinstvenosti ID-jev:

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"Vrstica {line_num}: Neveljaven JSON - {e}")
            continue

        # Preveri obvezna polja
        if "custom_id" not in data:
            errors.append(f"Vrstica {line_num}: manjka custom_id")
        if "body" not in data:
            errors.append(f"Vrstica {line_num}: manjka body")

        # Preveri edinstvenost custom_id
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Vrstica {line_num}: podvojen custom_id '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"Najdenih {len(errors)} napak:")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"Datoteka veljavna: {len(seen_ids)} zahtevkov pripravljenih.")

To naj bo sistematičen korak v tvojem pripravljalnem procesu, ki se izvede tik pred nalaganjem.

Omejitve in omejevalni dejavniki

Serijsko združevanje datotek je omejeno na milijon vrstic na datoteko, kar pomeni, da moraš večje korpuse razdeliti na več predložitev. Kodiranje mora biti UTF-8, format pa strogo zahteva en objekt JSON na vrstico: objekt JSON, razpet čez več vrstic, kot ga proizvede neustrezno postavljen json.dumps(..., indent=2), poruši strežniško razčlenjevanje. Nazadnje, zapomni si dve že omenjeni pravili, saj njuna kršitev povzroči neuspeh opravila: custom_id mora biti znotraj datoteke edinstven, body pa se mora ujemati s shemo ciljne končne točke.

Ključne ugotovitve

  • JSONL strukturira tvoje serijske zahtevke z enim objektom JSON na vrstico
  • Vsak zahtevek zahteva edinstven custom_id in body, ki ustreza ciljni končni točki
  • Naloži prek API-ja Python (client.files.upload) ali prek AI Studio
  • Pred predložitvijo vedno validiraj svojo datoteko, da se izogneš napakam pri obdelavi
  • Uporabi ensure_ascii=False za francoske in druge znake z naglasi