Najbolje prakse i sažetak
Na ovoj stranici
Sažetak tečaja
Istražio si cijeli spektar mehanizama strukturiranog izlaza koje nudi Mistral API. Ova završna lekcija povezuje ono što čini razliku u svakodnevnom radu: kako odabrati između dva pristupa, koje su postavke neupitne, koje su najčešće zamke i što moraš pratiti jednom kada si u proizvodnji.
Odabir tvog pristupa
Četiri pitanja dovoljna su za odluku, ovim redoslijedom. Imaš li definiranu shemu izlaza? Ako je odgovor ne, drži se JSON načina: nalaziš se u fazi istraživanja ili izrade prototipa, a zaključavanje podatkovnog modela bilo bi prerano. Ako je odgovor da, prijeđi na sljedeće pitanje.
Radiš li u Pythonu ili TypeScriptu? Ako je tako, prilagođeni strukturirani izlazi spremni su za tebe uz Pydantic ili Zod. Ako nije, JSON način s ručnom validacijom ostaje tvoj put.
Jesi li u proizvodnji? Ako jesi, prilagođeni strukturirani izlazi su obavezni, uvijek. Inače, JSON način više je nego dovoljan za prototipove.
Mijenja li se shema često? Shema koja se još razvija čini JSON način praktičnijim u početku, dok se zahtjevi ne stabiliziraju; fiksna shema govori u prilog prilagođenim strukturiranim izlazima i pouzdanosti koju donose.
Deset zlatnih pravila
Prvih pet odnosi se na način pisanja poziva. Uvijek postavi temperature=0 u proizvodnji: varijabilnost temperature neprijatelj je pouzdanosti, a ekstrakcija ne treba kreativnost.
# Production: deterministic
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reproducibility
)
Uvijek provjeri finish_reason. To je jedini pokazatelj koji te upozorava na odsječen odgovor prije nego što ga pokušaš upotrijebiti.
if response.choices[0].finish_reason != "stop":
# Response is truncated — increase max_tokens
raise ValueError(f"Incomplete response: {response.choices[0].finish_reason}")
U JSON načinu uvijek daj uputu modelu u promptu. Parametar jamči sintaksu, a ne strukturu: na tebi je da navedeš ključeve i njihove tipove.
# 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}
]
U prilagođenom načinu dokumentiraj svoja polja. Precizan opis vrijedi više od dugog prompta i putuje zajedno sa shemom u oba jezika.
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"),
});
Odvoji kontekst od sadržaja. Upute pripadaju sistemskoj poruci, podaci za obradu korisničkoj poruci—nikada obrnuto, inače će model pomiješati uputu s izvornim tekstom.
messages = [
{"role": "system", "content": "You are a data extractor. [Format instructions]"},
{"role": "user", "content": "[Text to process — NO format instructions here]"}
]
Sljedeća dva pravila tiču se tvoje sigurnosne mreže. Implementiraj mehanizam ponovnog pokušaja: nikada ne izvršavaj jedan poziv bez sigurnosne kopije; ponovni pokušaj s povratnom informacijom minimalni je obrazac u proizvodnji. I validiraj izvan sheme, jer shema jamči strukturu, dok semantička validacija—granice, dosljednost, poslovna logika—ostaje tvoja odgovornost.
Posljednja tri odnose se na orkestraciju. Odaberi pravi model za pravi slučaj upotrebe: mistral-large-latest za složene zadatke i ekstrakciju više polja, mistral-small-latest za jednostavnu klasifikaciju i osnovnu ekstrakciju, ministral-8b-latest za visoku učestalost i minimalnu latenciju. Bilježi svaki poziv u proizvodnji, zapisujući korišteni model, trajanje, finish_reason i ishod: bez zapisnika slijep si. Naposljetku, ne optimiziraj prompt prerano—kreni jednostavno, mjeri, iteriraj; prerana optimizacija prompta česta je zamka, dok su shema i validacija prave poluge.
Tri skupe zamke
Prva je vrijednost max_tokens koja je preniska. JSON će biti odsječen kod dugih odgovora, a pogreška će se pojaviti tek na velikim dokumentima, često nakon lansiranja.
# 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
)
Postavi max_tokens na temelju očekivane veličine tvog izlaza: račun s 20 stavki zahtijeva više tokena od jednostavne klasifikacije.
Druga je temperatura različita od nule, što tvoje rezultate čini nereproducibilnima bez ikakve dobiti za zadatak ekstrakcije.
# Dangerous in production — non-reproducible results
response = client.chat.parse(
...,
temperature=0.7 # Unnecessary variation for extraction
)
Treća je refleks korištenja jednog modela. Ne koristi mistral-large za sve: binarna klasifikacija ne zahtijeva najmoćniji model, a ministral-8b obavit će posao 5 puta brže uz manje troškove.
Što pratiti
Četiri metrike govore o zdravlju tvog pipelinea. Stopa uspješnosti mjeri postotak poziva koji vraćaju valjani objekt iz prvog pokušaja; stopa ponovnih pokušaja postotak je poziva kojima je trebala druga prilika. Latencija P50/P95 daje srednje vrijeme odgovora i 95. percentil, što je otkrivenije od prosjeka. Trošak po ekstrakciji, izražen u potrošenim tokenima po pozivu, drži račun pod kontrolom.
Na temelju ovih metrika, nekoliko pragova upozorenja dobro funkcionira: stopa uspješnosti ispod 95% opravdava žuto upozorenje, ispod 85% crveno upozorenje; latencija P95 veća od 10 s zahtijeva istragu; a otvoren prekidač kruga (circuit breaker) zahtijeva hitno upozorenje.
Daljnji koraci
Četiri smjera prirodno proširuju ovaj tečaj. Pozivanje funkcija koristi strukturirane izlaze za napajanje poziva funkcija u agentu. Strujanje (streaming) omogućuje ti progresivno primanje strukturiranog izlaza, što je važno za duge odgovore. Fino podešavanje (fine-tuning) prilagođava Mistral model za poboljšanje kvalitete ekstrakcije na tvojim specifičnim podacima. Evaluacija, naposljetku, sastoji se od postavljanja automatskog okvira temeljenog na zlatnom skupu podataka i metrikama—to je ono što će ti reći poboljšava li promjena prompta stvari.
Cjeloviti pipeline
Sljedeći kod objedinjuje prakse tečaja u jedan tijek: shema opisana polje po polje, validator koji odbija rezultate izvan granica, model prilagođen zadatku, temperature=0, eksplicitni max_tokens, provjera finish_reason i bilježenje za oba moguća ishoda.
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
Oko trideset redaka i imaš komponentu koju možeš sigurno uključiti u sredinu sustava: točno je to ono što strukturirani izlazi omogućuju.
Ključne točke
- Koristi prilagođene strukturirane izlaze u proizvodnji, JSON način za prototipove
temperature=0, provjerafinish_reasoni ponovni pokušaj nisu pregovarački- Odaberi model na temelju složenosti zadatka i proračuna
- Prati stopu uspješnosti, latenciju i troškove
- Kreni jednostavno, izmjeri, zatim optimiziraj
Provjeri svoje znanje
JSON način, sheme, ponovni pokušaj: strukturirani izlaz pod kontrolom?
1. JSON način naspram prilagođenih strukturiranih izlaza: koja je razlika?
Odgovor: JSON način jamči sintaksno valjani JSON; prilagođeni strukturirani izlazi dodatno nameću tvoju točnu shemu—polja, tipove, strukturu: cjeloviti ugovor.
2. Što pruža client.chat.parse() s Pydanticom?
Odgovor: Cjelokupni ciklus: Pydantic shema deklarira strukturu, API ograničava generiranje, a odgovor stiže već validiran i tipiziran kao Python objekt—nula ručnog parsiranja.
3. A na strani TypeScripta?
Odgovor: Isti komfor sa Zodom: Zod shema definira i validira strukturu—jedan izvor istine za generiranje i tipizaciju.
4. Što učiniti kada izlaz ne poštuje shemu?
Odgovor: Sustavno validiraj i planiraj strategiju ponovnog pokušaja: ponovno zatraži s pogreškom u kontekstu ili elegantno degradiraj—nikada slijepo povjerenje u izlaz.
5. Kada je strukturirani izlaz neophodan?
Odgovor: Čim program troši odgovor bez ljudskog pregleda: ekstrakcija, integracije, pipelinei—format prestaje biti ljubaznost, postaje sučelje.
Deklarirana shema, ograničeno generiranje, validacija izlaza: trijada koja čini AI priključivim u stvarni softver.