Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Production: mise à l'échelle et surveillance

Nodarbība 18 no 18 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Production : mise à l’échelle et surveillance
  2. Architecture de production
  3. Gestion des sessions concurrentes
  4. Journalisation structurée
  5. Métriques Prometheus
  6. Gestion des coûts
  7. Gestion des erreurs en production
  8. Galvenās atziņas
  9. Teste tes connaissances

Mis à jour le 2 novembre 2026 — Modèles audio. Plusieurs modèles de ce cours sont dépréciés : tts-1, tts-1-hd et gpt-4o-mini-tts cesseront de fonctionner le 6 janvier 2027 (remplacement : gpt-realtime-2.1-mini, que le guide TTS d’OpenAI indique comme non pris en charge par /v1/audio/speech : la migration de la synthèse vocale doit passer par l’API Realtime) ; gpt-realtime, gpt-4o-realtime et les anciens modèles audio le 20 janvier 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5) ; whisper-1, gpt-4o-transcribe et /v1/audio/translations le 26 février 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Pour la voix full-duplex, GPT-Live 1 est disponible dans l’API depuis le 10 septembre 2026.

Mis à jour le 3 novembre 2026. La gestion des coûts tenait auparavant en une seule phrase ; elle reflète désormais le modèle de facturation décrit par OpenAI (facturation par réponse, conversation renvoyée à chaque tour, audio compté en tokens, mise en cache automatique, transcription facturée séparément) et la troncation via retention_ratio, dont le format a été vérifié auprès des types SDK openai version 3.42.1. Source : Optimisation des coûts.

Production : mise à l’échelle et surveillance

Passer d’un prototype d’agent vocal à un service de production fiable et évolutif exige une attention particulière portée à l’infrastructure, à la surveillance et à la gestion des erreurs. Cette dernière leçon couvre les essentiels opérationnels pour déployer un agent vocal dans des conditions réelles.

Architecture de production

En production, l’agent vocal s’exécute derrière un équilibreur de charge et un pool de workers :

1

Équilibreur de charge (nginx / HAProxy)

Répartit les connexions WebSocket entrantes entre les workers. Prend en charge les sessions persistantes (sticky sessions) pour maintenir l'affinité.

2

Workers (FastAPI + uvicorn)

Chaque worker gère plusieurs sessions Realtime simultanées grâce à asyncio.

3

Base de données (PostgreSQL)

Stocke les journaux de conversation, les métriques et la configuration de l'agent.

4

Surveillance (Prometheus + Grafana)

Collecte les métriques en temps réel : latence, nombre de sessions, erreurs, coûts.

Gestion des sessions concurrentes

Chaque connexion WebSocket maintient une session API Realtime. Le nombre de sessions simultanées est limité par vos quotas de taux (rate limits) OpenAI et par la capacité de vos workers :

import asyncio
from dataclasses import dataclass

@dataclass
class SessionManager:
    """Gère les sessions API Realtime concurrentes."""
    max_sessions: int = 50
    active_sessions: dict = None
    semaphore: asyncio.Semaphore = None

    def __post_init__(self):
        self.active_sessions = {}
        self.semaphore = asyncio.Semaphore(self.max_sessions)

    async def create_session(self, session_id: str, config: dict):
        """Crée une nouvelle session avec contrôle de la concurrence."""
        async with self.semaphore:
            if session_id in self.active_sessions:
                raise ValueError(f"Session {session_id} déjà active")

            self.active_sessions[session_id] = {
                "created_at": asyncio.get_event_loop().time(),
                "config": config,
                "status": "active"
            }
            return session_id

    async def close_session(self, session_id: str):
        """Ferme correctement une session."""
        if session_id in self.active_sessions:
            del self.active_sessions[session_id]

    @property
    def active_count(self) -> int:
        return len(self.active_sessions)

    @property
    def available_slots(self) -> int:
        return self.max_sessions - self.active_count

session_manager = SessionManager(max_sessions=50)

Journalisation structurée

Journalise chaque interaction pour le débogage et la conformité :

import logging
import json
from datetime import datetime

