Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Formaat JSONL, custom_id ja tiedoston lataus

Oppitunti 2 / 16 Päivitetty 3. marraskuuta 2026 Edistynyt
Tällä sivulla
  1. JSONL-formaatti: batch-päätelyn selkäranka
  2. JSONL-pyynnön rakenne
  3. JSONL-tiedoston generointi Pythonilla
  4. Tiedoston lataus Mistraliin
  5. Tiedoston validointi
  6. Rajat ja rajoitukset
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026: SDK:n mistralai versiossa 3.7.0 files.upload odottaa parametria file={"file_name": …, "content": …} (tuple-tyypin välittäminen aiheuttaa ValidationError-virheen ennen datan lähetystä), ja tiedoston koko on saatavilla kentässä size_bytes.

JSONL-formaatti: batch-päätelyn selkäranka

JSONL (JSON Lines) on standardimuoto, jota Mistral käyttää batch-pyyntöjen rakenteistamiseen. Tiedoston jokainen rivi on itsenäinen JSON-objekti, joka edustaa yhtä pyyntöä. Tämä suunnittelu on tarkoituksenmukaista: voit generoida miljoonan rivin tiedoston virtauttamatta sitä kokonaan muistiin, lukea sen takaisin rivi kerrallaan ja tarkastella tiettyjä merkintöjä manuaalisesti, jos pyyntö epäonnistuu. Toisin kuin valtava yksittäinen JSON-taulukko, joka pakottaa lataamaan koko tiedoston vain yhden merkinnän varmistamiseksi, JSONL mahdollistaa työskentelyn rivitasolla.

JSONL-pyynnön rakenne

Jokaisen JSONL-tiedostosi rivin on sisällettävä kaksi pakollista kenttää:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Summarize this document in 3 points."}
    ]
  }
}

custom_id on yksilöllinen tunniste, jonka sinä määrität jokaiselle pyynnölle. Se on se, mikä tekee tuloksista käyttökelpoisia. Mistral ei takaa käsittelyjärjestystä: tulostiedosto voi alkaa pyynnöstä 8 472. Ilman custom_id:tä sinulla on vain pino vastauksia eikä mitään keinoa tietää, mitä dokumenttia kukin niistä vastaa. Tee tavaksi johtaa tämä ID omasta viitejärjestelmästäsi – esimerkiksi doc-001, email-2024-03-15-042, product-sku-ABC123 – anonyymin laskurin käytön sijaan. Kun vastaus aiheuttaa ongelmia, voit jäljittää sen lähteeseen ilman SQL-kyselyn ajamista. Tässä pätee kaksi käytännön sääntöä: ID:t ovat oltava yksilöllisiä tiedoston sisällä, muuten käsittely palauttaa virheen, ja niiden tulisi olla kohtuullisen lyhyitä, sillä 200 merkin tunniste tekee lokeista lukukelvottomia.

body-kenttä ei vaadi uuden opettelua: se sisältää täsmälleen saman rakenteen, jota käyttäisit synkronisessa API-kutsussa kohdepäätepisteeseen. Jos kohdistat pyynnön osoitteeseen /v1/chat/completions, body on identtinen sen kanssa, jonka välittäisit client.chat.complete()-kutsussa. Interaktiivisesti validoitu kehote muuttuu suoraan batch-työksi.

JSONL-tiedoston generointi Pythonilla

Näin generoit JSONL-tiedoston ohjelmallisesti dokumenttilistasta:

import json

documents = [
    {"id": "doc-001", "text": "Artificial intelligence is transforming..."},
    {"id": "doc-002", "text": "Deep neural networks..."},
    {"id": "doc-003", "text": "Natural language processing..."},
]

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": "You are an assistant that summarizes texts."
                    },
                    {
                        "role": "user",
                        "content": f"Summarize this text: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Huomaa parametri ensure_ascii=False. Ilman sitä json.dumps koodaa tarkkeelliset merkit \uXXXX-sekvensseiksi. Tiedosto pysyy kelvollisena, mutta siitä tulee ihmiselle lukukelvoton, mikä muuttaa ranskalaisen korpuksen virheenjäljityksen salauksenpurkamisharjoitukseksi. Tee tästä oletusarvo jo koodin ensimmäiseltä riviltä lähtien.

Tiedoston lataus Mistraliin

Tuotantoympäristössä lataus tapahtuu Python-API:n kautta:

from mistralai.client import Mistral

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

# Lataa JSONL-tiedosto
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"Uploaded file: {batch_file.id}")
print(f"Size: {batch_file.size_bytes} bytes")
print(f"Purpose: {batch_file.purpose}")

Parametri purpose="batch" kertoo Mistralille, että tämä tiedosto on tarkoitettu batch-käsittelyyn, ei muihin ominaisuuksiin kuten hienosäätöön tai RAG:iin. Tämä aikomuksen ilmoitus määrää, mitä seuraavaksi tapahtuu: väärällä käyttötarkoituksella ladattu tiedosto hylätään työssä.

Nopeaa testausta varten tai ei-teknisille tiimeille AI Studio tarjoaa saman palvelun graafisen käyttöliittymän kautta:

  1. Siirry osoitteeseen console.mistral.ai/build/files
  2. Napsauta “Upload”
  3. Valitse JSONL-tiedostosi
  4. Valitse käyttötarkoitukseksi “Batch Processing”

Käyttöliittymä palauttaa file_id:n aivan kuten API, ja tämä on tunniste, jota käytät batch-työn luomiseen.

Tiedoston validointi

Miljoonan rivin batch, joka epäonnistuu rivillä 300 duplikaatin custom_id:n vuoksi, maksaa sinulle koko odotusjakson. Muutama sekunti paikallista validointia estää tämän menetyksen. Seuraava skripti suorittaa yhden läpikulun tarkistaakseen JSONin kelvollisuuden, kahden pakollisen kentän olemassaolon ja ID:tten yksilöllisyyden:

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

        # Tarkista pakolliset kentät
        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")

        # Tarkista custom_id:n yksilöllisyys
        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.")

Tee tästä systemaattinen vaihe valmisteluputkistoosi, suoritettuna juuri ennen latausta.

Rajat ja rajoitukset

Tiedostobatchien yläraja on miljoona riviä tiedostoa kohden, mikä tarkoittaa, että suuremmat korpuksen on jaettava useisiin lähetyksiin. Koodauksen on oltava UTF-8, ja formaatti vaatii ehdottomasti yhtä JSON-objektia riviä kohden: useammalle riville levitetty JSON-objekti, kuten virheellisesti sijoitettu json.dumps(..., indent=2) tuottaa, rikkoo palvelinpuolen jäsennyksen. Muista lopuksi kaksi jo mainittua sääntöä, sillä niiden rikkominen aiheuttaa työn epäonnistumisen: custom_id:n on oltava yksilöllinen tiedoston sisällä, ja body:n on vastattava kohdepäätepisteen skeemaa.

Keskeiset asiat

  • JSONL jäsentelee batch-pyyntösi yhtenä JSON-objektina riviä kohden
  • Jokainen pyyntö vaatii yksilöllisen custom_id:n ja kohdepäätepisteen skeeman mukaisen body:n
  • Lataa tiedosto Python-API:n (client.files.upload) tai AI Studion kautta
  • Validoi tiedostosi aina ennen lähetystä käsittelyvirheiden välttämiseksi
  • Käytä parametria ensure_ascii=False ranskan kielen ja tarkkeellisten merkkien kanssa