Production: mise à l'échelle et surveillance
Šajā lapā
Mis à jour le 2 novembre 2026 — Modèles audio. Plusieurs modèles de ce cours sont dépréciés :
tts-1,tts-1-hdetgpt-4o-mini-ttscesseront 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-realtimeet 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-transcribeet/v1/audio/translationsle 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 SDKopenaiversion 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 :
É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é.
Workers (FastAPI + uvicorn)
Chaque worker gère plusieurs sessions Realtime simultanées grâce à asyncio.
Base de données (PostgreSQL)
Stocke les journaux de conversation, les métriques et la configuration de l'agent.
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
SessionManageravec 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
CostControllerlimite 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.