Upravljanje sej WebSocket
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi strani xAI Text to Speech, ki omenja 600-sekundno “dovoljenje za sejo” in povezavo brez časovne omejitve. Spodnja strategija obnovitve je previdnostni ukrep. Vir: Text to Speech.
Obvladaj življenjski cikel seje
V produkcijskem okolju je ravno robustno upravljanje sej WebSocket tisto, kar loči prototip od zanesljivega izdelka. Seje TTS imajo specifične omejitve (življenjska doba, omejitve sočasnih povezav), ki jih mora tvoja aplikacija pravilno obravnavati.
Življenjski cikel seje
Seja WebSocket za TTS poteka skozi naslednji cikel:
- Odpiranje: povezava z
wss://api.x.ai/v1/ttsz ustreznimi parametri - Aktivno: izmenjava sporočil
text.delta/audio.delta - Normalno zapiranje: klient ali strežnik zapre povezavo
- Nepričakovano zapiranje: napaka, vzdrževanje ali potek 600-sekundnega dovoljenja za sejo, ki ga omenja dokumentacija
Zaznavanje zapiranja
Strežnik lahko kadar koli zapre povezavo (notranja napaka, vzdrževanje, potek dovoljenja za sejo). Tvoja aplikacija mora vedno obravnavati dogodek zapiranja:
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")
Samodejna ponovna povezava
Za aplikacije, ki tečejo dlje časa, implementiraj ponovno povezavo z eksponentnim zamikom (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:
# Ponovna povezava in poskus znova
await self.connect()
return await self.synthesize(text)
Upravljanje življenjske dobe seje
Stran xAI Text to Speech omenja 600-sekundno “dovoljenje za sejo”, ne pojasni pa, kdaj se začne ali kaj se zgodi ob njegovem izteku, hkrati pa navaja, da povezava nima časovne omejitve. Najbolj previden pristop je štetje časa od trenutka vzpostavitve povezave in obnova seje pred tem trenutkom:
import time
class TTLAwareSession:
TTL = 600 # sekunde
REFRESH_MARGIN = 60 # ponovna povezava 60 s pred iztekom
def __init__(self):
self.connected_at = None
async def connect(self):
# ... povezava ...
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 seja
# ... pošlji besedilo ...
Ponovna povezava 60 sekund pred iztekom prepreči, da bi bili prekinjeni sredi sinteze.
Skupina sej (Session Pool)
Za aplikacije z velikim prometom imej skupino ponovno uporabnih sej:
class SessionPool:
def __init__(self, api_key, pool_size=10):
self.api_key = api_key
self.pool_size = min(pool_size, 50) # Največ 50 na ekipo
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
# Počakaj, da se seja sprosti
return await self.available.get()
async def release(self, session):
await self.available.put(session)
Velikost skupine ohrani na delu omejitve 50 sej, da ostane rezerva za druge storitve tvoje aplikacije.
Metrike za spremljanje
Za ohranjanje zdravja sej v produkcijskem okolju spremljaj:
- Število aktivnih sej: ne sme preseči 50
- Stopnja ponovnih povezav: visoka stopnja kaže na težavo z omrežjem ali življenjsko dobo
- Latentnost prvega audio.delta: meri odzivnost storitve
- Napake WebSocket: nenormalne kode zapiranja (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)
Ključne ugotovitve
- Dokumentacija omenja 600-sekundno dovoljenje za sejo: zaradi varnosti ga štej od trenutka vzpostavitve povezave
- Implementiraj samodejno ponovno povezavo z eksponentnim zamikom
- Obnovi sejo pred iztekom (z 60-sekundno rezervo)
- Za aplikacije z velikim prometom uporabi skupino sej
- Ostani znotraj omejitve 50 sočasnih sej na ekipo
- V produkcijskem okolju spremljaj metrike povezav