Lähe põhisisu juurde
Eesti— Vali keel
Menüü

JSON-režiim vs kohandatud struktureeritud väljundid

Õppetund 2 / 12 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Kaks lähenemist, kaks filosoofiat
  2. JSON-režiim: paindlikkus
  3. Kohandatud struktureeritud väljundid: rangus
  4. Üksikasjalik võrdlus
  5. Otsuse langetamine praktikas
  6. Peamised punktid

Kaks lähenemist, kaks filosoofiat

Mistral API pakub struktureeritud väljundite genereerimiseks kahte erinevat mehhanismi. Need ei konkureeri omavahel, vaid teenindavad projekti elutsükli erinevaid etappe. Sinu valik sõltub kasutusjuhtumist, tehnoloogilisest stackist ja usaldusväärsuse tasemest, mida pead tagama.

JSON-režiim: paindlikkus

JSON-režiim on kõige lihtsam lähenemine. Lülidad oma päringus sisse ühe parameetri ja Mistral garanteerib, et väljund on kehtiv JSON. See ongi kõik. Mudel jääb vabaks valima struktuuri: võtmeid, andmetüüpe ja pesastamise sügavust. Sa juhendad soovitud formaati oma vihje (prompt) kaudu, kuid skeemi ei seo ükski tehniline piirang.

# JSON-režiim — mudel valib struktuuri
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Analyze this text and return the result in JSON."}],
    response_format={"type": "json_object"}
)

See minimalism on selle peamine tugevus: vaja on lisada vaid üks parameeter, skeemi pole vaja eelnevalt defineerida ja paindlikkus on maksimaalne, kui uurid probleemi või teed kiiret prototüüpimist. Puudus on sümmeetriline. Mitte miski ei garanteeri saadava JSON-i täpset struktuuri: mudel võib jätta välja mõne välja, lisada teise või nimetada võtme ümber ühest päringust teiseni. Seetõttu on kliendipoolne valideerimine kohustuslik ja see on kood, mille pead ise kirjutama ja haldama.

Kohandatud struktureeritud väljundid: rangus

Kohandatud struktureeritud väljundid viivad selle piirangu API poolele. Sa defineerid täpse skeemi – kasutades Pythonis Pydanticut või TypeScriptis Zodi – ja Mistral sunnib mudelit sellest täpselt kinni pidama.

from pydantic import BaseModel

class Analyse(BaseModel):
    sentiment: str
    score: float
    keywords: list[str]

# Kohandatud — skeem on jõustatud
response = client.chat.parse(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Analyze this text."}],
    response_format=Analyse
)

Kasu on kohene: iga väli on olemas õige tüübiga ja saad tagasi parsitud objekti, mis on kohe kasutatav – Pydanticu või Zodi mudeli eksemplar – koos täieliku IDE-i autotäitmisega. See on režiim tootmiskeskkonna ja kriitiliste torustike jaoks. Kompromiss taandub ühele lausele: sa pead eelnevalt defineerima andmemudeli, mis muudab uurimise vähem paindlikuks ja seab alguses väikese arenduskoormuse.

Üksikasjalik võrdlus

KriteriumJSON-režiimKohandatud struktureeritud väljundid
Aktiveerimineresponse_format: {"type": "json_object"}response_format: MyModel (Pydantic/Zod)
API meetodclient.chat.complete()client.chat.parse()
Skeemi garantiiEi – ainult kehtiv JSONJah – täpne skeem on jõustatud
Automaatne parsimineEi – manuaalne json.loads()Jah – .parsed tagastab tüübitud objekti
PaindlikkusKõrge – vaba struktuurMadal – fikseeritud struktuur
Ideaalne kasutusjuhtumPrototüüpimine, uurimine, muutlikud skeemidTootmine, kriitilised torustikud, API-d
Vajalik valideerimineJah – kohustuslik kliendipoolneMinimaalne – skeem teeb töö ära

Otsuse langetamine praktikas

Kolm signaali viitavad JSON-režiimi kasuks. Esimene on projekti staadium: kui teed prototüüpimist ja skeem pole veel stabiilne, aeglustab andmemudeli lukustamine sind väärtust lisamata. Teine on ülesande olemus: kui väljundi struktuur varieerub sisendi põhjal õigustatult, nagu uurivas analüüsis, kus asjakohased mõõtmed pole ette teada, oleks fikseeritud struktuur kitsenduseks. Kolmas on tehniline: keeles, mis ei toeta Pydanticut ega Zodi, on JSON-režiim sinu ainus sisenemispunkt.

Kohandatud struktureeritud väljundid võtavad ohjad enda kätte niipea, kui olukord muutub vastupidiseks. Oled tootmiskeskkonnas ja ebaõnnestunud ekstraktsioonil on reaalne hind; väljundi skeem on teada ja stabiilne; töötad Pythoni või TypeScriptiga; ja soovid manipuleerida tüübitud objektidega, mitte anonüümsete sõnastikega. Konkreetsemalt öeldes pole torustikul, mis liigitab terve päeva tugipileteid kasutades samu nelja välja, mingit põhjust jääda JSON-režiimi.

See on kooskõlas ametliku Mistrali dokumentatsiooniga, mis soovitab kasutada kohandatud struktureeritud väljundeid alati, kui see on võimalik. JSON-režiim on hea sisenemispunkt, kuid kohandatud väljundid pakuvad paremat usaldusväärsust ja vähendavad oluliselt kliendipoolset valideerimiskoodi.

Peamised punktid

  • JSON-režiim = garanteeritud kehtiv JSON, vaba struktuur, lihtne aktiveerida
  • Kohandatud struktureeritud väljundid = garanteeritud täpne skeem, automaatne parsimine, ideaalne tootmiseks
  • Alusta prototüüpimisel JSON-režiimiga, mine tootmises üle kohandatud väljunditele
  • Kaks lähenemist täiendavad teineteist, ei välista teineteist