Formatas JSONL, custom_id ir failo įkėlimas
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d.: Naudojant SDK
mistralai3.7.0 versiją,files.uploadtikisi parametrofile={"file_name": …, "content": …}(perduodant kortelę (tuple) prieš siunčiant duomenis išmetamaValidationErrorklaida), o failo dydis pasiekiamas persize_bytes.
Formatas JSONL: masinio apdorojimo pagrindas
JSONL (JSON Lines) yra standartinis formatas, kurį „Mistral“ naudoja masinių užklausų struktūravimui. Kiekviena failo eilutė yra savarankiškas JSON objektas, reprezentuojantis vieną užklausą. Šis dizainas yra sąmoningas: gali srautiniu būdu sugeneruoti milijono eilučių failą neįkeliant jo viso į operatyviąją atmintį, nuskaityti jį eilutė po eilutės ir rankiniu būdu patikrinti konkrečius įrašus, kai užklausa nepavyksta. Skirtingai nei vienas didžiulis JSON masyvas, kuris verčia įkelti visą failą tik tam, kad patikrintum vieną įrašą, JSONL leidžia dirbti eilučių lygmeniu.
JSONL užklausos struktūra
Kiekvienoje tavo JSONL failo eilutėje privalo būti du būtini laukai:
{
"custom_id": "req-001",
"body": {
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Summarize this document in 3 points."}
]
}
}
custom_id yra unikalus identifikatorius, kurį tu apibrėži kiekvienai užklausai. Būtent jis daro rezultatus panaudojamus. „Mistral“ negarantuoja apdorojimo tvarkos: išvesties faile pirmas gali būti 8 472-asis prašymas. Be custom_id gausi krūvą atsakymų ir neturėsi jokio būdo nustatyti, kuriam dokumentui kiekvienas jų priklauso. Įprask šį ID kurti pagal savo vidinę sistemą – doc-001, email-2024-03-15-042, product-sku-ABC123 – užuot naudojęs anoniminį skaitliuką. Kai atsakymas sukels problemų, galėsi jį atsekti iki šaltinio net nedarant SQL užklausos. Čia galioja dvi praktinės taisyklės: ID faile privalo būti unikalūs, kitaip apdorojimas grąžins klaidą, ir jie turėtų būti pakankamai trumpi, nes 200 simbolių identifikatorius padarys žurnalus neįskaitomus.
Laukui body nereikia jokių naujų žinių: jame yra tiksli struktūra, kurią naudotum sinchroniniam API iškvietimui į norimą galinį tašką. Jei taikinys yra /v1/chat/completions, kūnas yra identiškas tam, kurį perduotum kviesdamas client.chat.complete(). Interaktyviai patikrinta užuomina tiesiogiai virsta masine užduotimi.
JSONL failo generavimas naudojant Python
Štai kaip programiškai sugeneruoti JSONL failą iš dokumentų sąrašo:
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")
Atkreipk dėmesį į parametrą ensure_ascii=False. Be jo, json.dumps koduotų diakritinius simbolius kaip \uXXXX sekas. Failas liks galiojantis, bet taps neįskaitomas žmonėms, o bet koks derinimas su prancūzišku korpusu virs dešifravimo pratimu. Padaryk tai savo numatytuoju nustatymu nuo pat pirmos kodo eilutės.
Failo įkėlimas į „Mistral“
Gamybinėje aplinkoje įkelk naudodamas Python API:
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Upload the JSONL file
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}")
Parametras purpose="batch" nurodo „Mistral“, kad šis failas skirtas masiniam apdorojimui, o ne kitoms funkcijoms, tokioms kaip derinimas („fine-tuning“) arba RAG. Šis ketinimo pareiškimas lemia tolesnius veiksmus: failas, įkeltas su neteisinga paskirtimi, bus atmestas vykdant užduotį.
Greitam testavimui arba netechninėms komandoms „AI Studio“ siūlo tą pačią paslaugą per grafinę sąsają:
- Eik į
console.mistral.ai/build/files - Spustelėk „Upload“
- Pasirink savo JSONL failą
- Pasirink paskirtį „Batch Processing“
Sąsaja grąžina file_id, lygiai taip pat kaip ir API, ir būtent šį identifikatorių naudoji kurdamas masinę užduotį.
Failo validavimas
Milijono eilučių masinė užduotis, žlunganti 300-oje eilutėje dėl pasikartojančio custom_id, kainuoja tau visą laukimo ciklą. Kelios sekundės lokalaus validavimo užkerta kelią šiam nuostoliui. Šis scenarijus atlieka vieną perėjimą, kad patikrintų JSON galiojimą, dviejų būtinų laukų buvimą ir ID unikalumą:
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
# Check required fields
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")
# Check custom_id uniqueness
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.")
Padaryk tai sistemingu žingsniu savo paruošimo procese, vykdomu tiesiai prieš įkeliant failą.
Ribos ir apribojimai
Failų masinis apdorojimas apribotas iki vieno milijono eilučių vienam failui, todėl didesnius korpusus turi skaidyti į kelias pateiktis. Koduotė privalo būti UTF-8, o formatas griežtai reikalauja vieno JSON objekto vienai eilutei: JSON objektas, išdėstytas per kelias eilutes (kaip gaunama neteisingai panaudojus json.dumps(..., indent=2)), sugadina serverio pusės analizavimą. Galiausiai, prisimink dvi jau minėtas taisykles, nes jų pažeidimas lemia užduoties žlugimą: custom_id privalo būti unikalus faile, o body turi atitikti tikslinio galinio taško schemą.
Svarbiausi punktai
- JSONL struktūrizuoja tavo masines užklausas po vieną JSON objektą eilutėje
- Kiekviena užklausa reikalauja unikalaus
custom_idirbody, atitinkančio tikslinį galinį tašką - Įkelk naudodamas Python API (
client.files.upload) arba per „AI Studio“ - Visada validuok savo failą prieš pateikdamas, kad išvengtum apdorojimo klaidų
- Naudok
ensure_ascii=Falsedirbdamas su prancūzų kalba ir diakritiniais ženklais