Bonnes pratiques et récapitulatif
På denna sida
Récapitulatif du cours
Tu as exploré toute la gamme des mécanismes de sortie structurée offerts par l’API Mistral. Cette dernière leçon rassemble ce qui fait la différence au quotidien : comment choisir entre les deux approches, les paramètres non négociables, les pièges les plus courants et ce qu’il faut surveiller une fois en production.
Choisir ton approche
Quatre questions suffisent pour décider, dans cet ordre. As-tu un schéma de sortie défini ? Si la réponse est non, reste sur le mode JSON : tu es en phase d’exploration ou de prototypage, et figer un modèle de données serait prématuré. Si oui, passe à la question suivante.
Travailles-tu en Python ou en TypeScript ? Si oui, les sorties structurées personnalisées sont prêtes pour toi avec Pydantic ou Zod. Sinon, le mode JSON avec validation manuelle reste ta voie.
Es-tu en production ? Si oui, les sorties structurées personnalisées sont obligatoires, toujours. Sinon, le mode JSON est plus que suffisant pour le prototypage.
Le schéma change-t-il fréquemment ? Un schéma encore en évolution rend le mode JSON plus pratique dans un premier temps, jusqu’à ce que les exigences se stabilisent ; un schéma fixe plaide pour les sorties structurées personnalisées et la fiabilité qu’elles apportent.
Les dix règles d’or
Les cinq premières concernent la façon dont tu écris tes appels. Définis toujours temperature=0 en production : la variabilité de la température est l’ennemie de la fiabilité, et l’extraction n’a aucun besoin de créativité.
# Production : déterministe
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Reproductibilité
)
Vérifie toujours finish_reason. C’est le seul indicateur qui t’avertit d’une réponse tronquée avant que tu ne tentes de l’utiliser.
if response.choices[0].finish_reason != "stop":
# La réponse est tronquée — augmentez max_tokens
raise ValueError(f"Réponse incomplète : {response.choices[0].finish_reason}")
En mode JSON, instruis toujours le modèle dans le prompt. Le paramètre garantit la syntaxe, pas la structure : c’est à toi de préciser les clés et leurs types.
# Mode JSON — le prompt DOIT décrire la structure
messages = [
{
"role": "system",
"content": "Renvoie un JSON avec les clés : name (string), age (number), city (string)."
},
{"role": "user", "content": text}
]
En mode personnalisé, documente tes champs. Une description précise vaut plus qu’un long prompt, et elle voyage avec le schéma dans les deux langages.
class Product(BaseModel):
name: str = Field(description="Nom commercial du produit")
price: float = Field(description="Prix en EUR hors taxe, arrondi à 2 décimales")
const ProductSchema = z.object({
name: z.string().describe("Nom commercial du produit"),
price: z.number().describe("Prix en EUR hors taxe, arrondi à 2 décimales"),
});
Sépare le contexte du contenu. Les instructions vivent dans le message système, les données à traiter dans le message utilisateur — jamais l’inverse, sinon le modèle confondra l’instruction avec le texte source.
messages = [
{"role": "system", "content": "Tu es un extracteur de données. [Instructions de format]"},
{"role": "user", "content": "[Texte à traiter — AUCUNE instruction de format ici]"}
]
Les deux règles suivantes concernent ton filet de sécurité. Mets en place un mécanisme de nouvelle tentative (retry) : ne fais jamais un seul appel sans sauvegarde ; la nouvelle tentative avec rétroaction est le motif minimal en production. Et valide au-delà du schéma, car le schéma garantit la structure tandis que la validation sémantique — bornes, cohérence, logique métier — reste ta responsabilité.
Les trois dernières concernent l’orchestration. Choisis le bon modèle pour le bon cas d’usage : mistral-large-latest pour les tâches complexes et l’extraction multi-champs, mistral-small-latest pour la classification simple et l’extraction basique, ministral-8b-latest pour la haute fréquence et la latence minimale. Journalise chaque appel en production, en enregistrant le modèle utilisé, la durée, finish_reason et le résultat : sans journaux, tu es aveugle. Enfin, n’optimise pas trop tôt le prompt — commence simple, mesure, itère ; l’optimisation prématurée du prompt est un piège courant, alors que le schéma et la validation sont les vrais leviers.
Trois pièges coûteux
Le premier est une valeur max_tokens trop faible. Le JSON sera tronqué sur les réponses longues, et l’erreur ne se manifestera que sur des documents volumineux, souvent après la mise en ligne.
# Dangereux — le JSON sera tronqué pour les réponses longues
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Trop faible pour un schéma complexe
)
Définis max_tokens en fonction de la taille attendue de ta sortie : une facture avec 20 lignes nécessite plus de jetons qu’une simple classification.
Le deuxième est une température non nulle, qui rend tes résultats non reproductibles pour un gain nul sur une tâche d’extraction.
# Dangereux en production — résultats non reproductibles
response = client.chat.parse(
...,
temperature=0.7 # Variation inutile pour l'extraction
)
Le troisième est le réflexe d’utiliser un seul modèle. N’utilise pas mistral-large pour tout : une classification binaire ne nécessite pas le modèle le plus puissant, et ministral-8b fera le travail 5 fois plus vite pour un coût moindre.
Ce qu’il faut surveiller
Quatre métriques indiquent la santé de ton pipeline. Le taux de réussite mesure le pourcentage d’appels renvoyant un objet valide du premier coup ; le taux de nouvelle tentative, le pourcentage d’appels ayant nécessité une seconde chance. La latence P50/P95 donne le temps de réponse médian et le 95e percentile, ce qui est plus révélateur que la moyenne. Le coût par extraction, exprimé en jetons consommés par appel, maintient la facture sous contrôle.
Sur ces métriques, quelques seuils d’alerte tiennent la route : un taux de réussite inférieur à 95 % justifie une alerte jaune, inférieur à 85 % une alerte rouge ; une latence P95 supérieure à 10 s warrant une investigation ; et un disjoncteur ouvert appelle une alerte immédiate.
Aller plus loin
Quatre directions prolongent naturellement ce cours. L’appel de fonctions utilise les sorties structurées pour alimenter des appels de fonctions dans un agent. Le streaming te permet de recevoir la sortie structurée progressivement, ce qui compte pour les réponses longues. Le fine-tuning ajuste un modèle Mistral pour améliorer la qualité de l’extraction sur tes données spécifiques. L’évaluation, enfin, consiste à mettre en place un cadre automatique basé sur un jeu de données de référence et des métriques — c’est ce qui te dira si une modification du prompt améliore réellement les choses.
Un pipeline complet
Le code suivant rassemble les pratiques du cours en un seul flux : un schéma décrit champ par champ, un validateur qui rejette les scores hors limites, un modèle adapté à la tâche, temperature=0, un max_tokens explicite, une vérification de finish_reason et une journalisation pour les deux issues possibles.
from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time
logger = logging.getLogger("pipeline")
class CustomerFeedback(BaseModel):
sentiment: str = Field(description="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 and 1.0")
category: str = Field(description="product, service, delivery, price, or other")
action_required: bool = Field(description="True if action is required")
summary: str = Field(description="One-sentence summary")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Score out of bounds: {v}")
return v
def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
start = time.time()
try:
response = client.chat.parse(
model="mistral-small-latest",
messages=[
{"role": "system", "content": "Analyze customer feedback."},
{"role": "user", "content": text}
],
response_format=CustomerFeedback,
temperature=0,
max_tokens=256
)
assert response.choices[0].finish_reason == "stop"
result = response.choices[0].message.parsed
logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
raise
Une trentaine de lignes, et tu as un composant qui peut être branché en toute sécurité au cœur d’un système : c’est exactement ce que rendent possible les sorties structurées.
Viktiga punkter
- Utilise les sorties structurées personnalisées en production, le mode JSON pour le prototypage
temperature=0, la vérification definish_reasonet la nouvelle tentative sont non négociables- Choisis le modèle en fonction de la complexité de la tâche et du budget
- Surveille le taux de réussite, la latence et le coût
- Commence simple, mesure, puis optimise
Teste tes connaissances
Mode JSON, schémas, nouvelles tentatives : la sortie structurée sous contrôle ?
1. Mode JSON vs Sorties structurées personnalisées : quelle est la différence ?
Réponse : Le mode JSON garantit un JSON syntaxiquement valide ; les Sorties structurées personnalisées imposent en plus ton schéma exact — champs, types, structure : le contrat complet.
2. Que fournit client.chat.parse() avec Pydantic ?
Réponse : La boucle complète : le schéma Pydantic déclare la structure, l’API contraint la génération, et la réponse arrive déjà validée et typée comme un objet Python — zéro analyse manuelle.
3. Et côté TypeScript ?
Réponse : Le même confort avec Zod : le schéma Zod définit et valide la structure — une source unique de vérité pour la génération et le typage.
4. Que faire lorsque la sortie ne respecte pas le schéma ?
Réponse : Valider systématiquement et planifier une stratégie de nouvelle tentative : redemander avec l’erreur dans le contexte, ou dégrader gracieusement — jamais de confiance aveugle dans la sortie.
5. Quand la sortie structurée est-elle indispensable ?
Réponse : Dès qu’un programme consomme la réponse sans revue humaine : extraction, intégrations, pipelines — le format cesse d’être une courtoisie, il devient une interface.
Schéma déclaré, génération contrainte, validation de la sortie : la triade qui rend l’IA enfichable dans de vrais logiciels.