class ConversationLogger:
    """Journaliseur structuré pour les conversations vocales."""

    def __init__(self, session_id: str):
        self.session_id = session_id
        self.logger = logging.getLogger(f"voice.{session_id}")
        self.events = []

    def log_event(self, event_type: str, data: dict = None):
        entry = {
            "timestamp": datetime.utcnow().isoformat(),
            "session_id": self.session_id,
            "event_type": event_type,
            "data": data or {}
        }
        self.events.append(entry)
        self.logger.info(json.dumps(entry))

    def log_transcription(self, role: str, text: str):
        self.log_event("transcription", {
            "role": role,
            "text": text
        })

    def log_function_call(self, name: str, args: dict, result: dict, duration_ms: float):
        self.log_event("function_call", {
            "name": name,
            "arguments": args,
            "result": result,
            "duration_ms": round(duration_ms)
        })

    def log_error(self, error_type: str, message: str):
        self.log_event("error", {
            "type": error_type,
            "message": message
        })

    async def save_to_db(self, db_pool):
        """Persiste le journal complet dans la base de données."""
        async with db_pool.acquire() as conn:
            await conn.execute(
                "INSERT INTO conversation_logs (session_id, events, created_at) "
                "VALUES ($1, $2, NOW())",
                self.session_id, json.dumps(self.events)
            )

Métriques Prometheus

Expose des métriques pour une surveillance en temps réel :

from prometheus_client import Counter, Histogram, Gauge, start_http_server

# Métriques clés
sessions_active = Gauge(
    "voice_sessions_active",
    "Nombre de sessions vocales actives"
)

session_duration = Histogram(
    "voice_session_duration_seconds",
    "Durée des sessions vocales",
    buckets=[30, 60, 120, 300, 600, 1800]
)

response_latency = Histogram(
    "voice_response_latency_ms",
    "Latence de réponse (fin de parole → premier audio)",
    buckets=[200, 400, 600, 800, 1000, 1500, 2000, 3000]
)

errors_total = Counter(
    "voice_errors_total",
    "Nombre total d'erreurs",
    ["error_type"]
)

tokens_used = Counter(
    "voice_tokens_total",
    "Tokens consommés",
    ["type"]  # input_audio, output_audio, input_text, output_text
)

# Démarrage du serveur de métriques
start_http_server(9090)

Gestion des coûts

Selon le guide Optimisation des coûts d’OpenAI, une session de conversation Realtime est facturée par réponse, en tokens d’entrée et de sortie pour le texte, l’audio et les images. Trois mécanismes pilotent l’essentiel de la facture :

  • La conversation entière est renvoyée au modèle à chaque réponse : les tours tardifs coûtent plus cher que les premiers.
  • L’audio est compté en tokens : 1 token pour 100 ms d’audio utilisateur, 1 token pour 50 ms d’audio assistant.
  • La mise en cache du prompt s’applique automatiquement : tant que le début de la conversation ne change pas, il est facturé au tarif réduit des tokens mis en cache. Modifier ou supprimer un élément ancien « brise » le cache à partir de ce point.

La transcription d’entrée, si activée, est facturée séparément au tarif de son propre modèle : gpt-transcribe est facturé à la durée, lue dans l’événement conversation.item.input_audio_transcription.completed. La consommation pour chaque réponse apparaît dans response.done, sous response.usage (total_tokens, input_tokens, output_tokens, plus le détail pour le texte, l’audio, l’image et le cache).

Pour limiter la taille du contexte — et donc le coût des tours tardifs — la session accepte une règle de troncation : au-delà de la limite, les messages les plus anciens sont supprimés. Avec retention_ratio défini en dessous de 1, le serveur retire légèrement plus que nécessaire, ce qui espace les troncations et préserve le cache :

await ws.send(json.dumps({
    "type": "session.update",
    "session": {
        "type": "realtime",
        "truncation": {
            "type": "retention_ratio",
            "retention_ratio": 0.8,
            "token_limits": {"post_instructions": 8000},
        },
    },
}))

Le compromis : un agent qui conserve moins de contexte oublie plus vite. Complète cela par des limites de session dans ton code :

