Formaat JSONL, custom_id ja tiedoston lataus
Tällä sivulla
Päivitetty 3. marraskuuta 2026: SDK:n
mistralaiversiossa 3.7.0files.uploadodottaa parametriafile={"file_name": …, "content": …}(tuple-tyypin välittäminen aiheuttaaValidationError-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:
- Siirry osoitteeseen
console.mistral.ai/build/files - Napsauta “Upload”
- Valitse JSONL-tiedostosi
- 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 mukaisenbody: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=Falseranskan kielen ja tarkkeellisten merkkien kanssa