Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Gestão de sessões WebSocket

Aula 11 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Domine o ciclo de vida da sessão
  2. Ciclo de vida da sessão
  3. Reconexão automática
  4. Gestão do tempo de vida da sessão
  5. Pool de sessões
  6. Métricas a monitorizar
  7. Pontos-chave

Atualizado a 3 de novembro de 2026, com base na página Text to Speech da xAI, que menciona uma “autorização de sessão” de 600 segundos e uma ligação sem tempo limite. A estratégia de renovação abaixo é uma precaução. Fonte: Text to Speech.

Domine o ciclo de vida da sessão

Em produção, uma gestão robusta de sessões WebSocket é o que separa um protótipo de um produto fiável. As sessões de TTS têm restrições específicas (tempo de vida, limites de concorrência) que a sua aplicação tem de gerir corretamente.

Ciclo de vida da sessão

Uma sessão WebSocket de TTS percorre este ciclo:

  1. Abertura: ligação a wss://api.x.ai/v1/tts com os parâmetros
  2. Ativa: troca de mensagens text.delta/audio.delta
  3. Fecho normal: o cliente ou o servidor encerra a ligação
  4. Fecho inesperado: um erro, manutenção ou o fim da autorização de sessão de 600 segundos mencionada na documentação

Detetar o fecho

O servidor pode encerrar a ligação a qualquer momento (erro interno, manutenção, fim da autorização de sessão). A sua aplicação deve tratar sempre o evento de fecho:

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"Connection closed: code={e.code}, reason={e.reason}")
    except websockets.ConnectionClosedError:
        print("Connection lost unexpectedly")

Reconexão automática

Para aplicações de longa duração, implemente uma reconexão com espera exponencial (exponential backoff):

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"Connected (attempt {attempt + 1})")
                return
            except Exception as e:
                wait = min(2 ** attempt + random.random(), 30)
                print(f"Connection failed: {e}. Retrying in {wait:.1f}s")
                await asyncio.sleep(wait)

        raise ConnectionError("Could not connect after 5 attempts")

    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:
            # Reconetar e tentar novamente
            await self.connect()
            return await self.synthesize(text)

Gestão do tempo de vida da sessão

A página Text to Speech da xAI menciona uma “autorização de sessão” de 600 segundos sem especificar quando começa nem o que acontece no fim, afirmando separadamente que a ligação não tem tempo limite. A abordagem mais cautelosa é contar a partir do momento da ligação e renovar a sessão antes desse ponto:

import time

class TTLAwareSession:
    TTL = 600  # segundos
    REFRESH_MARGIN = 60  # reconetar 60 s antes da expiração

    def __init__(self):
        self.connected_at = None

    async def connect(self):
        # ... ligação ...
        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()  # Nova sessão
        # ... enviar o texto ...

Reconetar 60 segundos antes da expiração evita que seja interrompido a meio da síntese.

Pool de sessões

Para aplicações com tráfego elevado, mantenha um pool de sessões reutilizáveis:

class SessionPool:
    def __init__(self, api_key, pool_size=10):
        self.api_key = api_key
        self.pool_size = min(pool_size, 50)  # Máximo 50 por equipa
        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

        # Aguardar que uma sessão fique livre
        return await self.available.get()

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

Mantenha o tamanho do pool numa fração do limite de 50 sessões para deixar margem para outros serviços da sua aplicação.

Métricas a monitorizar

Para manter as sessões saudáveis em produção, monitore:

  • Número de sessões ativas: não deve exceder 50
  • Taxa de reconexão: uma taxa elevada indica um problema de rede ou de tempo de vida
  • Latência do primeiro audio.delta: mede a capacidade de resposta do serviço
  • Erros WebSocket: códigos de fecho anormais (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)

Pontos-chave

  • A documentação menciona uma autorização de sessão de 600 segundos: por segurança, conte-a a partir do momento da ligação
  • Implemente uma reconexão automática com espera exponencial
  • Renove a sessão antes desse ponto (com uma margem de 60 segundos)
  • Utilize um pool de sessões para aplicações com tráfego elevado
  • Mantenha-se dentro do limite de 50 sessões simultâneas por equipa
  • Monitore as métricas de ligação em produção