Salt la conținutul principal
Română— Alege o limbă
Meniu

Bonnes pratiques de production

Lecția 16 din 16 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. De la preuve de concept au déploiement
  2. Authentification et versioning des modèles
  3. Un client qui gère les incidents
  4. Suivez les coûts en temps réel
  5. Validez aux deux extrémités
  6. Maîtrisez la fenêtre de contexte
  7. Ce que vous retenez de ce cours
  8. Puncte cheie
  9. Testez vos connaissances

De la preuve de concept au déploiement

Vous maîtrisez désormais tous les paramètres de l’API Chat Completions. La partie la plus délicate reste à venir : combler le fossé entre un notebook fonctionnel et un service utilisé par d’autres sans votre intervention. Cette dernière leçon consolide l’ensemble du cours en une liste de contrôle de production exploitable, puis vous indique la voie vers les cours de suivi.

Authentification et versioning des modèles

Deux décisions précèdent la première ligne de logique métier. La première concerne la clé API : elle réside dans une variable d’environnement, jamais dans le code, et une assertion au démarrage vaut mieux qu’un None qui se propage sur trois niveaux pour aboutir à un message d’erreur incompréhensible. Prévoyez également la rotation : créez la nouvelle clé, déployez-la, puis révoquez l’ancienne, dans cet ordre, si vous souhaitez éviter de mettre le service hors ligne.

import os

# TOUJOURS : Clé API dans une variable d'environnement
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY non définie"

# JAMAIS : Clé codée en dur dans le code
# api_key = "sk-abc123..."  # INTERDIT en production

# TOUJOURS : Rotation régulière des clés
# Créer une nouvelle clé, la déployer, puis révoquer l'ancienne

La seconde décision concerne l’identifiant du modèle. En développement, -latest vous apporte des améliorations sans effort. En production, ce même alias signifie qu’un changement de version chez le fournisseur peut altérer le comportement de votre application sans avertissement, un mardi matin, sans aucune trace de commit pour l’expliquer. Épinglez la version.

# DÉVELOPPEMENT — dernière version
model = "mistral-large-latest"

# PRODUCTION — version fixe pour la reproductibilité
model = "mistral-large-2512"

# Pourquoi ? Un changement "latest" peut altérer le comportement
# de votre application sans avertissement.

Un client qui gère les incidents

Le cœur d’une intégration en production n’est pas l’appel API, mais tout ce qui l’entoure. La classe ci-dessous regroupe trois responsabilités en un seul point de contrôle : nouvelle tentative avec backoff exponentiel sur les erreurs 429, courte pause sur les erreurs serveur, et escalade immédiate des erreurs client qu’aucune nouvelle tentative ne saurait corriger. Elle normalise également la réponse dans un dictionnaire stable — contenu, finish_reason, usage, modèle, ID — afin que le reste de votre code ne dépende plus de la forme exacte de l’objet retourné par le SDK. Le seul logger.warning sur les troncatures justifie cette encapsulation : c’est le seul moyen de découvrir qu’un paramètre max_tokens est trop restrictif avant que les utilisateurs ne le signalent.

from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging

logger = logging.getLogger(__name__)

class MistralClient:
    """Client de production avec retry, timeout et logging."""

    def __init__(self, api_key: str, max_retries: int = 3):
        self.client = Mistral(api_key=api_key)
        self.max_retries = max_retries

    def complete(self, messages: list, **kwargs) -> dict:
        for attempt in range(self.max_retries):
            try:
                response = self.client.chat.complete(
                    messages=messages,
                    **kwargs
                )

                result = {
                    "content": response.choices[0].message.content,
                    "finish_reason": response.choices[0].finish_reason,
                    "usage": {
                        "prompt": response.usage.prompt_tokens,
                        "completion": response.usage.completion_tokens,
                        "total": response.usage.total_tokens,
                    },
                    "model": response.model,
                    "id": response.id,
                }

                # Alerter si la réponse est tronquée
                if result["finish_reason"] == "length":
                    logger.warning(f"Réponse tronquée — req_id={response.id}")

                return result

            except SDKError as e:
                if e.status_code == 429:
                    wait = 2 ** attempt
                    logger.warning(f"Limite de débit, tentative {attempt+1}/{self.max_retries} dans {wait}s")
                    time.sleep(wait)
                elif e.status_code >= 500:
                    logger.error(f"Erreur serveur {e.status_code}, tentative {attempt+1}")
                    time.sleep(1)
                else:
                    logger.error(f"Erreur client {e.status_code}: {e.message}")
                    raise

        raise Exception(f"Échec après {self.max_retries} tentatives")

