Zarządzanie sesjami WebSocket
Na tej stronie
Zaktualizowano 3 listopada 2026 r. na podstawie strony xAI Text to Speech, która wspomina o 600-sekundowym „pozwoleniu na sesję“ i połączeniu bez limitu czasu. Poniższa strategia odnawiania jest środkiem ostrożności. Źródło: Text to Speech.
Opanuj cykl życia sesji
W środowisku produkcyjnym to właśnie solidne zarządzanie sesjami WebSocket odróżnia prototyp od niezawodnego produktu. Sesje TTS mają specyficzne ograniczenia (czas życia, limity współbieżności), które Twoja aplikacja musi poprawnie obsłużyć.
Cykl życia sesji
Sesja WebSocket TTS przechodzi przez następujący cykl:
- Otwieranie: połączenie z
wss://api.x.ai/v1/ttsz odpowiednimi parametrami - Aktywność: wymiana komunikatów
text.delta/audio.delta - Normalne zamykanie: klient lub serwer zamyka połączenie
- Nieoczekiwane zamykanie: błąd, konserwacja lub koniec 600-sekundowego pozwolenia na sesję wspomnianego w dokumentacji
Wykrywanie zamykania
Serwer może zamknąć połączenie w dowolnym momencie (błąd wewnętrzny, konserwacja, koniec pozwolenia na sesję). Twoja aplikacja powinna zawsze obsługiwać zdarzenie zamknięcia:
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")
Automatyczne ponowne łączenie
W aplikacjach działających długo wdroż mechanizm ponownego łączenia z wykładniczym wycofaniem (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:
# Połącz ponownie i spróbuj jeszcze raz
await self.connect()
return await self.synthesize(text)
Zarządzanie czasem życia sesji
Strona xAI Text to Speech wspomina o 600-sekundowym „pozwoleniu na sesję“, nie precyzując, kiedy się ono zaczyna ani co dzieje się po jego zakończeniu, jednocześnie stwierdzając osobno, że połączenie nie ma limitu czasu. Najostrożniejszym podejściem jest odliczanie od momentu nawiązania połączenia i odnowienie sesji przed upływem tego czasu:
import time
class TTLAwareSession:
TTL = 600 # sekundy
REFRESH_MARGIN = 60 # ponowne połączenie 60 s przed wygaśnięciem
def __init__(self):
self.connected_at = None
async def connect(self):
# ... połączenie ...
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() # Nowa sesja
# ... wyślij tekst ...
Ponowne połączenie na 60 sekund przed wygaśnięciem zapobiega przerwaniu syntezy w trakcie jej trwania.
Pula sesji
W aplikacjach o dużym ruchu utrzymuj pulę wielokrotnego użytku sesji:
class SessionPool:
def __init__(self, api_key, pool_size=10):
self.api_key = api_key
self.pool_size = min(pool_size, 50) # Maksymalnie 50 na zespół
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
# Poczekaj na zwolnienie sesji
return await self.available.get()
async def release(self, session):
await self.available.put(session)
Utrzymuj rozmiar puli jako ułamek limitu 50 sesji, aby zachować zapas dla innych usług Twojej aplikacji.
Metryki do monitorowania
Aby utrzymać sesje w dobrym stanie w środowisku produkcyjnym, monitoruj:
- Liczba aktywnych sesji: nie może przekroczyć 50
- Wskaźnik ponownych połączeń: wysoki wskaźnik wskazuje na problem z siecią lub czasem życia sesji
- Opóźnienie pierwszego audio.delta: mierzy responsywność usługi
- Błędy WebSocket: nieprawidłowe kody zamknięcia (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)
Kluczowe wnioski
- Dokumentacja wspomina o 600-sekundowym pozwoleniu na sesję: dla bezpieczeństwa odliczaj je od momentu nawiązania połączenia
- Wdróż automatyczne ponowne łączenie z wykładniczym wycofaniem
- Odnow sesję przed upływem tego czasu (z 60-sekundowym marginesem)
- Używaj puli sesji w aplikacjach o dużym ruchu
- Nie przekraczaj limitu 50 współbieżnych sesji na zespół
- Monitoruj metryki połączeń w środowisku produkcyjnym