Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Réponse et utilisation

Lezione 4 di 16 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Comprendre ce que renvoie l’API
  2. Anatomie complète de la réponse
  3. Le tableau choices
  4. Valeurs de finish_reason
  5. L’objet usage — Suivre tes coûts
  6. Contenu de la réponse
  7. Mise en pratique
  8. Punti chiave

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 — length signifie une réponse incomplète
  • usage compte 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 id est essentiel pour le débogage et le support technique