Gestione delle sessioni WebSocket
In questa pagina
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:
- Apertura: connessione a
wss://api.x.ai/v1/ttscon i parametri - Attiva: scambio di messaggi
text.delta/audio.delta - Chiusura normale: il client o il server chiude la connessione
- 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