Suivez les coûts en temps réel

Découvrir votre consommation sur la facture mensuelle est un luxe que peu d’équipes peuvent se permettre. Le traqueur ci-dessous écrit une ligne JSONL par appel — horodatage, modèle, jetons d’entrée et de sortie, finish_reason, ID de requête — et maintient un total de session que vous pouvez interroger à tout moment. Le format JSONL n’est pas un détail : il s’agrège avec n’importe quel outil d’analyse sans étape de parsing, et la présence de l’ID de requête vous permet de relier une anomalie de coût à un appel spécifique.

import json
from datetime import datetime, timezone

class CostTracker:
    """Suivi des coûts API en temps réel."""

    def __init__(self, log_path: str = "api_costs.jsonl"):
        self.log_path = log_path
        self.session_tokens = {"prompt": 0, "completion": 0}

    def log(self, response_data: dict):
        usage = response_data["usage"]
        self.session_tokens["prompt"] += usage["prompt"]
        self.session_tokens["completion"] += usage["completion"]

        entry = {
            "ts": datetime.now(timezone.utc).isoformat(),
            "model": response_data["model"],
            "prompt_tokens": usage["prompt"],
            "completion_tokens": usage["completion"],
            "finish_reason": response_data["finish_reason"],
            "id": response_data["id"],
        }

        with open(self.log_path, "a") as f:
            f.write(json.dumps(entry) + "\n")

    def report(self) -> str:
        total = self.session_tokens["prompt"] + self.session_tokens["completion"]
        return (
            f"Session — Prompt : {self.session_tokens['prompt']:,} | "
            f"Completion : {self.session_tokens['completion']:,} | "
            f"Total : {total:,} jetons"
        )

Validez aux deux extrémités

Une application robuste ne fait confiance ni à ce qui entre ni à ce qui sort. En entrée, rejetez les messages vides, plafonnez la longueur à 10 000 caractères pour éviter qu’un copier-coller malheureux ne fasse exploser votre facture, et supprimez les caractères de contrôle qui perturbent la tokenisation. En sortie, ne rejetez rien mais émettez des avertissements : réponse potentiellement tronquée, réponse anormalement courte (moins de cinq caractères), réponse anormalement longue (plus de 50 000). Ces trois signaux capturent la vaste majorité des échecs silencieux.

def validate_input(user_message: str) -> str:
    """Valider et nettoyer l'entrée utilisateur."""
    if not user_message or not user_message.strip():
        raise ValueError("Message vide")

    if len(user_message) > 10_000:
        raise ValueError("Message trop long (max 10 000 caractères)")

    # Nettoyer les caractères de contrôle
    cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
    return cleaned.strip()

def validate_output(content: str, finish_reason: str) -> dict:
    """Valider la sortie de l'API."""
    warnings = []

    if finish_reason == "length":
        warnings.append("Réponse potentiellement tronquée")

    if not content or len(content.strip()) < 5:
        warnings.append("Réponse anormalement courte")

    if len(content) > 50_000:
        warnings.append("Réponse anormalement longue")

    return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}

Maîtrisez la fenêtre de contexte

Un dernier problème : la dérive lente des longues conversations. La fonction ci-dessous estime le volume à un jeton pour quatre caractères en français — une approximation grossière mais suffisante comme garde-fou — et laisse passer les requêtes tant qu’elles restent sous 80 % de la limite. Au-delà, elle conserve le prompt système et supprime les messages les plus anciens jusqu’à redescendre sous les 70 %. Cet écart entre les deux seuils est délibéré : couper uniquement au seuil de déclenchement repousserait la fonction dans le rouge dès le message suivant.

