WebSocket-istuntojen hallinta
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Text to Speech -sivun perusteella, jossa mainitaan 600 sekunnin “istuntolupa” ja yhteys, jossa ei ole aikakatkaisua. Alla oleva uusimisstrategia on varotoimenpide. Lähde: Text to Speech.
Hallitse istunnon elinkaarta
Tuotantoympäristössä robusti WebSocket-istuntojen hallinta on se, mikä erottaa prototyypin luotettavasta tuotteesta. TTS-istunnoilla on erityisiä rajoituksia (kesto, samanaikaisuusrajat), jotka sovelluksesi on käsiteltävä oikein.
Istunnon elinkaari
TTS-WebSocket-istunto käy läpi seuraavan syklin:
- Avaus: muodosta yhteys osoitteeseen
wss://api.x.ai/v1/ttsannetuilla parametreilla - Aktiivinen: vaihda
text.delta/audio.delta-viestejä - Normaali sulkeminen: asiakas tai palvelin sulkee yhteyden
- Odottamaton sulkeminen: virhe, huoltotoimet tai dokumentaation mainitseman 600 sekunnin istuntoluvan päättyminen
Sulkemisen havaitseminen
Palvelin voi sulkea yhteyden milloin tahansa (sisäinen virhe, huolto, istuntoluvan päättyminen). Sovelluksesi tulee aina käsitellä sulkemistapahtuma:
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")
Automaattinen uudelleenyhdistäminen
Pitkäikäisille sovelluksille toteuta uudelleenyhdistäminen eksponentiaalisella viiveellä (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:
# Yhdistä uudelleen ja yritä uudelleen
await self.connect()
return await self.synthesize(text)
Istunnon keston hallinta
xAI:n Text to Speech -sivu mainitsee 600 sekunnin “istuntoluvan” kertomatta, milloin se alkaa tai mitä tapahtuu sen päättyessä, ja toteaa erikseen, että yhteydellä ei ole aikakatkaisua. Varovaisin lähestymistapa on laskea aika yhdistymishetkestä ja uusia istunto ennen kyseistä ajankohtaa:
import time
class TTLAwareSession:
TTL = 600 # sekuntia
REFRESH_MARGIN = 60 # yhdistä uudelleen 60 s ennen vanhenemista
def __init__(self):
self.connected_at = None
async def connect(self):
# ... yhteys ...
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() # Uusi istunto
# ... lähetä teksti ...
Uudelleenyhdistäminen 60 sekuntia ennen vanhenemista estää katkokset keskellä synteesiä.
Istuntopooli
Suuren liikenteen sovelluksille pidä yllä poolia uudelleenkäytettäviä istuntoja varten:
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
# Odota, että istunto vapautuu
return await self.available.get()
async def release(self, session):
await self.available.put(session)
Pidä poolin koko murto-osana 50 istunnon rajasta jättääksesi varaa sovelluksesi muille palveluille.
Seurattavat mittarit
Pitääksesi istunnot terveinä tuotannossa, valvo seuraavia:
- Aktiivisten istuntojen määrä: ei saa ylittää 50:tä
- Uudelleenyhdistämisaste: korkea aste viittaa verkko- tai kesto-ongelmaan
- Ensimmäisen audio.delta-viestin viive: mittaa palvelun vasteaikaa
- WebSocket-virheet: epänormaalit sulkemiskoodit (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)
Keskeiset asiat
- Dokumentaatio mainitsee 600 sekunnin istuntoluvan: varmistaaksesi toimivuuden, laske aika yhdistymishetkestä
- Toteuta automaattinen uudelleenyhdistäminen eksponentiaalisella viiveellä
- Uusi istunto ennen sen päättymistä (60 sekunnin varalla)
- Käytä istuntopoolia suuren liikenteen sovelluksissa
- Pysy 50 samanaikaisen istunnon rajassa tiimiä kohden
- Valvo yhteysmittareita tuotannossa