Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Použití metody client.chat.parse()

Lekce 8 z 12 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Metoda parse(): Srdce vlastních strukturovaných výstupů
  2. Kompletní volání od začátku do konce
  3. Automaticky připojený systémový prompt
  4. .parsed vs .content: Dva odlišné účely
  5. Co se stále může pokazit
  6. Klíčové poznatky

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() nahrazuje client.chat.complete() pro vlastní strukturované výstupy
  • .parsed vrací typizovaný objekt Pydantic; .content vrací surový JSON
  • Schéma se automaticky přidá do systémového promptu – není třeba popisovat formát
  • Vždy kontroluj finish_reason a ošetřuj chyby SDKError a ValidationError
  • Použij model_dump() pro převod parsovaného objektu na slovník Python