Producción: escalado y monitorización
En esta página
Actualizado el 2 de noviembre de 2026 — Modelos de audio. Varios modelos de este curso están obsoletos:
tts-1,tts-1-hdygpt-4o-mini-ttsdejarán de funcionar el 6 de enero de 2027 (sustituto:gpt-realtime-2.1-mini, que la guía de TTS de OpenAI indica que no es compatible con/v1/audio/speech: la migración de síntesis de voz debe realizarse a través de la API en tiempo real);gpt-realtime,gpt-4o-realtimey los modelos de audio heredados el 20 de enero de 2027 (gpt-realtime-2.1,gpt-realtime-2.1-mini,gpt-audio-1.5);whisper-1,gpt-4o-transcribey/v1/audio/translationsel 26 de febrero de 2027 (gpt-transcribe,gpt-live-transcribe,v1/realtime/translations). Para la voz a dúplex completo, GPT-Live 1 está disponible en la API desde el 10 de septiembre de 2026.
Actualizado el 3 de noviembre de 2026. La gestión de costes, que antes cabía en una frase, refleja ahora el modelo de facturación descrito por OpenAI (facturación por respuesta, conversación devuelta en cada turno, audio contado en tokens, caché automática, transcripción facturada por separado) y el truncamiento mediante
retention_ratio, cuyo formato se verificó frente a los tipos del SDKopenaiversión 3.42.1. Fuente: Optimización de costes.
Producción: escalado y monitorización
Pasar de un prototipo de agente de voz a un servicio de producción fiable y escalable exige prestar mucha atención a la infraestructura, la monitorización y la gestión de errores. Esta última lección cubre los aspectos operativos esenciales para desplegar un agente de voz en condiciones reales.
Arquitectura de producción
En producción, el agente de voz se ejecuta detrás de un equilibrador de carga y un grupo de trabajadores:
Equilibrador de carga (nginx / HAProxy)
Distribuye las conexiones WebSocket entrantes entre los trabajadores. Admite sesiones persistentes (sticky sessions) para mantener la afinidad.
Trabajadores (FastAPI + uvicorn)
Cada trabajador gestiona múltiples sesiones en tiempo real simultáneas gracias a asyncio.
Base de datos (PostgreSQL)
Almacena registros de conversaciones, métricas y configuración del agente.
Monitorización (Prometheus + Grafana)
Recopila métricas en tiempo real: latencia, número de sesiones, errores, costes.
Gestión de sesiones concurrentes
Cada conexión WebSocket mantiene una sesión de la API en tiempo real. El número de sesiones simultáneas está limitado por tus límites de tasa de OpenAI y por la capacidad de tus trabajadores:
import asyncio
from dataclasses import dataclass
@dataclass
class SessionManager:
"""Gestiona sesiones concurrentes de la API en tiempo real."""
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):
"""Crea una nueva sesión con control de concurrencia."""
async with self.semaphore:
if session_id in self.active_sessions:
raise ValueError(f"Session {session_id} already 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):
"""Cierra correctamente una sesión."""
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)
Registro estructurado
Registra cada interacción para depuración y cumplimiento normativo:
import logging
import json
from datetime import datetime
class ConversationLogger:
"""Registrador estructurado para conversaciones de voz."""
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 el registro completo en la base de datos."""
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étricas de Prometheus
Expón métricas para monitorización en tiempo real:
from prometheus_client import Counter, Histogram, Gauge, start_http_server
# Métricas clave
sessions_active = Gauge(
"voice_sessions_active",
"Number of active voice sessions"
)
session_duration = Histogram(
"voice_session_duration_seconds",
"Duration of voice sessions",
buckets=[30, 60, 120, 300, 600, 1800]
)
response_latency = Histogram(
"voice_response_latency_ms",
"Response latency (end of speech → first audio)",
buckets=[200, 400, 600, 800, 1000, 1500, 2000, 3000]
)
errors_total = Counter(
"voice_errors_total",
"Total number of errors",
["error_type"]
)
tokens_used = Counter(
"voice_tokens_total",
"Tokens consumed",
["type"] # input_audio, output_audio, input_text, output_text
)
# Inicia el servidor de métricas
start_http_server(9090)
Gestión de costes
Según la guía de Optimización de costes de OpenAI, una sesión de conversación en tiempo real se factura por respuesta, en tokens de entrada y salida para texto, audio e imágenes. Tres mecanismos impulsan la mayor parte de la factura:
- Toda la conversación se envía de vuelta al modelo con cada respuesta: los turnos posteriores cuestan más que los iniciales.
- El audio se cuenta en tokens: 1 token por cada 100 ms de audio del usuario, 1 token por cada 50 ms de audio del asistente.
- El caché de prompts se aplica automáticamente: mientras el inicio de la conversación no cambie, se factura a la tarifa reducida de tokens en caché. Modificar o eliminar un elemento antiguo «rompe» la caché a partir de ese punto.
La transcripción de entrada, si está activada, se factura por separado a la tarifa de su propio modelo: gpt-transcribe se cobra por duración, leída desde el evento conversation.item.input_audio_transcription.completed. El consumo de cada respuesta aparece en response.done, bajo response.usage (total_tokens, input_tokens, output_tokens, más el desglose para texto, audio, imagen y caché).
Para limitar el tamaño del contexto —y por tanto el coste de los turnos posteriores— la sesión acepta una regla de truncamiento: más allá del límite, se descartan los mensajes más antiguos. Con retention_ratio establecido por debajo de 1, el servidor elimina ligeramente más de lo necesario, lo que espacia los truncamientos y preserva la caché:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"type": "realtime",
"truncation": {
"type": "retention_ratio",
"retention_ratio": 0.8,
"token_limits": {"post_instructions": 8000},
},
},
}))
La contrapartida: un agente que retiene menos contexto olvida más rápido. Complementa esto con límites de sesión en tu código:
class CostController:
"""Controla los costes de una sesión en tiempo real."""
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"This session will end in {int(remaining)} seconds."
return ""
Gestión de errores en producción
async def production_event_loop(ws, logger, cost_ctrl):
"""Bucle de eventos robusto para producción."""
cost_ctrl.start()
try:
async for raw in ws:
event = json.loads(raw)
t = event["type"]
# Comprueba los límites de coste
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": "The session is approaching its duration limit."}]
}
}))
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()
Puntos clave
- La arquitectura de producción separa equilibrador de carga, trabajadores asyncio, base de datos y monitorización
- Un
SessionManagercon un semáforo controla el número de sesiones simultáneas - El registro estructurado en JSON permite la depuración y el cumplimiento (grabación de conversaciones)
- Las métricas de Prometheus (TTFA, duración, tokens, errores) son esenciales para las operaciones diarias
- El
CostControllerlimita la duración de la sesión y los tokens para evitar desviaciones presupuestarias
Pon a prueba tus conocimientos
Cinco preguntas que cubren toda la cadena de voz, desde WebSocket hasta el despliegue en producción.
1. ¿Por qué la API en tiempo real usa WebSocket en lugar de peticiones HTTP?
Respuesta: Porque una conexión persistente y bidireccional permite transmitir audio del micrófono y recibir respuestas de forma continua, sin pagar la sobrecarga de establecer una petición para cada intercambio. Esto es el prerequisito para una conversación de baja latencia.
2. ¿Qué debes enviar inmediatamente después de `session.created` y por qué?
Respuesta: session.update, inmediatamente: aquí es donde configuras la voz, las instrucciones, las herramientas y el formato de audio. Hasta que no se envía este mensaje, la sesión se ejecuta con valores por defecto.
3. ¿Por qué es esencial un servidor proxy en producción?
Respuesta: Evita exponer la clave de API en el cliente y te permite autenticar al usuario, limitar el consumo y registrar las llamadas; tres cosas imposibles si el navegador habla directamente con la API.
4. ¿Cuál es la finalidad del parámetro `prompt` en la API de transcripción?
Respuesta: Orientar el reconocimiento hacia el vocabulario esperado: nombres propios, marcas, jerga del dominio. Los términos que listes allí se transcriben con mucha más precisión.
5. ¿Cuál es la palanca principal para la latencia percibida en un agente de voz?
Respuesta: La transmisión de extremo a extremo: reproducir el audio tan pronto como llegan los primeros fragmentos en lugar de esperar a la respuesta completa, y gestionar la interrupción para que el usuario pueda intervenir en cualquier momento.