Použití metody client.chat.parse()
Na této stránce
Metoda parse(): Srdce vlastních strukturovaných výstupů
client.chat.parse() je strukturovaným ekvivalentem client.chat.complete(). Místo návratu volného textu nebo surového JSONu, který si musíš parsovat sám, vrací přímo typizovaný objekt odpovídající tvému modelu Pydantic. Změna může vypadat jen kosmeticky, ale ve skutečnosti eliminuje celou vrstvu kódu.
Rozdíl je nejzřetelnější při porovnání vedle sebe. S complete() získáš řetězec a musíš jej sám transformovat. S parse() dorazí objekt připravený k použití a surový JSON zůstává k dispozici, pokud ho potřebuješ.
# Režim JSON — complete() vrací 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í parsování
# Vlastní — parse() vrací 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 také k dispozici
Rozdíl spočívá v přístupu přes .parsed: přímo použitelný objekt Pydantic s automatickým doplňováním v IDE a validací typů.
Kompletní volání od začátku do konce
Následující příklad prochází pěti kroky skutečné extrakce: definuj schéma s jasnými popisy, vytvoř klienta, zavolej parse(), použij vrácený objekt a případně získej reprezentaci JSON.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definice schématu
class BookInfo(BaseModel):
title: str = Field(description="Book title")
authors: list[str] = Field(description="List of authors")
year: Optional[int] = Field(default=None, description="Publication year")
genre: str = Field(description="Main literary genre")
summary: str = Field(description="Summary in 2-3 sentences")
# 2. Vytvoření klienta
client = Mistral(api_key="your-api-key")
# 3. Volání parse()
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "You are an expert librarian. Extract information about the mentioned book."
},
{
"role": "user",
"content": "I loved '1984' by George Orwell. It's a dystopian novel published in 1949 describing a totalitarian society under constant surveillance."
}
],
temperature=0
)
# 4. Použití parsovaného objektu
book = response.choices[0].message.parsed
print(f"Title: {book.title}")
print(f"Authors: {', '.join(book.authors)}")
print(f"Year: {book.year}")
print(f"Genre: {book.genre}")
print(f"Summary: {book.summary}")
# 5. Surový JSON je také k dispozici
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Všimni si, co systémový prompt neobsahuje: žádný popis očekávaného formátu.
Automaticky připojený systémový prompt
SDK se o to postará. Když použiješ parse(), Mistral automaticky přidá prefix k systémovému promptu:
Your output should be an instance of a JSON object following this schema: { ... }
Tento prefix obsahuje schéma JSON vygenerované z tvého modelu Pydantic. Nemusíš popisovat formát ve svém promptu – udělá to SDK za tebe. To uvolní tvou systémovou zprávu pro to, co umí nejlépe: poskytovat obchodní kontext a stanovovat požadavky na kvalitu, jako je přesnost částek nebo způsob zpracování chybějících dat.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Není třeba popisovat formát JSON – je automatický
# Zaměř se na KONTEXT a KVALITU
"content": """You are an expert financial analyst.
Be precise with amounts and percentages.
If data is not available in the text, use null."""
},
{"role": "user", "content": report_text}
],
response_format=FinancialReport
)
.parsed vs .content: Dva odlišné účely
Typizovaný objekt, přístupný přes .parsed, je to, s čím pracuješ v logice své aplikace. Zpřístupňuje atributy s jejich typy, podporuje iteraci, převádí se na slovník pomocí model_dump() a serializuje se pomocí model_dump_json().
book = response.choices[0].message.parsed
# Typizovaný přístup s automatickým doplňováním v IDE
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iterace přes seznamy
for author in book.authors:
print(f" - {author}")
# Převod na slovník
book_dict = book.model_dump()
# Serializace do JSON
book_json = book.model_dump_json(indent=2)
Surový JSON je naopak užitečný na hranicích systému: pro logování, ukládání do databáze nebo předání odpovědi „tak jak je“ dalšímu API.
raw = response.choices[0].message.content
# Toto je řetězec JSON, užitečný pro:
# - Logování
# - Ukládání do databáze
# - Odeslání jinému API
import json
data = json.loads(raw)
Co se stále může pokazit
Zaručené schéma neznamená, že je tvůj kód imunní vůči všemu. API může vrátit chybu sítě nebo služby a .parsed může být None, pokud byla odpověď přerušena. Níže uvedený vzor řeší oba případy samostatně – SDKError pro API, ValidationError pro schéma – a opakuje pokus pouze omezený početkrá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):
"""Strukturovaná extrakce s ošetřením chyb."""
for attempt in range(max_retries + 1):
try:
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Extract the requested information."},
{"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 is None—response may be truncated")
return parsed
except SDKError as e:
print(f"API error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
except ValidationError as e:
print(f"Validation error (attempt {attempt + 1}): {e}")
if attempt == max_retries:
raise
# Použití
try:
book = extract_structured("'The Little Prince' by Saint-Exupéry, 1943", BookInfo)
print(f"Extracted: {book.title} by {', '.join(book.authors)}")
except Exception as e:
print(f"Final failure: {e}")
Reflex viděný u režimu JSON platí i zde: odpověď useknutá pomocí max_tokens vytvoří neúplný nebo null objekt a finish_reason ti to sdělí dříve, než to objevíš dále 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"Warning: finish_reason = {response.choices[0].finish_reason}")
# "length" = useknutá odpověď, zvyšte max_tokens
Klíčové poznatky
client.chat.parse()nahrazujeclient.chat.complete()pro vlastní strukturované výstupy.parsedvrací typizovaný objekt Pydantic;.contentvrací surový JSON- Schéma se automaticky přidá do systémového promptu – není třeba popisovat formát
- Vždy kontroluj
finish_reasona ošetřuj chybySDKErroraValidationError - Použij
model_dump()pro převod parsovaného objektu na slovník Python