Salt la conținutul principal
Română— Alege o limbă
Meniu

Utilizarea metodei client.chat.parse()

Lecția 8 din 12 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Metoda parse(): Inima ieșirilor structurate personalizate
  2. Un apel complet de la capăt la capăt
  3. Promptul de sistem adăugat automat
  4. .parsed vs .content: Două utilizări distincte
  5. Ce poate totuși să eșueze
  6. Puncte cheie

Metoda parse(): Inima ieșirilor structurate personalizate

client.chat.parse() este echivalentul structurat al metodei client.chat.complete(). În loc să returneze text liber sau JSON brut pe care trebuie să îl analizați manual, aceasta returnează direct un obiect tipat care corespunde modelului dumneavoastră Pydantic. Deși diferența poate părea cosmetică, ea elimină de fapt un întreg strat de cod.

Contrastul este cel mai clar atunci când sunt privite alăturate. Cu complete(), recuperați un șir de caractere pe care trebuie să îl transformați singuri. Cu parse(), obiectul sosește gata de utilizare, iar JSON-ul brut rămâne disponibil dacă aveți nevoie de el.

# Mod JSON — complete() returnează 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)  # Analiză manuală

# Personalizat — parse() returnează un obiect tipat
response = client.chat.parse(
    model="mistral-large-latest",
    messages=messages,
    response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed  # Obiect Pydantic
raw_json: str = response.choices[0].message.content   # JSON brut disponibil și el

Diferența constă în accesarea atributului .parsed: un obiect Pydantic direct utilizabil, cu autocompletare în IDE și validare de tip.

Un apel complet de la capăt la capăt

Următorul exemplu parcurge cei cinci pași ai unei extrageri reale: definirea schemei cu descrieri clare, crearea clientului, apelarea metodei parse(), utilizarea obiectului returnat și recuperarea reprezentării JSON dacă este necesar.

from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional

# 1. Definirea schemei
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. Crearea clientului
client = Mistral(api_key="your-api-key")

# 3. Apelarea metodei 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. Utilizarea obiectului analizat (parsed)
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. JSON-ul brut este, de asemenea, disponibil
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")

Observați ce nu conține promptul de sistem: nicio descriere a formatului așteptat.

Promptul de sistem adăugat automat

SDK-ul se ocupă de acest aspect. Atunci când utilizați parse(), Mistral adaugă automat un prefix la promptul de sistem:

Your output should be an instance of a JSON object following this schema: { ... }

Acest prefix conține schema JSON generată din modelul dumneavoastră Pydantic. Nu trebuie să descrieți formatul în promptul dumneavoastră – SDK-ul o face pentru dumneavoastră. Acest lucru eliberează mesajul de sistem pentru a face ceea ce face mai bine: să ofere context de afaceri și să stabilească cerințe de calitate, cum ar fi precizia pentru sume sau modul de gestionare a datelor lipsă.

response = client.chat.parse(
    model="mistral-large-latest",
    messages=[
        {
            "role": "system",
            # Nu este nevoie să descrieți formatul JSON – este automat
            # Concentrați-vă pe CONTEXT și CALITATE
            "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: Două utilizări distincte

Obiectul tipat, accesibil prin .parsed, este ceea ce manipulați în logica aplicației dumneavoastră. Acesta expune atribute cu tipurile lor, suportă iterarea, se convertește într-un dicționar cu model_dump() și se serializează cu model_dump_json().

book = response.choices[0].message.parsed

# Acces tipat cu autocompletare în IDE
print(book.title)        # str
print(book.authors)      # list[str]
print(book.year)         # Optional[int]

# Iterare peste liste
for author in book.authors:
    print(f"  - {author}")

# Conversie în dicționar
book_dict = book.model_dump()

# Serializare în JSON
book_json = book.model_dump_json(indent=2)

JSON-ul brut, pe de altă parte, rămâne util la limitele sistemului: pentru jurnalizare (logging), stocare în baza de date sau transmiterea răspunsului ca atare către un alt API.

raw = response.choices[0].message.content

# Acesta este un șir JSON, util pentru:
# - Jurnalizare
# - Stocare în baza de date
# - Trimitere către un alt API

import json
data = json.loads(raw)

Ce poate totuși să eșueze

O schemă garantată nu vă face codul imun la totul. API-ul poate returna o eroare de rețea sau de serviciu, iar .parsed poate fi None dacă răspunsul a fost întrerupt. Modelul de mai jos gestionează ambele cazuri separat – SDKError pentru API și ValidationError pentru schemă – și reîncearcă doar de un număr limitat de ori.

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):
    """Extragere structurată cu gestionarea erorilor."""
    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

# Utilizare
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}")

Reflexul observat cu Modului JSON se aplică și aici: un răspuns tăiat de max_tokens produce un obiect incomplet sau nul, iar finish_reason vă indică acest lucru înainte de a-l descoperi mai departe în 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" = răspuns trunchiat, măriți max_tokens

Puncte cheie

  • client.chat.parse() înlocuiește client.chat.complete() pentru ieșirile structurate personalizate
  • .parsed returnează un obiect Pydantic tipat; .content returnează JSON brut
  • Schema este adăugată automat la promptul de sistem – nu este nevoie să descrieți formatul
  • Verificați întotdeauna finish_reason și gestionați erorile SDKError și ValidationError
  • Utilizați model_dump() pentru a converti obiectul analizat într-un dicționar Python