Réponse et utilisation
In questa pagina
Comprendre ce que renvoie l’API
La plupart des développeurs qui découvrent l’API ne lisent qu’une seule ligne de la réponse : le texte généré, et ignorent tout le reste. C’est une erreur. Chaque appel à /v1/chat/completions renvoie un objet JSON riche. C’est là que tu trouveras les données nécessaires pour suivre les coûts, détecter une réponse tronquée avant qu’elle n’atteigne l’utilisateur, et identifier un appel spécifique lors de l’ouverture d’un ticket de support.
Anatomie complète de la réponse
Commençons par les métadonnées. Ce sont les champs que tu vérifies rarement, mais que tu regretteras de ne pas avoir journalisés le jour où un incident survient :
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "What is machine learning?"}],
max_tokens=500
)
# Access metadata
print(f"Request ID : {response.id}")
print(f"Model used : {response.model}")
print(f"Created at : {response.created}")
Le champ id est un identifiant unique attribué à chaque requête. C’est la référence que tu fourniras au support technique, et celle qui te permet de relier une réclamation utilisateur à un appel spécifique dans tes journaux. Le champ model confirme quel modèle a été réellement utilisé. Cela compte plus que tu ne le penses lorsque tu appelles un alias -latest et que le comportement change du jour au lendemain sans aucune modification de code de ta part.
Le tableau choices
Le cœur de la réponse réside dans choices. Par défaut, ce tableau contient un seul élément. C’est à partir de là que tu extrais à la fois le texte et le verdict sur la façon dont la génération s’est terminée :
choice = response.choices[0]
# The generated message
print(choice.message.role) # "assistant"
print(choice.message.content) # The response text
# The index of this response in the array
print(choice.index) # 0
# The stop reason
print(choice.finish_reason) # "stop", "length", or "tool_calls"
Si tu demandes plusieurs réponses en utilisant le paramètre n, que nous aborderons dans la leçon 15, choices contiendra plusieurs éléments, et l’index redeviendra pertinent.
Valeurs de finish_reason
Ce champ détermine la fiabilité de ton application. Il existe trois valeurs possibles. stop signale que le modèle a terminé sa réponse naturellement. C’est le cas normal, où tu peux afficher le contenu sans réserve. length signifie que la génération a été coupée par max_tokens, donc la réponse est potentiellement incomplète : un résumé sans conclusion, ou une liste qui s’arrête au septième élément. Enfin, tool_calls indique que le modèle demande l’exécution d’un outil externe dans le cadre d’un appel de fonction, et c’est maintenant à toi de jouer.
Chacun de ces cas nécessite un traitement distinct, que tu dois écrire une fois pour toutes :
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Write a detailed report."}],
max_tokens=200
)
choice = response.choices[0]
if choice.finish_reason == "stop":
# Complete response — normal processing
result = choice.message.content
elif choice.finish_reason == "length":
# Truncated response — retry with more tokens or warn the user
print("Warning: The response was truncated.")
# Option: Retry with a higher max_tokens limit
# Option: Ask the model to continue
elif choice.finish_reason == "tool_calls":
# The model requests a tool call
for tool_call in choice.message.tool_calls:
print(f"Requested tool: {tool_call.function.name}")
Remarque que la branche length ne se contente pas de laisser passer le texte. Soit tu réessaies avec une limite plus élevée, soit tu demandes au modèle de continuer, soit tu avertis l’utilisateur. Ce que tu ne dois jamais faire, c’est afficher un texte tronqué comme s’il était complet.
L’objet usage — Suivre tes coûts
Le champ usage compte les jetons consommés par la requête, en séparant l’entrée de la sortie :
usage = response.usage
print(f"Input tokens : {usage.prompt_tokens}")
print(f"Output tokens : {usage.completion_tokens}")
print(f"Total : {usage.total_tokens}")
Cette distinction n’est pas cosmétique. Les modèles Mistral ont des tarifs différents pour l’entrée et la sortie. Une fonctionnalité qui envoie un long contexte pour obtenir trois mots en retour a un profil de coût complètement différent d’un long brouillon généré à partir d’une invite brève. Le calcul ne prend que quelques lignes :
# Hypothetical rates per million tokens (check current pricing)
RATE_INPUT = 2.0 # $/M tokens input
RATE_OUTPUT = 6.0 # $/M tokens output
cost_input = (usage.prompt_tokens / 1_000_000) * RATE_INPUT
cost_output = (usage.completion_tokens / 1_000_000) * RATE_OUTPUT
cost_total = cost_input + cost_output
print(f"Cost of this call: ${cost_total:.6f}")
Un seul appel coûte une fraction de centime, ce qui est faussement rassurant. Multiplie cela par le trafic réel d’une application, et la question devient : quelle fonctionnalité consomme quoi ? Pour y répondre, agrège les métriques d’utilisation dès ton tout premier déploiement. Journalise chaque appel avec le nom de la fonctionnalité qui l’a déclenché :
import json
from datetime import datetime
def log_usage(response, endpoint_name: str):
"""Logs usage metrics for each API call."""
log_entry = {
"timestamp": datetime.utcnow().isoformat(),
"endpoint": endpoint_name,
"model": response.model,
"prompt_tokens": response.usage.prompt_tokens,
"completion_tokens": response.usage.completion_tokens,
"total_tokens": response.usage.total_tokens,
"finish_reason": response.choices[0].finish_reason,
"request_id": response.id
}
with open("api_usage.jsonl", "a") as f:
f.write(json.dumps(log_entry) + "\n")
# Usage
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Hello"}]
)
log_usage(response, "main_chatbot")
Un fichier JSONL comme celui-ci, examiné après deux semaines, te dira sans ambiguïté quel écran de ton produit pèse le plus lourd sur la facture — et combien d’appels se terminent par length.
Contenu de la réponse
Le champ content du message de l’assistant peut prendre deux formes, exactement comme du côté de la requête :
# Simple form — string
content = response.choices[0].message.content
# "Machine learning is a branch of artificial intelligence..."
# Structured form — list of blocks (rare in standard chat)
# [{"type": "text", "text": "..."}]
En pratique, pour les appels standard Chat Completions, content est toujours une chaîne de caractères. La forme structurée est réservée aux réponses multimodales.
Mise en pratique
Rassemblons tout cela dans une fonction utilitaire — celle que tu copieras de projet en projet. Elle assemble les messages, effectue l’appel et renvoie un dictionnaire qui expose à la fois les métriques et le texte :
from mistralai.client import Mistral
def chat_complete(
client: Mistral,
prompt: str,
system: str = "",
model: str = "mistral-large-latest",
max_tokens: int = 1000
) -> dict:
"""Chat Completions call with error handling and metrics."""
messages = []
if system:
messages.append({"role": "system", "content": system})
messages.append({"role": "user", "content": prompt})
response = client.chat.complete(
model=model,
messages=messages,
max_tokens=max_tokens
)
return {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"tokens_in": response.usage.prompt_tokens,
"tokens_out": response.usage.completion_tokens,
"model": response.model,
"id": response.id
}
Le point clé réside dans ce que la fonction renvoie : jamais juste le texte. En remontant finish_reason, le nombre de jetons et l’ID de requête vers l’appelant, tu rends l’erreur la plus courante impossible : traiter une réponse coupée comme valide.
Punti chiave
- La réponse contient
choices(contenu),usage(jetons) et des métadonnées (id,model) - Vérifie toujours
finish_reason—lengthsignifie une réponse incomplète usagecompte les jetons d’entrée et de sortie séparément pour un suivi précis des coûts- Configure la journalisation des métriques dès ton premier déploiement en production
- Le champ
idest essentiel pour le débogage et le support technique