Správa relácií WebSocket
Na tejto strane
Aktualizované 3. novembra 2026 na základe stránky xAI Text to Speech, ktorá spomína 600-sekundové „povolenie relácie“ a pripojenie bez časového limitu. Nižšie uvedená stratégia obnovy je preventívnym opatrením. Zdroj: Text to Speech.
Zvládni životný cyklus relácie
V produkčnom prostredí je to práve robustná správa relácií WebSocket, čo oddeľuje prototyp od spoľahlivého produktu. Relácie TTS majú špecifické obmedzenia (doba života, limity súbežnosti), ktoré musí tvoja aplikácia správne ošetriť.
Životný cyklus relácie
Relácia WebSocket pre TTS prechádza týmto cyklom:
- Otvorenie: pripojenie na
wss://api.x.ai/v1/ttss parametrami - Aktívna: výmena správ
text.delta/audio.delta - Normálne uzavretie: klient alebo server uzavrie spojenie
- Neočakávané uzavretie: chyba, údržba alebo uplynutie 600-sekundového povolenia relácie, ktoré spomína dokumentácia
Detekcia uzavretia
Server môže uzavrieť spojenie kedykoľvek (interná chyba, údržba, koniec povolenia relácie). Tvoja aplikácia by mala vždy ošetriť udalosť uzavretia:
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")
Automatické opätovné pripojenie
Pre dlho bežiace aplikácie implementuj opätovné pripojenie s exponenciálnym oneskorením (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:
# Opätovné pripojenie a retry
await self.connect()
return await self.synthesize(text)
Správa životnosti relácie
Stránka xAI Text to Speech spomína 600-sekundové „povolenie relácie“, ale nešpecifikuje, kedy začína plynúť ani čo sa stane po jeho uplynutí. Zároveň samostatne uvádza, že spojenie nemá žiadny časový limit. Najopatrnejší prístup je počítať čas od momentu pripojenia a obnoviť reláciu pred uplynutím tohto limitu:
import time
class TTLAwareSession:
TTL = 600 # sekundy
REFRESH_MARGIN = 60 # opätovné pripojenie 60 s pred vypršaním
def __init__(self):
self.connected_at = None
async def connect(self):
# ... pripojenie ...
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() # Nová relácia
# ... odoslanie textu ...
Opätovné pripojenie 60 sekúnd pred vypršaním ťa ochráni pred prerušením uprostred syntézy.
Pool relácií
Pre aplikácie s vysokou prevádzkou si udržuj pool opätovne použiteľných relácií:
class SessionPool:
def __init__(self, api_key, pool_size=10):
self.api_key = api_key
self.pool_size = min(pool_size, 50) # Max 50 na tím
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
# Čakaj na uvoľnenie relácie
return await self.available.get()
async def release(self, session):
await self.available.put(session)
Veľkosť poolu udržuj ako zlomok limitu 50 relácií, aby si mal rezervu pre ostatné služby tvojej aplikácie.
Metriky na sledovanie
Aby si udržal relácie v produkčnom prostredí zdravé, monitoruj:
- Počet aktívnych relácií: nesmie prekročiť 50
- Miera opätovných pripojení: vysoká miera poukazuje na problém so sieťou alebo životnosťou relácie
- Latencia prvého audio.delta: meria odozvu služby
- Chyby WebSocket: abnormálne kódy uzavretia (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)
Kľúčové poznatky
- Dokumentácia spomína 600-sekundové povolenie relácie: pre istotu ho počítaj od momentu pripojenia
- Implementuj automatické opätovné pripojenie s exponenciálnym oneskorením
- Obnov reláciu pred uplynutím tohto limitu (s 60-sekundovou rezervou)
- Pre aplikácie s vysokou prevádzkou používaj pool relácií
- Dodržuj limit 50 súbežných relácií na tím
- V produkčnom prostredí monitoruj metriky pripojenia