Režim JSON vs. vlastní strukturované výstupy
Na této stránce
Dva přístupy, dvě filozofie
API Mistral nabízí dva odlišné mechanismy pro generování strukturovaných výstupů. Nesoutěží spolu; slouží různým fázím životního cyklu projektu. Tvá volba závisí na tvém případě použití, technologickém stacku a úrovni spolehlivosti, kterou potřebuješ udržet.
Režim JSON: flexibilita
Režim JSON je nejjednodušší přístup. V požadavku pouze povolíš parametr a Mistral zaručí, že výstup bude platný JSON. To je vše. Model si může svobodně vybrat strukturu: klíče, typy i hloubku vnoření. Požadovaný formát navrhneš prostřednictvím promptu, ale schéma není technicky svázáno žádnými omezeními.
# Režim JSON — strukturu volí model
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"}
)
Tento minimalismus je jeho hlavní silou: stačí přidat jeden parametr, nemusíš předem definovat žádné schéma a získáš maximální flexibilitu při zkoumání problému nebo rychlém prototypování. Nevýhoda je však symetrická. Nic nezaručuje přesnou strukturu přijatého JSONu: model může vynechat pole, přidat jiné nebo přejmenovat klíč z jednoho volání na druhé. Validace na straně klienta se proto stává povinností a to je kód, který musíš napsat a sám udržovat.
Vlastní strukturované výstupy: rigoróznost
Vlastní strukturované výstupy přesouvají toto omezení na stranu API. Definuješ přesné schéma – pomocí Pydantic v Pythonu nebo Zod v TypeScriptu – a Mistral donutí model, aby se ho přesně držel.
from pydantic import BaseModel
class Analyse(BaseModel):
sentiment: str
score: float
keywords: list[str]
# Vlastní — schéma je vynuceno
response = client.chat.parse(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Analyze this text."}],
response_format=Analyse
)
Přínos je okamžitý: každé pole je přítomno se správným typem a zpět získáš analyzovaný objekt připravený k použití – instanci modelu Pydantic nebo Zod – s plným automatickým doplňováním v IDE. Toto je režim pro produkci a kritické pipeline. Kompromis lze shrnout do jedné věty: musíš předem definovat datový model, což činí exploraci méně flexibilní a ukládá ti mírnou počáteční zátěž ve vývoji.
Podrobné srovnání
| Kritérium | Režim JSON | Vlastní strukturované výstupy |
|---|---|---|
| Aktivace | response_format: {"type": "json_object"} | response_format: MyModel (Pydantic/Zod) |
| Metoda API | client.chat.complete() | client.chat.parse() |
| Záruka schématu | Ne – pouze platný JSON | Ano – vynuceno přesné schéma |
| Automatické parsování | Ne – ruční json.loads() | Ano – .parsed vrací typovaný objekt |
| Flexibilita | Vysoká – volná struktura | Nízká – pevná struktura |
| Ideální případ použití | Prototypování, explorace, proměnlivá schémata | Produkce, kritické pipeline, API |
| Požadovaná validace | Ano – povinná na straně klienta | Minimální – práci odvede schéma |
Jak se rozhodnout v praxi
Tři signály ukazují směrem k režimu JSON. Prvním je fáze projektu: když prototypuješ a schéma ještě není stabilní, uzamčení datového modelu tě zpomalí, aniž by přineslo hodnotu. Druhým je povaha úkolu: pokud se struktura výstupu legitimně mění na základě vstupu, jako je tomu u explorativní analýzy, kde relevantní dimenze nejsou předem známé, pevná struktura by byla svěrací kazajkou. Třetím je technický aspekt: v jazyce bez podpory Pydantic nebo Zod zůstává režim JSON tvou jedinou vstupní branou.
Vlastní strukturované výstupy převezmou vedení, jakmile se situace obrátí. Jsi v produkci a neúspěšná extrakce má reálné náklady; schéma výstupu je známé a stabilní; pracuješ v Pythonu nebo TypeScriptu; a chceš manipulovat s typovanými objekty místo anonymních slovníků. Konkrétně pipeline, která celý den klasifikuje supportní ticket pomocí stejných čtyř polí, nemá žádný důvod zůstávat v režimu JSON.
To odpovídá oficiální dokumentaci Mistral, která doporučuje používat vlastní strukturované výstupy vždy, když je to možné. Režim JSON zůstává dobrým vstupním bodem, ale vlastní výstupy nabízejí vyšší spolehlivost a výrazně redukují množství validačního kódu na straně klienta.
Klíčové poznatky
- Režim JSON = zaručeně platný JSON, volná struktura, snadná aktivace
- Vlastní strukturované výstupy = zaručeně přesné schéma, automatické parsování, ideální pro produkci
- Začni s režimem JSON pro prototypování, přejdi na vlastní výstupy pro produkci
- Oba přístupy se doplňují, nejsou vzájemně výlučné