Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gestione delle sessioni WebSocket

Lezione 11 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Padroneggia il ciclo di vita della sessione
  2. Ciclo di vita della sessione
  3. Riconnessione automatica
  4. Gestione della durata della sessione
  5. Pool di sessioni
  6. Metriche da monitorare
  7. Punti chiave

Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI, che menziona un “permesso di sessione” di 600 secondi e una connessione senza timeout. La strategia di rinnovo descritta di seguito è una precauzione. Fonte: Text to Speech.

Padroneggia il ciclo di vita della sessione

In produzione, una gestione robusta delle sessioni WebSocket è ciò che distingue un prototipo da un prodotto affidabile. Le sessioni TTS presentano vincoli specifici (durata, limiti di concorrenza) che la tua applicazione deve gestire correttamente.

Ciclo di vita della sessione

Una sessione WebSocket TTS attraversa questo ciclo:

  1. Apertura: connessione a wss://api.x.ai/v1/tts con i parametri
  2. Attiva: scambio di messaggi text.delta/audio.delta
  3. Chiusura normale: il client o il server chiude la connessione
  4. Chiusura imprevista: un errore, la manutenzione o la scadenza del permesso di sessione di 600 secondi menzionato nella documentazione

Rilevare la chiusura

Il server può chiudere la connessione in qualsiasi momento (errore interno, manutenzione, fine del permesso di sessione). La tua applicazione deve sempre gestire l’evento di chiusura:

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")

Riconnessione automatica

Per le applicazioni a lunga esecuzione, implementa una riconnessione con backoff esponenziale:

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

Gestione della durata della sessione

La pagina Text to Speech di xAI menziona un “permesso di sessione” di 600 secondi senza specificare quando inizia né cosa accade alla scadenza, affermando separatamente che la connessione non ha timeout. L’approccio più prudente è contare dal momento della connessione e rinnovare la sessione prima di tale istante:

import time

class TTLAwareSession:
    TTL = 600  # secondi
    REFRESH_MARGIN = 60  # riconnetti 60 s prima della scadenza

    def __init__(self):
        self.connected_at = None

    async def connect(self):
        # ... connessione ...
        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()  # Nuova sessione
        # ... invia il testo ...

Riconnettersi 60 secondi prima della scadenza ti evita di essere interrotto a metà sintesi.

Pool di sessioni

Per le applicazioni ad alto traffico, mantieni un pool di sessioni riutilizzabili:

class SessionPool:
    def __init__(self, api_key, pool_size=10):
        self.api_key = api_key
        self.pool_size = min(pool_size, 50)  # Max 50 per team
        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

        # Attendi che una sessione si liberi
        return await self.available.get()

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

Mantieni la dimensione del pool a una frazione del limite di 50 sessioni per lasciare margine agli altri servizi della tua applicazione.

Metriche da monitorare

Per mantenere le sessioni sane in produzione, monitora:

  • Numero di sessioni attive: non deve superare 50
  • Tasso di riconnessione: un tasso elevato indica un problema di rete o di durata
  • Latenza del primo audio.delta: misura la reattività del servizio
  • Errori WebSocket: codici di chiusura anomali (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)

Punti chiave

  • La documentazione menziona un permesso di sessione di 600 secondi: per sicurezza, contalo dal momento della connessione
  • Implementa la riconnessione automatica con backoff esponenziale
  • Rinnova la sessione prima della scadenza (con un margine di 60 secondi)
  • Usa un pool di sessioni per le applicazioni ad alto traffico
  • Rimani entro il limite di 50 sessioni concurrenti per team
  • Monitora le metriche di connessione in produzione