Gebruik van client.chat.parse()
Op deze pagina
De methode parse(): het hart van aangepaste gestructureerde uitvoer
client.chat.parse() is het gestructureerde equivalent van client.chat.complete(). In plaats van vrije tekst of ruwe JSON terug te geven die u zelf moet parseren, retourneert deze methode direct een getypt object dat overeenkomt met uw Pydantic-model. Het verschil lijkt misschien cosmetisch, maar het elimineert feitelijk een volledige codelaag.
Het contrast wordt het duidelijkst wanneer u ze naast elkaar bekijkt. Met complete() haalt u een string op die u zelf moet transformeren. Met parse() komt het object gebruiksklaar binnen, terwijl de ruwe JSON beschikbaar blijft mocht u deze nodig hebben.
# JSON-modus — complete() retourneert 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) # Handmatig parseren
# Aangepast — parse() retourneert een getypt object
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Pydantic-object
raw_json: str = response.choices[0].message.content # Ruwe JSON ook beschikbaar
Het verschil zit hem in de toegang via .parsed: een direct bruikbaar Pydantic-object met IDE-autocompletion en typevalidatie.
Een volledige end-to-end-aanroep
Het volgende voorbeeld doorloopt de vijf stappen van een echte extractie: definieer het schema met duidelijke beschrijvingen, maak de client aan, roep parse() aan, gebruik het geretourneerde object en haal indien nodig de JSON-representatie op.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Definieer het schema
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. Maak de client aan
client = Mistral(api_key="your-api-key")
# 3. Roep parse() aan
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. Gebruik het geparseerde object
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. Ruwe JSON is ook beschikbaar
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Merk op wat de systeemprompt niet bevat: geen beschrijving van het verwachte formaat.
De automatisch toegevoegde systeemprompt
De SDK regelt dit voor u. Wanneer u parse() gebruikt, voegt Mistral automatisch een voorvoegsel toe aan de systeemprompt:
Your output should be an instance of a JSON object following this schema: { ... }
Dit voorvoegsel bevat het JSON-schema dat gegenereerd is vanuit uw Pydantic-model. U hoeft het formaat niet in uw prompt te beschrijven; de SDK doet dit voor u. Hierdoor blijft uw systeembericht vrij om te doen waar het het beste in is: zakelijke context bieden en kwaliteitseisen stellen, zoals precisie bij bedragen of hoe om te gaan met ontbrekende gegevens.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Geen behoefte om het JSON-formaat te beschrijven—dit gaat automatisch
# Focus op CONTEXT en KWALITEIT
"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 versus .content: twee verschillende gebruiksscenario’s
Het getypte object, toegankelijk via .parsed, is wat u manipuleert in uw applicatielogica. Het stelt attributen met hun types bloot, ondersteunt iteratie, converteert naar een dictionary met model_dump() en serialiseert met model_dump_json().
book = response.choices[0].message.parsed
# Getypeerde toegang met IDE-autocompletion
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Itereer over lijsten
for author in book.authors:
print(f" - {author}")
# Converteer naar dictionary
book_dict = book.model_dump()
# Serialiseer naar JSON
book_json = book.model_dump_json(indent=2)
Ruwe JSON is daarentegen nog steeds nuttig aan systeemgrenzen: voor logging, database-opslag of om het antwoord ongewijzigd door te sturen naar een andere API.
raw = response.choices[0].message.content
# Dit is een JSON-string, nuttig voor:
# - Logging
# - Database-opslag
# - Verzenden naar een andere API
import json
data = json.loads(raw)
Wat er nog steeds mis kan gaan
Een gegarandeerd schema maakt uw code niet immuun voor alles. De API kan een netwerk- of servicefout retourneren, en .parsed kan None zijn als het antwoord werd onderbroken. Het onderstaande patroon behandelt beide gevallen afzonderlijk—SDKError voor de API, ValidationError voor het schema—en probeert het slechts een beperkt aantal keren opnieuw.
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):
"""Gestructureerde extractie met foutafhandeling."""
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
# Gebruik
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}")
De reflex die u kent van de JSON-modus geldt hier ook: een antwoord dat wordt afgekapt door max_tokens levert een onvolledig of null-object op, en finish_reason informeert u hierover voordat u het verder in de pipeline ontdekt.
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" = afgekapt antwoord, verhoog max_tokens
Belangrijkste punten
client.chat.parse()vervangtclient.chat.complete()voor aangepaste gestructureerde uitvoer.parsedretourneert een getypt Pydantic-object;.contentretourneert ruwe JSON- Het schema wordt automatisch aan de systeemprompt toegevoegd—beschrijf het formaat niet zelf
- Controleer altijd
finish_reasonen handelSDKError- enValidationError-fouten af - Gebruik
model_dump()om het geparseerde object om te zetten naar een Python-dictionary