Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Formatas JSONL, custom_id ir failo įkėlimas

Paskaita 2 iš 16 Atnaujinta 2026 m. lapkričio 3 d. Pažengusiems
Šiame puslapyje
  1. Formatas JSONL: masinio apdorojimo pagrindas
  2. JSONL užklausos struktūra
  3. JSONL failo generavimas naudojant Python
  4. Failo įkėlimas į „Mistral“
  5. Failo validavimas
  6. Ribos ir apribojimai
  7. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d.: Naudojant SDK mistralai 3.7.0 versiją, files.upload tikisi parametro file={"file_name": …, "content": …} (perduodant kortelę (tuple) prieš siunčiant duomenis išmetama ValidationError klaida), o failo dydis pasiekiamas per size_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ą:

  1. Eik į console.mistral.ai/build/files
  2. Spustelėk „Upload“
  3. Pasirink savo JSONL failą
  4. 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_id ir body, 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=False dirbdamas su prancūzų kalba ir diakritiniais ženklais