Najboljše prakse in povzetek
Na tej strani
Povzetek tečaja
Raziskal si celoten nabor mehanizmov strukturiranega izpisa, ki jih ponuja API Mistral. Ta zadnja lekcija združuje vse, kar dela razliko v vsakdanjem delu: kako izbrati med obema pristopoma, katere nastavitve so nepogrešljive, katere so najpogostejše pasti in kaj moraš spremljati, ko si enkrat v proizvodnem okolju.
Izbira tvojega pristopa
Za odločitev zadostujejo štiri vprašanja, in sicer v tem vrstnem redu. Ali imaš definiran shemo izpisa? Če je odgovor ne, ostani pri načinu JSON: si v fazi raziskovanja ali prototipiranja in prezgodaj je, da bi zaklenil podatkovni model. Če je odgovor da, preidi na naslednje vprašanje.
Ali delaš v Pythonu ali TypeScriptu? Če da, so prilagojeni strukturirani izpisi (Custom Structured Outputs) pripravljeni zate s knjižnicama Pydantic ali Zod. Če ne, ostaja tvoja pot način JSON z ročnim preverjanjem veljavnosti.
Ali si v proizvodnem okolju? Če da, so prilagojeni strukturirani izpisi vedno obvezni. V nasprotnem primeru je način JSON več kot dovolj za prototipiranje.
Ali se shema pogosto spreminja? Shema, ki se še razvija, naredi način JSON sprva bolj praktičen, dokler se zahteve ne stabilizirajo; fiksna shema govori v prid prilagojenim strukturiranim izpisom in zanesljivosti, ki jo prinašajo.
Deset zlatih pravil
Prvih pet se nanaša na to, kako pišeš svoje klice. V proizvodnem okolju vedno nastavi temperature=0: variabilnost temperature je sovražnik zanesljivosti, ekstrakcija pa ne potrebuje ustvarjalnosti.
# Production: deterministic
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reproducibility
)
Vedno preveri finish_reason. To je edini indikator, ki te opozori na okrnjen odgovor, preden ga poskušaš uporabiti.
if response.choices[0].finish_reason != "stop":
# Response is truncated — increase max_tokens
raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")
V načinu JSON vedno navodi model v pozivu. Parameter zagotavlja sintakso, ne strukture: tvoja naloga je, da določiš ključe in njihove tipe.
# JSON Mode — the prompt MUST describe the structure
messages = [
{
"role": "system",
"content": "Return JSON with keys: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
V prilagojenem načinu dokumentiraj svoja polja. Natančen opis je vreden več kot dolg poziv in potuje s shemo v obeh jezikih.
class Product(BaseModel):
name: str = Field(description="Commercial product name")
price: float = Field(description="Price in EUR excluding tax, rounded to 2 decimals")
const ProductSchema = z.object({
name: z.string().describe("Commercial product name"),
price: z.number().describe("Price in EUR excluding tax, rounded to 2 decimals"),
});
Loči kontekst od vsebine. Navodila živijo v sistemskem sporočilu, podatki za obdelavo pa v uporabniškem sporočilu – nikoli obratno, sicer bo model zamenjal navodilo z izvornim besedilom.
messages = [
{"role": "system", "content": "You are a data extractor. [Format instructions]"},
{"role": "user", "content": "[Text to process — NO format instructions here]"}
]
Naslednji dve pravili se nanašata na tvojo varnostno mrežo. Implementiraj mehanizem za ponovne poskuse: nikoli ne opravi enega samega klica brez rezervne možnosti; ponovni poskus z povratno informacijo je minimalni vzorec v proizvodnji. In preverjaj veljavnost onkraj sheme, saj shema zagotavlja strukturo, medtem ko semantično preverjanje – meje, skladnost, poslovna logika – ostaja tvoja odgovornost.
Zadnja tri se nanašajo na orkestracijo. Izberi pravi model za pravi primer uporabe: mistral-large-latest za kompleksne naloge in ekstrakcijo več polj, mistral-small-latest za preprosto klasifikacijo in osnovno ekstrakcijo, ministral-8b-latest za visoko frekvenco in minimalno zakasnitev. Zabeleži vsak klic v proizvodnji, pri čemer zabeležiš uporabljeni model, trajanje, finish_reason in izid: brez dnevnikov si slep. Nazadnje, ne optimiziraj poziva prezgodaj – začni preprosto, meri, iteriraj; prezgodnja optimizacija poziva je pogosta past, medtem ko sta shema in preverjanje veljavnosti pravi vzvod.
Tri drage pasti
Prva je vrednost max_tokens, ki je prenizka. JSON bo okrnjen pri dolgih odgovorih, napaka pa se bo pokazala šele pri velikih dokumentih, pogosto šele po zagonu v živo.
# Dangerous — JSON will be truncated for long responses
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Too low for a complex schema
)
Nastavi max_tokens glede na pričakovano velikost tvojega izpisa: račun z 20 vrsticami zahteva več žetonov kot preprosta klasifikacija.
Druga je temperatura različna od nič, zaradi katere so tvoji rezultati neproducirabilni brez kakršne koli koristi pri nalogi ekstrakcije.
# Dangerous in production — non-reproducible results
response = client.chat.parse(
...,
temperature=0.7 # Unnecessary variation for extraction
)
Tretja je refleks uporabe enega samega modela. Ne uporabljaj mistral-large za vse: binarna klasifikacija ne zahteva najmočnejšega modela in ministral-8b bo opravil nalogo 5-krat hitreje ob nižjih stroških.
Kaj spremljati
Štirje kazalniki kažejo na zdravje tvojega procesa. Stopnja uspešnosti meri odstotek klicev, ki vrnejo veljaven objekt ob prvem poskusu; stopnja ponovnih poskusov odstotek klicev, ki so potrebovali drugo priložnost. Zakasnitev P50/P95 poda mediani čas odziva in 95. percentilo, kar je bolj razkrivalno od povprečja. Strošek na ekstrakcijo, izražen v porabljenih žetonih na klic, drži račune pod nadzorom.
Glede teh kazalnikov velja nekaj pragov za opozarjanje: stopnja uspešnosti pod 95 % upravičuje rumeno opozorilo, pod 85 % rdeče opozorilo; zakasnitev P95, večja od 10 s, zahteva preiskavo; odklopljeno stikalo (circuit breaker) pa zahteva takojšnje opozorilo.
Naprej
Štiri smeri naravno nadgrajujejo ta tečaj. Klicanje funkcij uporablja strukturirane izpise za napajanje klicev funkcij v agentu. Pretakanje (streaming) ti omogoča postopno prejemanje strukturiranega izpisa, kar je pomembno pri dolgih odgovorih. Fino uglaševanje prilagodi model Mistral za izboljšanje kakovosti ekstrakcije na tvojih specifičnih podatkih. Evalvacija nazadnje obsega vzpostavitev samodejnega okvira, ki temelji na zlatem naboru podatkov in kazalnikih – to je tisto, kar ti bo povedalo, ali sprememba poziva dejansko izboljša stvari.
Celoten proces
Spodnja koda združuje prakse tečaja v enoten tok: shema, opisana polje za poljem, validator, ki zavrača rezultate izven meja, model, prilagojen nalogi, temperature=0, ekspliciten max_tokens, preverjanje finish_reason in beleženje za oba možna izida.
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="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 and 1.0")
category: str = Field(description="product, service, delivery, price, or other")
action_required: bool = Field(description="True if action is required")
summary: str = Field(description="One-sentence summary")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Score out of bounds: {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": "Analyze customer feedback."},
{"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 in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
raise
Približno trideset vrstic in imaš komponento, ki jo lahko varno vključiš v sredino sistema: točno to omogočajo strukturirani izpisi.
Ključne ugotovitve
- V proizvodnji uporabi prilagojene strukturirane izpise, način JSON pa za prototipiranje
temperature=0, preverjanjefinish_reasonin ponovni poskusi so nepogrešljivi- Model izberi glede na kompleksnost naloge in proračun
- Spremljaj stopnjo uspešnosti, zakasnitev in stroške
- Začni preprosto, meri, nato optimiziraj
Preveri svoje znanje
Način JSON, sheme, ponovni poskusi: imaš strukturirani izpis pod nadzorom?
1. Način JSON proti prilagojenim strukturiranim izpisom: kakšna je razlika?
Odgovor: Način JSON zagotavlja sintaktično veljaven JSON; prilagojeni strukturirani izpisi poleg tega uveljavljajo tvojo točno shemo – polja, tipe, strukturo: popolno pogodbo.
2. Kaj zagotavlja client.chat.parse() s Pydantic?
Odgovor: Celoten cikel: shema Pydantic določa strukturo, API omejuje generiranje, odgovor pa prispe že preverjen in tipiziran kot objekt Python – brez ročnega razčlenjevanja.
3. In na strani TypeScript?
Odgovor: Enako udobje z Zod: shema Zod določa in preverja strukturo – en sam vir resnice za generiranje in tipizacijo.
4. Kaj storiti, ko izpis ne spoštuje sheme?
Odgovor: Sistematično preveri veljavnost in načrtuj strategijo ponovnih poskusov: ponovno zahtevaj z napako v kontekstu ali elegantno degradiraj – nikoli slepo zaupaj izpisu.
5. Kdaj je strukturirani izpis nujen?
Odgovor: Takoj, ko program porabi odgovor brez človeškega pregleda: ekstrakcija, integracije, procesi – format preneha biti vljudnost, postane vmesnik.
Deklarirana shema, omejeno generiranje, preverjanje izpisa: triada, ki omogoča vključitev UI v pravo programsko opremo.