Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Bonnes pratiques de production

Lekcija 16 od 16 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  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. Suivre les coûts en temps réel
  5. Valider aux deux extrémités
  6. Maîtriser la fenêtre de contexte
  7. Ce que tu retiens de ce cours
  8. Ključne točke
  9. Teste tes connaissances

De la preuve de concept au déploiement

Tu maîtrises désormais tous les paramètres de l’API Chat Completions. La partie la plus délicate reste à faire : combler le fossé entre un notebook fonctionnel et un service utilisé par d’autres sans ton intervention. Cette dernière leçon consolide l’ensemble du cours en une liste de contrôle actionnable pour la production, puis t’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évois aussi la rotation : crée la nouvelle clé, déploie-la, puis révoque l’ancienne, dans cet ordre, si tu veux é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é 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 deuxième décision concerne l’identifiant du modèle. En développement, -latest t’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 ton application sans avertissement, un mardi matin, sans aucune trace de commit pour l’expliquer. Épingle la version.

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

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

# Pourquoi ? Un changement « latest » peut altérer le comportement
# de ton 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 point de contrôle unique : 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 corrigera. Elle normalise également la réponse dans un dictionnaire stable — contenu, finish_reason, usage, modèle, ID — afin que le reste de ton code ne dépende plus de la forme exacte de l’objet retourné par le SDK. Le seul logger.warning sur les troncatures justifie déjà cette encapsulation : c’est le seul moyen de découvrir qu’un réglage max_tokens est trop serré 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")

Suivre les coûts en temps réel

Découvrir ta 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, tokens d’entrée et de sortie, finish_reason, ID de requête — et maintient un total de session que tu peux interroger à tout moment. Le format JSONL n’est pas un détail : il s’agrège avec n’importe quel outil d’analytique sans étape de parsing, et la présence de l’ID de requête te 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:,} tokens"
        )

Valider aux deux extrémités

Une application robuste ne fait confiance ni à ce qui entre ni à ce qui sort. En entrée, rejette les messages vides, limite la longueur à 10 000 caractères pour éviter qu’un copier-coller malheureux ne fasse exploser ta facture, et supprime les caractères de contrôle qui perturbent la tokenisation. En sortie, ne rejette rien mais émets 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îtriser la fenêtre de contexte

Dernier problème : la dérive lente des longues conversations. La fonction ci-dessous estime le volume à un token 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 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 tokens du modèle."""
    # Estimation : 1 token ~ 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

    # 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 tu retiens de ce cours

Le parcours a suivi quatre étapes. D’abord, 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. Le prompting a occupé la troisième phase — 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 pour la production.

La configuration ci-dessous distille ces choix en un point de départ défendable pour un premier déploiement en production : version figée, plafond de tokens adapté au cas d’usage, basse 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 figée
    "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 à tes outils et APIs externes
  • Fine-tuning — Adapter un modèle à ton domaine spécifique
  • Production et Évaluation — Métriques, évaluations automatisées, optimisation des coûts

Ključne točke

  • Utilise des modèles versionnés en production, jamais -latest
  • Implémente retry + backoff + logging dès le premier déploiement
  • Valide à la fois les entrées ET les sorties de chaque appel API
  • Suis les coûts en temps réel avec un traqueur de tokens
  • Gère la fenêtre de contexte pour les longues conversations
  • Active safe_prompt comme filet de sécurité minimal
  • Teste tes prompts avec des cas limites avant chaque mise en production

Teste tes 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 (les requêtes), assistant (les réponses du modèle) — l’historique complet redémarre à chaque appel, car l’API est sans état.

2. Que trouves-tu dans le champ usage de la réponse ?

Réponse : Les tokens 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 : tu affiches au fur et à mesure et concatènes 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 réglages à figer par cas d’usage et à documenter alongside tes prompts.

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