Osvědčené postupy a shrnutí
Na této stránce
Shrnutí kurzu
Prošel jsi celý rozsah mechanismů strukturovaného výstupu, které nabízí Mistral API. Tato závěrečná lekce spojuje to podstatné pro každodenní práci: jak vybrat mezi dvěma přístupy, jaká nastavení jsou nezbytná, jaké jsou nejčastější pasti a co monitorovat, jakmile nasadíš řešení do produkce.
Výběr tvého přístupu
K rozhodnutí stačí čtyři otázky, které si polož v tomto pořadí. Máš definované schéma výstupu? Pokud ne, drž se režimu JSON Mode: jsi ve fázi průzkumu nebo prototypování a uzamykání datového modelu by bylo předčasné. Pokud ano, přejdi k další otázce.
Pracuješ v Pythonu nebo TypeScriptu? Pokud ano, jsou pro tebe připravena vlastní strukturovaná výstupní data (Custom Structured Outputs) pomocí knihoven Pydantic nebo Zod. Pokud ne, tvou cestou zůstává JSON Mode s ruční validací.
Jsi v produkci? Pokud ano, jsou vlastní strukturované výstupy (Custom Structured Outputs) vždy povinné. V opačném případě je pro prototypování více než dostatečný režim JSON Mode.
Mění se schéma často? Pokud se schéma stále vyvíjí, je zpočátku praktičtější JSON Mode, dokud se požadavky neustálí; pevné schéma naopak hovoří ve prospěch vlastních strukturovaných výstupů a spolehlivosti, kterou přinášejí.
Deset zlatých pravidel
Prvních pět se týká způsobu, jakým píšeš své volání. V produkci vždy nastav temperature=0: variabilita teploty je nepřítelem spolehlivosti a extrakce nepotřebuje kreativitu.
# Produkce: deterministické
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reprodukovatelnost
)
Vždy kontroluj finish_reason. Je to jediný indikátor, který tě upozorní na oříznutou odpověď dříve, než se ji pokusíš použít.
if response.choices[0].finish_reason != "stop":
# Odpověď je oříznuta — zvyšte max_tokens
raise ValueError(f"Neúplná odpověď: {response.choices[0].finish_reason}")
V režimu JSON Mode vždy instruuj model v promptu. Parametr garantuje syntaxi, nikoliv strukturu: je na tobě, abys definoval klíče a jejich typy.
# JSON Mode — prompt MUSÍ popisovat strukturu
messages = [
{
"role": "system",
"content": "Vrať JSON s klíči: name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
V režimu Custom dokumentuj svá pole. Přesný popis má větší váhu než dlouhý prompt a cestuje spolu se schématem v obou jazycích.
class Product(BaseModel):
name: str = Field(description="Obchodní název produktu")
price: float = Field(description="Cena v EUR bez DPH, zaokrouhleno na 2 desetinná místa")
const ProductSchema = z.object({
name: z.string().describe("Obchodní název produktu"),
price: z.number().describe("Cena v EUR bez DPH, zaokrouhleno na 2 desetinná místa"),
});
Odděl kontext od obsahu. Instrukce patří do systémové zprávy, data ke zpracování do uživatelské zprávy – nikdy naopak, jinak si model splete instrukci se zdrojovým textem.
messages = [
{"role": "system", "content": "Jsi extraktor dat. [Instrukce k formátu]"},
{"role": "user", "content": "[Text ke zpracování — ŽÁDNÉ instrukce k formátu zde]"}
]
Další dvě pravidla se týkají tvoje bezpečnostní sítě. Implementuj mechanismus opakování (retry): nikdy nedělej jediný pokus bez zálohy; opakování s zpětnou vazbou je minimálním vzorcem v produkci. A validuj nad rámec schématu, protože schéma garantuje strukturu, zatímco sémantická validace – meze, konzistence, obchodní logika – zůstává tvou odpovědností.
Poslední tři souvisejí s orchestrací. Vyber správný model pro správný případ použití: mistral-large-latest pro složité úlohy a extrakci více polí, mistral-small-latest pro jednoduchou klasifikaci a základní extrakci, ministral-8b-latest pro vysokou frekvenci a minimální latenci. Loguj každé volání v produkci, zaznamenávej použitý model, dobu trvání, finish_reason a výsledek: bez logů jsi slepý. Nakonec, neoptimalizuj prompt příliš brzy – začni jednoduše, měř, iteruj; předčasná optimalizace promptu je častou pastí, zatímco schéma a validace jsou skutečnými pákami.
Tři nákladné pasti
První je hodnota max_tokens, která je příliš nízká. JSON bude u dlouhých odpovědí oříznut a chyba se projeví až u velkých dokumentů, často až po nasazení do ostrého provozu.
# Nebezpečné — JSON bude u dlouhých odpovědí oříznut
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Příliš nízké pro komplexní schéma
)
Nastav max_tokens na základě očekávané velikosti tvého výstupu: faktura s 20 řádky vyžaduje více tokenů než jednoduchá klasifikace.
Druhou pastí je nenulová teplota, která činí tvé výsledky nereprodukovatelnými bez jakéhokoli přínosu pro úlohu extrakce.
# Nebezpečné v produkci — nereprodukovatelné výsledky
response = client.chat.parse(
...,
temperature=0.7 # Zbytečná variace pro extrakci
)
Třetí pastí je reflex používat jediný model. Nepoužívej mistral-large na všechno: binární klasifikace nevyžaduje nejmocnější model a ministral-8b odvede práci 5x rychleji za nižší cenu.
Co monitorovat
Čtyři metriky vypovídají o zdraví tvého pipeline. Míra úspěšnosti měří procento volání, která vrátí platný objekt na první pokus; míra opakování (retry rate) procento volání, která potřebovala druhou šanci. Latence P50/P95 udává medián doby odezvy a 95. percentil, což je vypovídající než průměr. Náklady na extrakci, vyjádřené ve spotřebovaných tokenech na volání, drží fakturu pod kontrolou.
U těchto metrik platí několik osvědčených prahových hodnot pro alerty: míra úspěšnosti pod 95 % оправдňuje žlutý alert, pod 85 % červený alert; latence P95 větší než 10 s si zaslouží vyšetřování; a otevřený jistič (circuit breaker) vyžaduje okamžitý alert.
Jak pokračovat dál
Čtyři směry přirozeně rozšiřují tento kurz. Volání funkcí (Function calling) využívá strukturované výstupy k napájení volání funkcí v agentovi. Streamování ti umožňuje přijímat strukturovaný výstup postupně, což je důležité u dlouhých odpovědí. Jemné ladění (Fine-tuning) upravuje model Mistral pro zlepšení kvality extrakce na tvých specifických datech. Evaluace konečně spočívá v nastavení automatického rámce založeného na zlatém datasetu a metrikách – to je to, co ti řekne, zda změna promptu věci skutečně zlepšila.
Kompletní pipeline
Následující kód spojuje postupy z kurzu do jediného toku: schéma popsané pole po poli, validátor, který odmítá skóre mimo rozsah, model přizpůsobený úloze, temperature=0, explicitní max_tokens, ověření finish_reason a logování pro oba možné výsledky.
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
Asi třicet řádků a máš komponentu, kterou lze bezpečně zapojit doprostřed systému: přesně to je to, co strukturované výstupy umožňují.
Klíčové poznatky
- V produkci používej vlastní strukturované výstupy (Custom Structured Outputs), pro prototypování režim JSON Mode
temperature=0, kontrolafinish_reasona opakování (retry) jsou nezbytné- Vyber model na základě složitosti úlohy a rozpočtu
- Monitoruj míru úspěšnosti, latenci a náklady
- Začni jednoduše, měř a poté optimalizuj
Ověř si své znalosti
Režim JSON Mode, schémata, opakování: máš strukturovaný výstup pod kontrolou?
1. JSON Mode vs vlastní strukturované výstupy: jaký je rozdíl?
Odpověď: JSON Mode garantuje syntakticky platný JSON; vlastní strukturované výstupy navíc vynucují tvé přesné schéma – pole, typy, strukturu: kompletní kontrakt.
2. Co poskytuje client.chat.parse() s knihovnou Pydantic?
Odpověď: Kompletní smyčku: schéma Pydantic deklaruje strukturu, API omezuje generování a odpověď dorazí již validovaná a typovaná jako Python objekt – žádné ruční parsování.
3. A co na straně TypeScriptu?
Odpověď: Stejné pohodlí se Zod: schéma Zod definuje a validuje strukturu – jediný zdroj pravdy pro generování i typování.
4. Co dělat, když výstup nerespektuje schéma?
Odpověď: Systematicky validuj a naplánuj strategii opakování: požádej znovu s chybou v kontextu, nebo graceful degrade – nikdy slepě nedůvěřuj výstupu.
5. Kdy je strukturovaný výstup nezbytný?
Odpověď: Jakmile program spotřebovává odpověď bez lidské kontroly: extrakce, integrace, pipeline – formát přestává být zdvořilostí, stává se rozhraním.
Deklarované schéma, omezené generování, validace výstupu: triáda, která činí AI zapojitelnou do reálného softwaru.