Премини към основното съдържание
Български— Изберете език
Меню

Съобщения през WebSocket: текст и аудио

Урок 10 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Протокол за съобщения на TTS
  2. Съобщения от клиент към сървър
  3. Съобщения от сървър към клиент
  4. Пълният поток на комуникация
  5. Пълна реализация на Python
  6. Реализация на JavaScript (Node.js)
  7. Обработка на множество делти
  8. Ключови изводи

Обновено на 3 ноември 2026 г., въз основа на страницата Text to Speech на xAI: делти до 60 000 знака, отмяна (text.clear, audio.clear) и таблица за произношение (session.update, session.updated). Източник: Text to Speech.

Протокол за съобщения на TTS

След като връзката през WebSocket се установи, комуникацията протича чрез размяна на JSON съобщения. Вие изпращате текст, а сървърът отговаря с аудио, кодирано в base64. Разбирането на този протокол е от съществено значение за правилното внедряване на потоково предаване на TTS.

Съобщения от клиент към сървър

Вашето приложение изпраща четири типа съобщения до сървъра: text.delta и text.done за текста, text.clear за отмяна и session.update за конфигуриране.

text.delta: изпращане на част от текста

Съобщението text.delta изпраща фрагмент от текст за преобразуване. Можете да изпращате текста на последователни части:

{"type": "text.delta", "delta": "Hello, and welcome to "}
{"type": "text.delta", "delta": "our presentation on speech synthesis."}

Всяка делта може да съдържа до 60 000 знака, като общият текст няма ограничение. Сървърът започва да генерира аудио веднага щом разполага с достатъчно контекст, за да произведе естествено произношение.

text.done: сигнализиране на края на текста

Съобщението text.done информира сървъра, че сте приключили с изпращането на текст за тази последователност:

{"type": "text.done"}

След получаването на това съобщение сървърът завършва генерирането на аудиото и изпраща съобщение audio.done. След това можете да започнете да изпращате нови делти за нова последователност.

text.clear: отмяна на текущата последователност

text.clear отменя текущата последователност: сървърът спира генерирането на аудио, изтрива данните в паметта си и отговаря с audio.clear. Връзката е незабавно готова за следващата последователност без ново ръкостискане на WebSocket; xAI оценява спестеното време на около 600 ms за отдалечен клиент. Това е механизмът за прекъсване („barge-in“), когато потребителят се намеси.

{"type": "text.clear"}

session.update: коригиране на произношението

session.update инсталира или заменя таблицата replace на връзката: всяка фраза, открита в текста, се заменя с нейната говорима форма преди синтеза, без да се променя изпратеният от Вас текст или броят на таксуваните знаци. Изпратете го преди първия text.delta, за да обхване цялата връзка; актуализация, получена по средата на последователност, важи едва от следващата последователност.

{"type": "session.update", "replace": {"kubectl": "kube cuttle"}}

Съобщения от сървър към клиент

Сървърът отговаря с пет типа съобщения: audio.delta, audio.done и error, описани по-долу, плюс audio.clear, което потвърждава отмяната, и session.updated, което връща активната таблица replace.

audio.delta: част от аудио

Съобщението audio.delta съдържа аудио фрагмент, кодиран в base64:

{
  "type": "audio.delta",
  "delta": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2..."
}

Всяка делта представлява валиден аудио фрагмент, който можете да декодирате и възпроизведете незабавно. Делтите пристигат в процеса на генериране.

audio.done: генерирането приключи

Съобщението audio.done сигнализира, че цялото аудио за изпратената от Вас текстова последователност е генерирано:

