Ir al contenido principal
Español— Elegir un idioma
Menú

Gestión de sesiones WebSocket

Lección 11 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Domina el ciclo de vida de la sesión
  2. Ciclo de vida de la sesión
  3. Reconexión automática
  4. Gestión de la duración de la sesión
  5. Grupo de sesiones (Pool)
  6. Métricas a vigilar
  7. Puntos clave

Actualizado el 3 de noviembre de 2026, basándose en la página Text to Speech de xAI, que menciona un “permiso de sesión” de 600 segundos y una conexión sin tiempo de espera. La estrategia de renovación descrita a continuación es una medida de precaución. Fuente: Text to Speech.

Domina el ciclo de vida de la sesión

En producción, una gestión robusta de las sesiones WebSocket es lo que separa un prototipo de un producto fiable. Las sesiones de TTS tienen restricciones específicas (duración, límites de concurrencia) que tu aplicación debe gestionar correctamente.

Ciclo de vida de la sesión

Una sesión WebSocket de TTS pasa por este ciclo:

  1. Apertura: conexión a wss://api.x.ai/v1/tts con los parámetros adecuados.
  2. Activa: intercambio de mensajes text.delta/audio.delta.
  3. Cierre normal: el cliente o el servidor cierran la conexión.
  4. Cierre inesperado: un error, mantenimiento o el fin del permiso de sesión de 600 segundos que menciona la documentación.

Detección del cierre

El servidor puede cerrar la conexión en cualquier momento (error interno, mantenimiento, fin del permiso de sesión). Tu aplicación debe gestionar siempre el evento de cierre:

async def managed_session(api_key, language="en", voice="eve"):
    uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}"
    headers = {"Authorization": f"Bearer {api_key}"}

    try:
        async with websockets.connect(uri, additional_headers=headers) as ws:
            yield ws
    except websockets.ConnectionClosed as e:
        print(f"Conexión cerrada: código={e.code}, motivo={e.reason}")
    except websockets.ConnectionClosedError:
        print("Conexión perdida inesperadamente")

Reconexión automática

Para aplicaciones de larga duración, implementa una reconexión con retroceso exponencial:

import asyncio
import random

class TTSSessionManager:
    def __init__(self, api_key, language="en", voice="eve"):
        self.api_key = api_key
        self.language = language
        self.voice = voice
        self.ws = None
        self.max_retries = 5

    async def connect(self):
        uri = f"wss://api.x.ai/v1/tts?language={self.language}&voice={self.voice}"
        headers = {"Authorization": f"Bearer {self.api_key}"}

        for attempt in range(self.max_retries):
            try:
                self.ws = await websockets.connect(uri, additional_headers=headers)
                print(f"Conectado (intento {attempt + 1})")
                return
            except Exception as e:
                wait = min(2 ** attempt + random.random(), 30)
                print(f"Fallo de conexión: {e}. Reintentando en {wait:.1f}s")
                await asyncio.sleep(wait)

        raise ConnectionError("No se pudo conectar tras 5 intentos")

    async def ensure_connected(self):
        if self.ws is None or self.ws.closed:
            await self.connect()

    async def synthesize(self, text):
        await self.ensure_connected()

        try:
            await self.ws.send(json.dumps({
                "type": "text.delta",
                "delta": text
            }))
            await self.ws.send(json.dumps({"type": "text.done"}))

            audio_chunks = []
            async for msg in self.ws:
                data = json.loads(msg)
                if data["type"] == "audio.delta":
                    audio_chunks.append(base64.b64decode(data["delta"]))
                elif data["type"] == "audio.done":
                    break
                elif data["type"] == "error":
                    raise Exception(data["message"])

            return b"".join(audio_chunks)

        except websockets.ConnectionClosed:
            # Reconectar y reintentar
            await self.connect()
            return await self.synthesize(text)

Gestión de la duración de la sesión

La página Text to Speech de xAI menciona un “permiso de sesión” de 600 segundos sin especificar cuándo comienza ni qué ocurre al finalizar, y afirma por separado que la conexión no tiene tiempo de espera. El enfoque más prudente es contar desde el momento en que te conectas y renovar la sesión antes de que llegue ese punto:

import time

class TTLAwareSession:
    TTL = 600  # segundos
    REFRESH_MARGIN = 60  # reconectar 60 s antes de la expiración

    def __init__(self):
        self.connected_at = None

    async def connect(self):
        # ... conexión ...
        self.connected_at = time.time()

    def should_refresh(self):
        if self.connected_at is None:
            return True
        elapsed = time.time() - self.connected_at
        return elapsed >= (self.TTL - self.REFRESH_MARGIN)

    async def synthesize(self, text):
        if self.should_refresh():
            await self.connect()  # Nueva sesión
        # ... enviar el texto ...

Reconectar 60 segundos antes de la expiración evita que te corten la comunicación en mitad de una síntesis.

Grupo de sesiones (Pool)

Para aplicaciones con mucho tráfico, mantén un grupo de sesiones reutilizables:

class SessionPool:
    def __init__(self, api_key, pool_size=10):
        self.api_key = api_key
        self.pool_size = min(pool_size, 50)  # Máx. 50 por equipo
        self.available = asyncio.Queue()
        self.active_count = 0

    async def acquire(self):
        if not self.available.empty():
            session = await self.available.get()
            if not session.should_refresh():
                return session

        if self.active_count < self.pool_size:
            session = TTSSessionManager(self.api_key)
            await session.connect()
            self.active_count += 1
            return session

        # Esperar a que se libere una sesión
        return await self.available.get()

    async def release(self, session):
        await self.available.put(session)

Mantén el tamaño del grupo en una fracción del límite de 50 sesiones para dejar margen a otros servicios de tu aplicación.

Métricas a vigilar

Para mantener las sesiones sanas en producción, supervisa:

  • Número de sesiones activas: no debe superar 50.
  • Tasa de reconexión: una tasa alta indica un problema de red o de duración de la sesión.
  • Latencia del primer audio.delta: mide la capacidad de respuesta del servicio.
  • Errores WebSocket: códigos de cierre anómalos (1006, 1011).
class MetricsCollector:
    def __init__(self):
        self.connections = 0
        self.reconnections = 0
        self.errors = 0
        self.first_audio_latencies = []

    def record_connection(self):
        self.connections += 1

    def record_reconnection(self):
        self.reconnections += 1

    def record_first_audio(self, latency_ms):
        self.first_audio_latencies.append(latency_ms)

Puntos clave

  • La documentación menciona un permiso de sesión de 600 segundos: por seguridad, cuéntalo desde el momento de la conexión.
  • Implementa una reconexión automática con retroceso exponencial.
  • Renueva la sesión antes de que expire (con un margen de 60 segundos).
  • Utiliza un grupo de sesiones para aplicaciones con mucho tráfico.
  • Mantente dentro del límite de 50 sesiones simultáneas por equipo.
  • Supervisa las métricas de conexión en producción.