def manage_context(messages: list, max_tokens: int = 100_000) -> list:
    """Maintenir les messages dans la limite de jetons du modèle."""
    # Estimation : 1 jeton ~ 4 caractères en français
    total_chars = sum(len(m["content"]) for m in messages)
    estimated_tokens = total_chars // 4

    if estimated_tokens < max_tokens * 0.8:
        return messages  # Tout tient dans la limite

    # Garder le système + premier et dernier messages
    system = [m for m in messages if m["role"] == "system"]
    history = [m for m in messages if m["role"] != "system"]

    # Supprimer les messages les plus anciens
    while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
        removed = history.pop(0)
        estimated_tokens -= len(removed["content"]) // 4

    return system + history

Ce que vous retenez de ce cours

Le parcours a suivi quatre étapes. Premièrement, les fondamentaux : le point de terminaison, les rôles, les paramètres de base et la structure de réponse. Ensuite, le streaming, avec le protocole SSE, son implémentation Python, les séquences d’arrêt et le durcissement via safe_prompt et les garde-fous. La troisième phase a été occupée par le prompting — prompts système de production, few-shot, structuration XML et Markdown, anti-modèles. Les paramètres avancés ont bouclé la boucle : température et Top P en détail, pénalités de présence et de fréquence, N complétions, et cette liste de contrôle de production.

La configuration ci-dessous distille ces choix en un point de départ défendable pour un premier déploiement en production : version fixe, plafond de jetons adapté au cas d’usage, faible température pour la cohérence factuelle, top_p inchangé puisque la température est ajustée, pénalités neutres sauf besoin spécifique justifié, et safe_prompt activé.

# Configuration typique pour une application de production
PRODUCTION_CONFIG = {
    "model": "mistral-large-2512",      # Version fixe
    "max_tokens": 2000,                  # Adapté au cas d'usage
    "temperature": 0.3,                  # Cohérent et factuel
    "top_p": 1.0,                        # Inchangé si température ajustée
    "presence_penalty": 0.0,             # Par défaut sauf besoin spécifique
    "frequency_penalty": 0.0,            # Par défaut sauf besoin spécifique
    "safe_prompt": True,                 # Sécurité activée
}

Pour aller plus loin avec l’API Mistral, quatre cours complémentaires suivent sur Corsen Academy :

  • Embeddings et RAG — Recherche sémantique avec mistral-embed et bases de données vectorielles
  • Function Calling — Connecter le modèle à vos outils et API externes
  • Fine-tuning — Adapter un modèle à votre domaine spécifique
  • Production et Évaluation — Métriques, évaluations automatisées, optimisation des coûts

Puncte cheie

  • Utilisez des modèles versionnés en production, jamais -latest
  • Implémentez retry + backoff + logging dès le premier déploiement
  • Validez à la fois les entrées ET les sorties de chaque appel API
  • Suivez les coûts en temps réel avec un traqueur de jetons
  • Gérez la fenêtre de contexte pour les longues conversations
  • Activez safe_prompt comme filet de sécurité minimal
  • Testez vos prompts avec des cas limites avant chaque mise en production

Testez vos connaissances

Plus de secrets dans le point de terminaison chat/completions ? Vérifions.

1. Quels rôles structurent la liste de messages ?

Réponse : system (le cadre), user (requêtes), assistant (réponses du modèle) — l’historique complet redémarre à chaque appel, car l’API est sans état.

2. Que trouvez-vous dans le champ usage de la réponse ?

Réponse : Les jetons consommés en entrée et en sortie — la base de la facturation et la métrique à surveiller pour le dimensionnement et les coûts.

3. Comment fonctionne le streaming SSE ?

Réponse : La réponse arrive sous forme d’événements Server-Sent, fragment par fragment : vous affichez au fur et à mesure et concaténez pour obtenir le message final.

4. À quoi servent les séquences d'arrêt ?

Réponse : À couper la génération dès qu’une chaîne donnée apparaît : contrôler la longueur, s’arrêter à un délimiteur, garantir des formats propres.

5. Température, Top P, pénalités : quel usage en production ?

Réponse : La température/Top P définit le déterminisme par tâche ; les pénalités de présence/fréquence limitent la répétition — des paramètres à fixer par cas d’usage et à documenter aux côtés de vos prompts.

Rôles, usage, streaming, arrêts, réglages : les fondamentaux tiennent — les bonnes pratiques de production ci-dessus les mettent en ordre.