Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

WebSocket-istuntojen hallinta

Oppitunti 11 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Hallitse istunnon elinkaarta
  2. Istunnon elinkaari
  3. Automaattinen uudelleenyhdistäminen
  4. Istunnon keston hallinta
  5. Istuntopooli
  6. Seurattavat mittarit
  7. Keskeiset asiat

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:

  1. Avaus: muodosta yhteys osoitteeseen wss://api.x.ai/v1/tts annetuilla parametreilla
  2. Aktiivinen: vaihda text.delta/audio.delta-viestejä
  3. Normaali sulkeminen: asiakas tai palvelin sulkee yhteyden
  4. 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