Korištenje client.chat.parse()
Na ovoj stranici
Metoda parse(): Srce prilagođenih strukturiranih izlaza
client.chat.parse() strukturirani je ekvivalent metode client.chat.complete(). Umjesto da vraća slobodan tekst ili sirovi JSON koji moraš ručno parsirati, ona izravno vraća tipizirani objekt koji odgovara tvom Pydantic modelu. Promjena može izgledati kozmetički, no zapravo eliminira čitav sloj koda.
Kontrast je najjasniji kada se prikaže usporedno. S complete() dohvaćaš niz znakova i sam ga transformiraš. S parse(), objekt stiže spreman za upotrebu, a sirovi JSON ostaje dostupan ako ti zatreba.
# JSON Mode — complete() vraća JSON tekst
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čno parsiranje
# Custom — parse() vraća tipizirani objekt
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Pydantic objekt
raw_json: str = response.choices[0].message.content # Sirovi JSON također dostupan
Razlika leži u pristupu putem .parsed: izravno upotrebljiv Pydantic objekt s IDE autokompletiranjem i validacijom tipova.
Potpuni poziv od kraja do kraja
Sljedeći primjer prolazi kroz pet koraka stvarne ekstrakcije: definiranje sheme s jasnim opisima, kreiranje klijenta, poziv parse(), korištenje vraćenog objekta i dohvat JSON reprezentacije ako je potrebno.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definiraj shemu
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. Kreiraj klijenta
client = Mistral(api_key="your-api-key")
# 3. Pozovi 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. Koristi parsirani objekt
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. Sirovi JSON je također dostupan
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Primijeti što sistemski prompt ne sadrži: nikakav opis očekivanog formata.
Automatski dodani sistemski prompt
SDK se brine za to. Kada koristiš parse(), Mistral automatski dodaje prefiks sistemskom promptu:
Your output should be an instance of a JSON object following this schema: { ... }
Ovaj prefiks sadrži JSON shemu generiranu iz tvog Pydantic modela. Ne moraš opisivati format u svom promptu – SDK to radi umjesto tebe. To oslobađa tvoju sistemsku poruku da radi ono u čemu je najbolja: pruža poslovni kontekst i postavlja zahtjeve kvalitete, poput preciznosti za iznose ili načina rukovanja nedostajućim podacima.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Nema potrebe opisivati JSON format – to je automatski
# Fokusiraj se na KONTEKST i KVALITETU
"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 naspram .content: Dvije različite namjene
Tipizirani objekt, dostupan putem .parsed, ono je čime manipuliraš u logici svoje aplikacije. On izlaže atribute s njihovim tipovima, podržava iteraciju, pretvara se u rječnik pomoću model_dump() i serijalizira s model_dump_json().
book = response.choices[0].message.parsed
# Tipizirani pristup s IDE autokompletiranjem
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Iteracija kroz liste
for author in book.authors:
print(f" - {author}")
# Pretvori u rječnik
book_dict = book.model_dump()
# Serijaliziraj u JSON
book_json = book.model_dump_json(indent=2)
S druge strane, sirovi JSON ostaje koristan na granicama sustava: za bilježenje (logging), pohranu u bazu podataka ili prosljeđivanje odgovora kakav jest drugom API-ju.
raw = response.choices[0].message.content
# Ovo je JSON niz, koristan za:
# - Bilježenje (Logging)
# - Pohranu u bazu podataka
# - Slanje drugom API-ju
import json
data = json.loads(raw)
Što još može poći po zlu
Zajamčena shema ne čini tvoj kod imunnim na sve. API može vratiti mrežnu pogrešku ili pogrešku usluge, a .parsed može biti None ako je odgovor prekinut. Donji obrazac zasebno obrađuje oba slučaja – SDKError za API i ValidationError za shemu – te pokušava ponovno izvršiti operaciju samo ograničen broj puta.
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):
"""Strukturirana ekstrakcija s rukovanjem pogreškama."""
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
# Upotreba
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}")
Refleks viđen kod JSON Modea i dalje vrijedi ovdje: odgovor prekinut zbog max_tokens proizvodi nepotpun ili null objekt, a finish_reason ti to govori prije nego što to otkriješ dalje u pipelineu.
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" = odsječen odgovor, povećaj max_tokens
Ključne točke
client.chat.parse()zamjenjujeclient.chat.complete()za prilagođene strukturirane izlaze.parsedvraća tipizirani Pydantic objekt;.contentvraća sirovi JSON- Shema se automatski dodaje sistemskom promptu – nema potrebe opisivati format
- Uvijek provjeri
finish_reasoni obradi pogreškeSDKErroriValidationError - Koristi
model_dump()za pretvorbu parsiranog objekta u Python rječnik