Používanie client.chat.parse()
Na tejto strane
Metóda parse(): Srdce vlastných štruktúrovaných výstupov
client.chat.parse() je štruktúrovaným ekvivalentom client.chat.complete(). Namiesto vrátenia voľného textu alebo surového JSON, ktorý si musíš spracovať sám, vráti priamo typizovaný objekt zodpovedajúci tvojmu modelu Pydantic. Táto zmena sa môže zdať len kozmetická, ale v skutočnosti eliminuje celú vrstvu kódu.
Rozdiel je najzrejmejší pri priamom porovnaní. Pri complete() získaš reťazec a musíš ho sám transformovať. Pri parse() dorazí objekt pripravený na použitie a surový JSON zostáva dostupný, ak ho potrebuješ.
# Režim JSON — complete() vráti text JSON
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
response_format={"type": "json_object"}
)
raw_json: str = response.choices[0].message.content
data = json.loads(raw_json) # Ručné spracovanie
# Vlastné — parse() vráti typizovaný objekt
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Objekt Pydantic
raw_json: str = response.choices[0].message.content # Surový JSON je tiež dostupný
Rozdiel spočíva v prístupe cez .parsed: priamo použiteľný objekt Pydantic s automatickým dopĺňaním v IDE a overením typov.
Kompletný end-to-end volanie
Nasledujúci príklad prechádza piatimi krokmi skutočnej extrakcie: definuj schému s jasnými popismi, vytvor klienta, zavolaj parse(), použij vrátený objekt a v prípade potreby získej reprezentáciu JSON.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definícia schémy
class BookInfo(BaseModel):
title: str = Field(description="Názov knihy")
authors: list[str] = Field(description="Zoznam autorov")
year: Optional[int] = Field(default=None, description="Rok vydania")
genre: str = Field(description="Hlavný literárny žáner")
summary: str = Field(description="Zhrnutie v 2-3 vetách")
# 2. Vytvorenie klienta
client = Mistral(api_key="your-api-key")
# 3. Volanie parse()
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Si expertný knihovník. Extrahuj informácie o spomenutej knihe."
},
{
"role": "user",
"content": "Páčila sa mi kniha '1984' od Georgea Orwella. Je to dystopický román vydaný v roku 1949, ktorý opisuje totalitnú spoločnosť pod neustálym dohľadom."
}
],
temperature=0
)
# 4. Použitie spracovaného objektu
book = response.choices[0].message.parsed
print(f"Názov: {book.title}")
print(f"Autori: {', '.join(book.authors)}")
print(f"Rok: {book.year}")
print(f"Žáner: {book.genre}")
print(f"Zhrnutie: {book.summary}")
# 5. Surový JSON je tiež dostupný
raw = response.choices[0].message.content
print(f"\nSurový JSON: {raw}")
Všimni si, čo systémový prompt neobsahuje: žiadny popis očakávaného formátu.
Automaticky pripojený systémový prompt
SDK sa o toto postará. Keď použiješ parse(), Mistral automaticky pridá prefix k systémovému promptu:
Your output should be an instance of a JSON object following this schema: { ... }
Tento prefix obsahuje schému JSON vygenerovanú z tvojho modelu Pydantic. Nemusíš v prompte popisovať formát – SDK to urobí za teba. To uvoľní tvoju systémovú správu, aby robila to, v čom je najlepšia: poskytovala obchodný kontext a stanovovala požiadavky na kvalitu, ako je presnosť čiastok alebo spôsob riešenia chýbajúcich údajov.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Nie je potrebné popisovať formát JSON – je automatický
# Zameraj sa na KONTEXT a KVALITU
"content": """Si expertný finančný analytik.
Buď presný pri čiastkach a percentách.
Ak údaje nie sú v texte dostupné, použij null."""
},
{"role": "user", "content": report_text}
],
response_format=FinancialReport
)
.parsed vs .content: Dva odlišné účely
Typizovaný objekt, dostupný cez .parsed, je to, s čím pracuješ v logike svojej aplikácie. Sprístupňuje atribúty s ich typmi, podporuje iteráciu, konvertuje na slovník pomocou model_dump() a serializuje sa pomocou model_dump_json().
book = response.choices[0].message.parsed
# Typizovaný prístup s automatickým dopĺňaním v IDE
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iterácia cez zoznamy
for author in book.authors:
print(f" - {author}")
# Konverzia na slovník
book_dict = book.model_dump()
# Serializácia do JSON
book_json = book.model_dump_json(indent=2)
Surový JSON je naopak užitočný na hraniciach systému: na logovanie, ukladanie do databázy alebo odovzdanie odpovede v nezmenenej podobe inej API.
raw = response.choices[0].message.content
# Toto je reťazec JSON, užitočný pre:
# - Logovanie
# - Ukladanie do databázy
# - Odoslanie inej API
import json
data = json.loads(raw)
Čo sa stále môže pokaziť
Zaručená schéma neznamená, že je tvoj kód imúnny voči všetkému. API môže vrátiť chybu siete alebo služby a .parsed môže byť None, ak bola odpoveď prerušená. Nižšie uvedený vzor rieši oba prípady samostatne – SDKError pre API, ValidationError pre schému – a opakuje pokus len obmedzený počet krát.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
from pydantic import ValidationError
client = Mistral(api_key="your-api-key")
def extract_structured(text: str, schema, max_retries: int = 2):
"""Štruktúrovaná extrakcia s ošetrením chýb."""
for attempt in range(max_retries + 1):
try:
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extrahuj požadované informácie."},
{"role": "user", "content": text}
],
response_format=schema,
temperature=0,
max_tokens=1024
)
parsed = response.choices[0].message.parsed
if parsed is None:
raise ValueError("Parsed je None – odpoveď mohla byť orezaná")
return parsed
except SDKError as e:
print(f"Chyba API (pokus {attempt + 1}): {e}")
if attempt == max_retries:
raise
except ValidationError as e:
print(f"Chyba overenia (pokus {attempt + 1}): {e}")
if attempt == max_retries:
raise
# Použitie
try:
book = extract_structured("'Malý princ' od Saint-Exupéryho, 1943", BookInfo)
print(f"Extrahované: {book.title} od {', '.join(book.authors)}")
except Exception as e:
print(f"Konečné zlyhanie: {e}")
Reflex viditeľný pri režime JSON platí aj tu: odpoveď orezaná podľa max_tokens vytvorí neúplný alebo nulový objekt a finish_reason ti to oznámi skôr, než to objavíš ďalej v pipeline.
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=256
)
if response.choices[0].finish_reason != "stop":
print(f"Upozornenie: finish_reason = {response.choices[0].finish_reason}")
# "length" = orezaná odpoveď, zvýš max_tokens
Kľúčové poznatky
client.chat.parse()nahrádzaclient.chat.complete()pre vlastné štruktúrované výstupy.parsedvráti typizovaný objekt Pydantic;.contentvráti surový JSON- Schéma sa automaticky pridá do systémového promptu – nie je potrebné popisovať formát
- Vždy kontroluj
finish_reasona ošetruj chybySDKErroraValidationError - Použi
model_dump()na konverziu spracovaného objektu na slovník Python