Správa relací WebSocket
Na této stránce
Aktualizováno 3. listopadu 2026 na základě stránky xAI Text to Speech, která zmiňuje 600sekundové „povolení relace“ a připojení bez časového limitu. Níže uvedená strategie obnovy je preventivním opatřením. Zdroj: Text to Speech.
Zvládni životní cyklus relace
V produkčním prostředí je to právě robustní správa relací WebSocket, co odděluje prototyp od spolehlivého produktu. Relace TTS mají specifická omezení (doba života, limity souběžnosti), která musí tvoje aplikace správně zpracovávat.
Životní cyklus relace
Relace WebSocket pro TTS prochází tímto cyklem:
- Otevření: připojení k
wss://api.x.ai/v1/ttss parametry - Aktivní: výměna zpráv
text.delta/audio.delta - Normální uzavření: klient nebo server ukončí připojení
- Neočekávané uzavření: chyba, údržba nebo vypršení 600sekundového povolení relace zmíněného v dokumentaci
Detekce uzavření
Server může připojení kdykoli uzavřít (interní chyba, údržba, konec povolení relace). Tvoje aplikace by měla vždy zpracovávat událost uzavření:
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é připojení
Pro dlouhodobě běžící aplikace implementuj opětovné připojení s exponenciálním backoffem:
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é připojení a opakování
await self.connect()
return await self.synthesize(text)
Správa životnosti relace
Stránka xAI Text to Speech zmiňuje 600sekundové „povolení relace“, ale neupřesňuje, kdy začíná ani co se stane po jeho vypršení, a samostatně uvádí, že připojení nemá žádný časový limit. Nejopatrnější přístup je počítat čas od okamžiku připojení a obnovit relaci před uplynutím této doby:
import time
class TTLAwareSession:
TTL = 600 # sekundy
REFRESH_MARGIN = 60 # opětovné připojení 60 s před vypršením
def __init__(self):
self.connected_at = None
async def connect(self):
# ... připojení ...
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á relace
# ... odeslání textu ...
Opětovné připojení 60 sekund před vypršením ti zabrání v přerušení uprostřed syntézy.
Pool relací
Pro aplikace s vysokým provozem udržuj pool opakovaně použitelných relací:
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
# Počkej na uvolnění relace
return await self.available.get()
async def release(self, session):
await self.available.put(session)
Velikost poolu udržuj jako zlomek limitu 50 relací, abys měl rezervu pro další služby své aplikace.
Metriky ke sledování
Aby byly relace v produkčním prostředí zdravé, monitoruj:
- Počet aktivních relací: nesmí překročit 50
- Míra opětovného připojení: vysoká míra ukazuje na problém se sítí nebo životností
- Latence prvního audio.delta: měří, jak rychle služba reaguje
- Chyby WebSocket: abnormální kódy uzavření (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)
Klíčové poznatky
- Dokumentace zmiňuje 600sekundové povolení relace: pro jistotu ho počítej od okamžiku připojení
- Implementuj automatické opětovné připojení s exponenciálním backoffem
- Obnov relaci před vypršením této doby (s 60sekundovou rezervou)
- Pro aplikace s vysokým provozem použij pool relací
- Dodržuj limit 50 souběžných relací na tým
- V produkčním prostředí monitoruj metriky připojení