Parimad tavad ja kokkuvõte
Sellel lehel
Kursuse kokkuvõte
Oled tutvunud Mistral API pakutavate struktureeritud väljundmehhanismide täieliku valikuga. See viimane õppetund toob kokku selle, mis teeb igapäevatöös vahet: kuidas valida kahe lähenemisviisi vahel, millised seaded on kohustuslikud, millised on levinuimad lõksud ja mida tuleb tootmiskeskkonnas jälgida.
Oma lähenemisviisi valimine
Otsuse tegemiseks piisab neljast küsimusest, esitatuna selles järjekorras. Kas sul on defineeritud väljundi skeem? Kui vastus on ei, jää JSON-režiimi juurde: oled uurimis- või prototüüpimisetapis ja andmemudeli lukustamine oleks ennatlik. Kui jah, liigu järgmise küsimuse juurde.
Kas töötad Pythoni või TypeScriptiga? Kui jah, on kohandatud struktureeritud väljundid (Custom Structured Outputs) sinu jaoks valmis koos Pydantici või Zodiga. Kui ei, jääb sinu teeks JSON-režiim koos manuaalse valideerimisega.
Kas oled tootmiskeskkonnas? Kui jah, on kohandatud struktureeritud väljundid alati kohustuslikud. Vastasel juhul on JSON-režiim prototüüpimiseks enam kui piisav.
Kas skeem muutub sageli? Alles kujunev skeem teeb JSON-režiimi esialgu praktilisemaks, kuni nõuded stabiliseeruvad; fikseeritud skeem eeldab kohandatud struktureeritud väljundeid ja nende pakutavat usaldusväärsust.
Kümme kuldreeglit
Esimesed viis puudutavad päringute kirjutamist. Määra tootmiskeskkonnas alati temperature=0: temperatuuri muutlikkus on usaldusväärsuse vaenlane ja ekstraktsioon ei vaja loovust.
# Tootmine: deterministlik
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Korratavus
)
Kontrolli alati finish_reason-i. See on ainus indikaator, mis hoiatab sind katkenud vastuse eest, enne kui seda kasutama hakkad.
if response.choices[0].finish_reason != "stop":
# Vastus on katkenud — suurenda max_tokens
raise ValueError(f"Puudulik vastus: {response.choices[0].finish_reason}")
JSON-režiimis anna mudelile alati juhised promptis. Parameeter garanteerib süntaksi, mitte struktuuri: võtmed ja nende tüübid pead ise määratlema.
# JSON-režiim — prompt PEAB kirjeldama struktuuri
messages = [
{
"role": "system",
"content": "Tagasta JSON võtmetega: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
Kohandatud režiimis dokumenteeri oma väljad. Täpne kirjeldus on väärtuslikum kui pikk prompt ja see liigub skeemiga kaasas mõlemas keeles.
class Product(BaseModel):
name: str = Field(description="Kaubanduslik tootenimi")
price: float = Field(description="Hind EUR ilma käibemaksuta, ümardatud 2 komakohani")
const ProductSchema = z.object({
name: z.string().describe("Kaubanduslik tootenimi"),
price: z.number().describe("Hind EUR ilma käibemaksuta, ümardatud 2 komakohani"),
});
Eralda kontekst sisust. Juhised kuuluvad süsteemsõnumisse, töödeldavad andmed kasutajasõnumisse – mitte kunagi vastupidi, muidu ajab mudel juhised lähtetekstiga sassi.
messages = [
{"role": "system", "content": "Oled andmete ekstraheerija. [Vormingu juhised]"},
{"role": "user", "content": "[Töödeldav tekst — SIIN pole vormingu juhiseid]"}
]
Järgmised kaks reeglit puudutavad sinu turvavõrku. Rakenda korduskatse mehhanismi: ära tee kunagi ühteainsat päringut ilma varuplaanita; tagasisidega korduskatse on tootmiskeskkonnas minimaalne muster. Ja valideeri üle skeemi, kuna skeem garanteerib struktuuri, samas kui semantiline valideerimine – piirid, järjepidevus, ärireeglid – jääb sinu vastutuseks.
Viimased kolm puudutavad orkestratsiooni. Vali õige mudel õigeks kasutusjuhuks: mistral-large-latest keerukate ülesannete ja mitmeväljalise ekstraktsiooni jaoks, mistral-small-latest lihtsa klassifitseerimise ja baasekstraktsiooni jaoks, ministral-8b-latest suure sageduse ja minimaalse latentsuse jaoks. Logi iga päring tootmiskeskkonnas, salvestades kasutatud mudeli, kestuse, finish_reason-i ja tulemuse: ilma logideta oled pime. Lõpuks, ära optimeeri prompti liiga vara – alusta lihtsast, mõõda, iteratsiooni; ennatlik prompti optimeerimine on levinud lõks, samas kui skeem ja valideerimine on tegelikud hoovad.
Kolm kulukat lõksu
Esimene on liiga väike max_tokens väärtus. JSON katkeb pikkade vastuste korral ja viga avaldub alles suurte dokumentide puhul, sageli alles pärast kasutuselevõttu.
# Ohtlik — JSON katkeb pikkade vastuste korral
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Liiga väike keeruka skeemi jaoks
)
Määra max_tokens oma väljundi eeldatava suuruse põhjal: 20-realine arve nõuab rohkem tokeneid kui lihtne klassifitseerimine.
Teine on nullist erinev temperatuur, mis muudab sinu tulemused kordumatuteks, pakkudes ekstraktsiooniülesande puhul nullist kasu.
# Ohtlik tootmiskeskkonnas — kordumatud tulemused
response = client.chat.parse(
...,
temperature=0.7 # Ekstraktsiooni jaoks mittevajalik varieeruvus
)
Kolmas on refleks kasutada ühteainest mudelit. Ära kasuta mistral-large-i kõige jaoks: binaarne klassifitseerimine ei vaja võimsaimat mudelit ja ministral-8b teeb töö ära 5 korda kiiremini väiksemate kuludega.
Mida jälgida
Neli mõõdikut annavad ülevaate sinu torustiku tervisest. Edukuse määr mõõdab nende päringute protsenti, mis tagastavad esimesel katsel kehtiva objekti; korduskatsete määr näitab protsenti päringutest, mis vajasid teist võimalust. P50/P95 latentsus annab keskmise vastusaja ja 95. protsentiili, mis on paljastavam kui keskmine. Kulu ekstraktsiooni kohta, väljendatuna tarbitud tokenites päringu kohta, hoiab arve kontrolli all.
Nende mõõdikute puhul kehtivad hästi mõned häireläved: edukuse määr alla 95% õigustab kollast häiret, alla 85% punast häiret; P95 latentsus suurem kui 10 s nõuab uurimist; ja avatud vooluahela katkesti (circuit breaker) kutsub esile viivitamatu häire.
Edasi liikumine
Neli suunda laiendavad seda kursust loomulikul teel. Funktsioonide kutsumine (Function calling) kasutab struktureeritud väljundeid agentide funktsioonikutsude toitmiseks. Voogedastus (Streaming) võimaldab struktureeritud väljundit järk-järgult vastu võtta, mis on oluline pikkade vastuste puhul. Peenhäälestus (Fine-tuning) kohandab Mistrali mudelit, et parandada ekstraktsiooni kvaliteeti just sinu andmetel. Hindamine (Evaluation) lõpuks seisneb automaatse raamistiku loomises, mis põhineb kuldandel (golden dataset) ja mõõdikutel – see ütleb sulle, kas prompti muutus tegelikult asju parandas.
Täielik torustik
Järgnev kood toob kokku kursuse parimad tavad ühte voogu: väljapõhiselt kirjeldatud skeem, valideerija, mis lükkab tagasi piiridest väljuvad hinnangud, ülesandele sobiva suurusega mudel, temperature=0, selge max_tokens, finish_reason-i kontrollimine ja logimine mõlema võimaliku tulemuse jaoks.
from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time
logger = logging.getLogger("pipeline")
class CustomerFeedback(BaseModel):
sentiment: str = Field(description="positiivne, negatiivne või neutraalne")
score: float = Field(description="Hinne vahemikus -1.0 kuni 1.0")
category: str = Field(description="toode, teenus, tarne, hind või muu")
action_required: bool = Field(description="Tõene, kui tegevus on vajalik")
summary: str = Field(description="Üherealine kokkuvõte")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Hinne väljaspool piire: {v}")
return v
def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
start = time.time()
try:
response = client.chat.parse(
model="mistral-small-latest",
messages=[
{"role": "system", "content": "Analüüsi kliendi tagasisidet."},
{"role": "user", "content": text}
],
response_format=CustomerFeedback,
temperature=0,
max_tokens=256
)
assert response.choices[0].finish_reason == "stop"
result = response.choices[0].message.parsed
logger.info(f"OK ajaga {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"VIGA ajaga {time.time()-start:.2f}s — {e}")
raise
Umbes kolmkümmend rida ja sul on komponent, mida saab süsteemi keskele ohutult ühendada: just seda võimaldavadki struktureeritud väljundid.
Peamised punktid
- Kasuta tootmiskeskkonnas kohandatud struktureeritud väljundeid, prototüüpimiseks JSON-režiimi
temperature=0,finish_reason-i kontrollimine ja korduskatsed on mittekõrvaldatavad- Vali mudel ülesande keerukuse ja eelarve põhjal
- Jälgi edukuse määra, latentsust ja kulusid
- Alusta lihtsast, mõõda ja seejärel optimeeri
Testi oma teadmisi
JSON-režiim, skeemid, korduskatsed: kas struktureeritud väljund on kontrolli all?
1. JSON-režiim vs kohandatud struktureeritud väljundid: mis on erinevus?
Vastus: JSON-režiim garanteerib süntaktiliselt kehtiva JSON-i; kohandatud struktureeritud väljundid jõustavad lisaks sinu täpse skeemi – väljad, tüübid, struktuur: täielik leping.
2. Mida pakub client.chat.parse() koos Pydanticiga?
Vastus: Täieliku tsükli: Pydantici skeem deklareerib struktuuri, API piirab genereerimist ja vastus saabub juba valideerituna ja tüübituna Pythoni objektina – null manuaalset parsimist.
3. Ja TypeScripti poolel?
Vastus: Sama mugavus Zodiga: Zodi skeem defineerib ja valideerib struktuuri – ainus tõese allikas nii genereerimiseks kui ka tüüpimiseks.
4. Mida teha, kui väljund ei järgi skeemi?
Vastus: Valideeri süstemaatiliselt ja planeeri korduskatse strateegia: küsi uuesti, lisades vea konteksti, või degradeeru graatsiliselt – ära kunagi pimesi usalda väljundit.
5. Millal on struktureeritud väljund hädavajalik?
Vastus: Niipea, kui programm tarbib vastust ilma inimliku ülevaatuseta: ekstraktsioon, integratsioonid, torustikud – vorming lakkab olemast viisakus, sellest saab liides.
Deklareeritud skeem, piiratud genereerimine, väljundi valideerimine: kolmik, mis teeb tehisintellekti ühendatavaks päris tarkvaraga.