Utilisation de client.chat.parse()
Šajā lapā
La méthode parse() : le cœur des sorties structurées personnalisées
client.chat.parse() est l’équivalent structuré de client.chat.complete(). Au lieu de renvoyer du texte libre ou du JSON brut que tu dois analyser toi-même, elle retourne directement un objet typé correspondant à ton modèle Pydantic. Ce changement peut sembler cosmétique, mais il élimine en réalité toute une couche de code.
Le contraste est plus clair lorsqu’on les compare côte à côte. Avec complete(), tu récupères une chaîne de caractères et tu la transformes toi-même. Avec parse(), l’objet arrive prêt à l’emploi, et le JSON brut reste disponible si tu en as besoin.
# Mode JSON — complete() renvoie du texte 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) # Analyse manuelle
# Personnalisé — parse() renvoie un objet typé
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema
)
obj: MonSchema = response.choices[0].message.parsed # Objet Pydantic
raw_json: str = response.choices[0].message.content # JSON brut également disponible
La différence réside dans l’accès à .parsed : un objet Pydantic directement utilisable, avec autocomplétion dans l’IDE et validation de type.
Un appel complet de bout en bout
L’exemple suivant détaille les cinq étapes d’une extraction réelle : définir le schéma avec des descriptions claires, créer le client, appeler parse(), utiliser l’objet retourné et récupérer la représentation JSON si nécessaire.
from mistralai.client import Mistral
from pydantic import BaseModel, Field
from typing import Optional
# 1. Définir le schéma
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. Créer le client
client = Mistral(api_key="your-api-key")
# 3. Appeler 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. Utiliser l'objet analysé
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. Le JSON brut est également disponible
raw = response.choices[0].message.content
print(f"\nRaw JSON: {raw}")
Remarque ce que le prompt système ne contient pas : aucune description du format attendu.
Le prompt système ajouté automatiquement
Le SDK s’en charge. Lorsque tu utilises parse(), Mistral ajoute automatiquement un préfixe au prompt système :
Your output should be an instance of a JSON object following this schema: { ... }
Ce préfixe contient le schéma JSON généré à partir de ton modèle Pydantic. Tu n’as pas besoin de décrire le format dans ton prompt : le SDK le fait pour toi. Cela libère ton message système pour qu’il fasse ce qu’il fait de mieux : fournir un contexte métier et définir des exigences de qualité, comme la précision des montants ou la gestion des données manquantes.
response = client.chat.parse(
model="mistral-large-latest",
messages=[
{
"role": "system",
# Inutile de décrire le format JSON, c'est automatique
# Concentre-toi sur le CONTEXTE et la QUALITÉ
"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 contre .content : deux usages distincts
L’objet typé, accessible via .parsed, est celui que tu manipules dans ta logique applicative. Il expose des attributs avec leurs types, prend en charge l’itération, se convertit en dictionnaire avec model_dump() et se sérialise avec model_dump_json().
book = response.choices[0].message.parsed
# Accès typé avec autocomplétion IDE
print(book.title) # str
print(book.authors) # list[str]
print(book.year) # Optional[int]
# Itérer sur les listes
for author in book.authors:
print(f" - {author}")
# Convertir en dictionnaire
book_dict = book.model_dump()
# Sérialiser en JSON
book_json = book.model_dump_json(indent=2)
Le JSON brut, quant à lui, reste utile aux frontières du système : pour la journalisation, le stockage en base de données ou la transmission de la réponse telle quelle à une autre API.
raw = response.choices[0].message.content
# Ceci est une chaîne JSON, utile pour :
# - La journalisation
# - Le stockage en base de données
# - L'envoi à une autre API
import json
data = json.loads(raw)
Ce qui peut encore échouer
Un schéma garanti ne rend pas ton code immunisé contre tout. L’API peut renvoyer une erreur réseau ou de service, et .parsed peut être None si la réponse a été interrompue. Le motif ci-dessous gère ces deux cas séparément : SDKError pour l’API, ValidationError pour le schéma, et ne réessaie qu’un nombre limité de fois.
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):
"""Extraction structurée avec gestion des erreurs."""
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
# Utilisation
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}")
Le réflexe observé avec le mode JSON s’applique toujours ici : une réponse coupée par max_tokens produit un objet incomplet ou nul, et finish_reason te l’indique avant que tu ne le découvres plus loin dans le 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éponse tronquée, augmente max_tokens
Galvenās atziņas
client.chat.parse()remplaceclient.chat.complete()pour les sorties structurées personnalisées.parsedrenvoie un objet Pydantic typé ;.contentrenvoie du JSON brut- Le schéma est automatiquement ajouté au prompt système : inutile de décrire le format
- Vérifie toujours
finish_reasonet gère les erreursSDKErroretValidationError - Utilise
model_dump()pour convertir l’objet analysé en dictionnaire Python