class CostController:
    """Contrôle les coûts d'une session Realtime."""

    def __init__(self, max_duration_s: int = 600, max_tokens: int = 50000):
        self.max_duration_s = max_duration_s
        self.max_tokens = max_tokens
        self.total_tokens = 0
        self.start_time = None

    def start(self):
        self.start_time = asyncio.get_event_loop().time()

    def update_tokens(self, usage: dict):
        self.total_tokens += usage.get("total_tokens", 0)

    @property
    def elapsed_seconds(self) -> float:
        if not self.start_time:
            return 0
        return asyncio.get_event_loop().time() - self.start_time

    @property
    def should_terminate(self) -> bool:
        if self.elapsed_seconds > self.max_duration_s:
            return True
        if self.total_tokens > self.max_tokens:
            return True
        return False

    @property
    def warning_message(self) -> str:
        remaining = self.max_duration_s - self.elapsed_seconds
        if remaining < 60:
            return f"Cette session se terminera dans {int(remaining)} secondes."
        return ""

Gestion des erreurs en production

async def production_event_loop(ws, logger, cost_ctrl):
    """Boucle d'événements robuste pour la production."""
    cost_ctrl.start()

    try:
        async for raw in ws:
            event = json.loads(raw)
            t = event["type"]

            # Vérification des limites de coût
            if cost_ctrl.should_terminate:
                logger.log_event("session_limit_reached")
                await ws.send(json.dumps({
                    "type": "conversation.item.create",
                    "item": {
                        "type": "message",
                        "role": "user",
                        "content": [{"type": "input_text",
                                     "text": "La session approche de sa limite de durée."}]
                    }
                }))
                break

            if t == "response.done":
                usage = event["response"].get("usage", {})
                cost_ctrl.update_tokens(usage)
                tokens_used.labels(type="total").inc(usage.get("total_tokens", 0))

            elif t == "error":
                error = event["error"]
                logger.log_error(error["type"], error["message"])
                errors_total.labels(error_type=error["type"]).inc()

                if error["type"] == "rate_limit_error":
                    await asyncio.sleep(1)

    except websockets.exceptions.ConnectionClosed as e:
        logger.log_error("connection_closed", str(e))
    except Exception as e:
        logger.log_error("unexpected", str(e))
    finally:
        session_duration.observe(cost_ctrl.elapsed_seconds)
        sessions_active.dec()

Galvenās atziņas

  • L’architecture de production sépare équilibreur de charge, workers asyncio, base de données et surveillance
  • Un SessionManager avec un sémaphore contrôle le nombre de sessions simultanées
  • La journalisation structurée JSON permet le débogage et la conformité (enregistrement des conversations)
  • Les métriques Prometheus (TTFA, durée, tokens, erreurs) sont essentielles pour les opérations quotidiennes
  • Le CostController limite la durée de session et les tokens pour éviter les dépassements budgétaires

Teste tes connaissances

Cinq questions couvrant toute la chaîne vocale, du WebSocket au déploiement en production.

1. Pourquoi l'API Realtime utilise-t-elle WebSocket plutôt que des requêtes HTTP ?

Réponse : Parce qu’une connexion persistante et bidirectionnelle permet de diffuser l’audio du microphone et de recevoir des réponses en continu, sans payer la surcharge d’établissement d’une requête pour chaque échange. C’est la condition préalable à une conversation à faible latence.

2. Que dois-tu envoyer immédiatement après `session.created`, et pourquoi ?

Réponse : session.update, immédiatement : c’est là que tu configures la voix, les instructions, les outils et le format audio. Tant que ce message n’est pas envoyé, la session s’exécute avec des valeurs par défaut.

3. Pourquoi un serveur proxy est-il essentiel en production ?

Réponse : Il empêche d’exposer la clé API dans le client, et il te permet d’authentifier l’utilisateur, de plafonner la consommation et de journaliser les appels — trois choses impossibles si le navigateur parle directement à l’API.

4. Quel est le but du paramètre `prompt` dans l'API de transcription ?

Réponse : Orienter la reconnaissance vers le vocabulaire attendu : noms propres, marques, jargon métier. Les termes que tu y listes sont transcrits avec beaucoup plus de précision.

5. Quel est le principal levier de la latence perçue dans un agent vocal ?

Réponse : La diffusion en flux continu de bout en bout : jouer l’audio dès l’arrivée des premiers fragments au lieu d’attendre la réponse complète, et gérer l’interruption pour que l’utilisateur puisse intervenir à tout moment.