{
  "type": "audio.done",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

trace_id е уникален идентификатор за последователността, полезен за отстраняване на грешки и проследяване.

error: възникнала е грешка

Ако нещо се обърка, сървърът изпраща съобщение за грешка:

{
  "type": "error",
  "message": "Invalid text encoding"
}

Пълният поток на комуникация

Ето как протича типична сесия:

Client                          Server
  |                                |
  |-- text.delta ("Hello, ") ----->|
  |-- text.delta ("how are ") ---->|
  |-- text.delta ("you?") -------->|
  |<-- audio.delta (chunk 1) -----|
  |<-- audio.delta (chunk 2) -----|
  |-- text.done ----------------->|
  |<-- audio.delta (chunk 3) -----|
  |<-- audio.done ----------------|

Сървърът може да започне да изпраща съобщения audio.delta, преди дори да сте изпратили text.done. Това е същинската идея на потоковото предаване: генерирането започва възможно най-рано.

Пълна реализация на Python

import asyncio
import websockets
import json
import base64

async def stream_tts(api_key, text, voice="eve", language="en"):
    uri = f"wss://api.x.ai/v1/tts?language={language}&voice={voice}&codec=mp3"
    headers = {"Authorization": f"Bearer {api_key}"}

    audio_chunks = []

    async with websockets.connect(uri, additional_headers=headers) as ws:
        # Изпращане на текста на части от 2000 знака
        chunk_size = 2000
        for i in range(0, len(text), chunk_size):
            chunk = text[i:i + chunk_size]
            await ws.send(json.dumps({
                "type": "text.delta",
                "delta": chunk
            }))

        # Сигнализиране на края на текста
        await ws.send(json.dumps({"type": "text.done"}))

        # Получаване на аудио частите
        async for message in ws:
            data = json.loads(message)

            if data["type"] == "audio.delta":
                audio_bytes = base64.b64decode(data["delta"])
                audio_chunks.append(audio_bytes)

            elif data["type"] == "audio.done":
                print(f"Generation finished (trace: {data['trace_id']})")
                break

            elif data["type"] == "error":
                raise Exception(f"TTS error: {data['message']}")

    # Сглобяване на пълното аудио
    return b"".join(audio_chunks)

Реализация на JavaScript (Node.js)

const WebSocket = require("ws");

function streamTTS(apiKey, text, voice = "eve", language = "en") {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(
      `wss://api.x.ai/v1/tts?language=${language}&voice=${voice}&codec=mp3`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const audioChunks = [];

    ws.on("open", () => {
      // Изпращане на текста
      ws.send(JSON.stringify({ type: "text.delta", delta: text }));
      ws.send(JSON.stringify({ type: "text.done" }));
    });

    ws.on("message", (raw) => {
      const data = JSON.parse(raw);

      if (data.type === "audio.delta") {
        audioChunks.push(Buffer.from(data.delta, "base64"));
      } else if (data.type === "audio.done") {
        ws.close();
        resolve(Buffer.concat(audioChunks));
      } else if (data.type === "error") {
        ws.close();
        reject(new Error(data.message));
      }
    });

    ws.on("error", reject);
  });
}

Обработка на множество делти

За текст, генериран прогресивно (например изход от LLM), изпращайте всеки токен директно към TTS WebSocket:

async def llm_to_speech(ws_tts, llm_stream):
    async for token in llm_stream:
        await ws_tts.send(json.dumps({
            "type": "text.delta",
            "delta": token
        }))

    await ws_tts.send(json.dumps({"type": "text.done"}))

Тази архитектура „потоков LLM към потоков TTS“ осигурява най-ниската възможна латентност: потребителят чува отговора, докато LLM все още генерира.

Ключови изводи

  • Четири клиентски съобщения: text.delta (изпращане на текст), text.done (край на текста), text.clear (отмяна) и session.update (таблица replace)
  • Пет сървърни съобщения: audio.delta (аудио част), audio.done (край), audio.clear (потвърждение за отмяна), session.updated и error
  • Аудиото е кодирано в base64 в съобщенията audio.delta
  • Сървърът започва генерирането, преди да получи text.done
  • Всяка текстова делта е ограничена до 60 000 знака
  • Свързването на потоков LLM към потоков TTS осигурява най-ниската латентност