Sota Voice
Tài liệu

Voice agent qua WebSocket

Stream chữ từ LLM vào, nhận audio PCM ra theo từng câu, trên một kết nối.

Xem dạng Markdown

Với voice agent, LLM sinh chữ từng mảnh và người dùng không muốn chờ cả câu trả lời. Mở một WebSocket tới wss://voice-be.sotalabs.io/v1/audio/speech/stream, gửi chữ ngay khi có, và phát audio ngay khi nhận.

Đặc tả đầy đủ của giao thức: /asyncapi.yaml (AsyncAPI 3.0).

Sơ đồ message

Client                                         Sota Voice
  │  GET /v1/audio/speech/stream (upgrade)          │
  │  Authorization: Bearer sk_live_... hoặc ?token= │
  │ ───────────────────────────────────────────────▶│
  │ ◀─────────────────────────── 101 Switching ─────│
  │                                                 │
  │  {"type":"session.config","session":{...}}      │
  │ ───────────────────────────────────────────────▶│
  │ ◀──────────── {"type":"session.configured",...} │
  │                                                 │
  │  {"type":"input.text","text":"Xin chào, "}      │
  │ ───────────────────────────────────────────────▶│
  │  {"type":"input.text","text":"tôi là Sota."}    │
  │ ───────────────────────────────────────────────▶│
  │ ◀──────────────────────── {"type":"audio.start"}│
  │ ◀────────────────────────────── [binary audio] │  (nhiều frame)
  │ ◀───────────────────────── {"type":"audio.done"}│  (hết một câu)
  │                                                 │
  │  {"type":"input.commit"}   (hết lượt, giữ kết nối)
  │ ───────────────────────────────────────────────▶│
  │ ◀────── ... audio còn lại ... {"type":"input.committed"}
  │                                                 │
  │  {"type":"input.done"}     (kết thúc phiên)     │
  │ ───────────────────────────────────────────────▶│
  │ ◀────── ... audio còn lại ... {"type":"session.done"}
  │ ◀─────────────────────────── close 1000 ────────│
  1. Gửi session.config trước tiên và chờ session.configured.
  2. Gửi bao nhiêu input.text cũng được. Server tự tách câu; với mỗi đoạn được sinh, bạn nhận audio.start, các frame audio nhị phân, rồi audio.done.
  3. Gửi input.commit để đọc hết phần chữ đã gửi mà vẫn giữ kết nối (server trả input.committed khi audio của phần đó xong), hoặc input.done để đọc hết và kết thúc: server gửi session.done rồi đóng kết nối.

Message client gửi

Mọi message là JSON object trong text frame. Chỉ có bốn type, phân biệt hoa thường:

typeFieldÝ nghĩa
session.configsessionCấu hình giọng và định dạng. Gửi đầu tiên.
input.texttextChữ cần đọc, tính phí theo ký tự.
input.commit(không có)Đọc hết phần đã gửi, giữ kết nối.
input.done(không có)Đọc hết phần đã gửi rồi kết thúc phiên.

Field của session: voice (giọng có sẵn hoặc name giọng đã nhân bản, mặc định default), response_format (pcm mặc định, hoặc mp3, wav, opus, aac, flac), stream_audio (gửi frame ngay khi sinh thay vì cả đoạn), split_granularity (sentence mặc định hoặc clause; giá trị khác: lỗi invalid_request), literal_punctuation.

Server kiểm tra từng message trước khi chuyển đi:

  • type khác bốn giá trị trên: sự kiện error với code: invalid_request (unsupported message type).
  • Chỉ nhận đúng các field đã liệt kê. Field lạ, field lặp lại, hoặc field chỉ khác chữ hoa thường (Voice) đều bị từ chối.
  • Message bị từ chối không được gửi đi, không bị tính phí, và phiên vẫn mở.
  • Client không được gửi binary frame: kết nối bị đóng với mã 1003 (binary_not_supported).

Message server gửi

MessageÝ nghĩa
session.configuredCấu hình đã nhận (session_id, response_format, stream_audio, split_granularity). Bắt đầu gửi chữ.
audio.startBắt đầu audio của một đoạn.
binary frameAudio theo response_format. Với pcm: 16-bit có dấu little-endian, mono, 44,1 kHz. Ghép các frame theo thứ tự.
audio.doneHết audio của đoạn.
input.committedToàn bộ chữ đến input.commit đã đọc xong.
session.doneSau input.done; server đóng kết nối (1000).
errorCó lỗi, xem bảng dưới.

Lỗi và đóng kết nối

Lỗi trước khi upgrade là lỗi JSON HTTP thường (401 unauthorized, 402 insufficient_credit, 429 rate_limited, 503 upstream_unavailable), không mở WebSocket. Sau khi mở, lỗi đến dưới dạng sự kiện error. Lỗi của gateway có code; lỗi từ dịch vụ giọng nói chỉ có message.

codeKhi nàoSau đó
insufficient_creditHết credit giữa phiênĐóng kết nối, mã 1008
voice_not_foundsession.voice không tồn tạiPhiên vẫn mở; gửi lại session.config đúng
input_too_longMột input.text vượt giới hạn mỗi message (mặc định 5.000 ký tự)Phiên vẫn mở; chữ không được gửi, không tính phí
invalid_requestText frame không phải JSON object hợp lệ, hoặc sai fieldPhiên vẫn mở
rate_limitedQuá số phiên đồng thời (thường đã trả 429 trước upgrade)Thử lại sau
upstream_unavailableDịch vụ giọng nói lỗi hoặc ngắt phiênĐóng kết nối, mã 1013
internal_errorLỗi gateway ngoài dự kiếnĐóng kết nối, mã 1011

Lý do đóng khác: idle_timeout (mã 1000, không có input.text trong 5 phút) và binary_not_supported (mã 1003).

Tính phí

Mỗi input.text tốn số ký tự của text (code point NFC, tính cả khoảng trắng và dấu câu). Phiên cần số dư lớn hơn 0 để mở. Credit được giữ trước theo lô 1.000 ký tự; số dư có thể âm tối đa một lô trong một phiên, và phần giữ chưa dùng được trả lại khi phiên kết thúc. Chữ đã chuyển đi vẫn bị tính phí dù bạn ngắt kết nối.

Ví dụ: voice agent bằng Python

Server-side, dùng khóa API. LLM ở đây là một API chat bất kỳ có stream; mỗi mảnh chữ được gửi ngay thành một input.text.

import asyncio
import json
import os

import websockets  # pip install websockets
from openai import AsyncOpenAI  # LLM của bạn, ví dụ dùng API chat tương thích OpenAI

URL = "wss://voice-be.sotalabs.io/v1/audio/speech/stream"
llm = AsyncOpenAI()  # đọc OPENAI_API_KEY của nhà cung cấp LLM


async def speak_turn(ws, question: str) -> None:
    stream = await llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
        stream=True,
    )
    async for chunk in stream:
        delta = chunk.choices[0].delta.content if chunk.choices else None
        if delta:
            await ws.send(json.dumps({"type": "input.text", "text": delta}))
    # Hết lượt: đọc nốt phần còn lại nhưng giữ kết nối cho lượt sau.
    await ws.send(json.dumps({"type": "input.commit"}))


async def receive(ws, out) -> None:
    async for msg in ws:
        if isinstance(msg, bytes):
            out.write(msg)  # PCM s16le, mono, 44.1 kHz: đưa vào bộ phát của bạn
            continue
        event = json.loads(msg)
        if event["type"] == "input.committed":
            print("đã đọc xong một lượt")
        elif event["type"] == "error":
            print("lỗi:", event.get("code"), event["message"])
        elif event["type"] == "session.done":
            return


async def main() -> None:
    headers = {"Authorization": f"Bearer {os.environ['SOTA_API_KEY']}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "session.config",
            "session": {"voice": "default", "response_format": "pcm", "stream_audio": True},
        }))
        configured = json.loads(await ws.recv())
        assert configured["type"] == "session.configured", configured

        with open("agent.pcm", "wb") as out:
            receiver = asyncio.create_task(receive(ws, out))
            await speak_turn(ws, "Giới thiệu ngắn về Hà Nội.")
            await ws.send(json.dumps({"type": "input.done"}))
            await receiver


asyncio.run(main())

Nghe thử file PCM: ffplay -f s16le -ar 44100 -ch_layout mono agent.pcm.

Từ trình duyệt

Trang web không được giữ khóa API. Server của bạn cấp token ngắn hạn (xem Xác thực), trang mở WebSocket với ?token=. Token sống 5 phút và chỉ dùng cho route này; origin của trang phải được deployment cho phép.

const SAMPLE_RATE = 44100; // PCM s16le, mono
const JITTER_SEC = 0.2; // bộ đệm chống giật: 150-300 ms

// Gọi từ một thao tác của người dùng (click) để trình duyệt cho phép phát âm thanh.
export async function speak(textChunks) {
  // Endpoint của server bạn, gọi POST /v1/tokens bằng khóa API.
  const { token } = await (await fetch('/sota-token', { method: 'POST' })).json();
  const ws = new WebSocket(
    `wss://voice-be.sotalabs.io/v1/audio/speech/stream?token=${encodeURIComponent(token)}`,
  );
  ws.binaryType = 'arraybuffer';

  const ctx = new AudioContext({ sampleRate: SAMPLE_RATE });
  let playAt = 0;
  let carry = null; // byte lẻ cuối frame trước (một mẫu có thể bị cắt giữa hai frame)

  function play(bytes) {
    if (carry !== null) {
      const joined = new Uint8Array(bytes.length + 1);
      joined[0] = carry;
      joined.set(bytes, 1);
      bytes = joined;
      carry = null;
    }
    if (bytes.length % 2) {
      carry = bytes[bytes.length - 1];
      bytes = bytes.subarray(0, bytes.length - 1);
    }
    const samples = bytes.length / 2;
    if (!samples) return;
    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
    const buffer = ctx.createBuffer(1, samples, SAMPLE_RATE);
    const channel = buffer.getChannelData(0);
    for (let i = 0; i < samples; i++) channel[i] = view.getInt16(i * 2, true) / 32768;

    const source = ctx.createBufferSource();
    source.buffer = buffer;
    source.connect(ctx.destination);
    // Lần đầu, hoặc khi bộ đệm cạn: lùi thời điểm phát thêm JITTER_SEC để tích đủ dữ liệu.
    if (playAt < ctx.currentTime) playAt = ctx.currentTime + JITTER_SEC;
    source.start(playAt);
    playAt += buffer.duration;
  }

  ws.onopen = () =>
    ws.send(JSON.stringify({
      type: 'session.config',
      session: { voice: 'default', response_format: 'pcm', stream_audio: true },
    }));

  ws.onmessage = async (event) => {
    if (typeof event.data !== 'string') return play(new Uint8Array(event.data));
    const msg = JSON.parse(event.data);
    if (msg.type === 'session.configured') {
      for await (const text of textChunks) ws.send(JSON.stringify({ type: 'input.text', text }));
      ws.send(JSON.stringify({ type: 'input.done' }));
    } else if (msg.type === 'error') {
      console.error(msg.code ?? 'speech_error', msg.message);
    }
  };
}

textChunks là bất kỳ iterable (đồng bộ hoặc async) nào trả về chuỗi, ví dụ các mảnh chữ từ LLM.

Mẹo cho realtime

  • Bộ đệm chống giật (jitter buffer) 150-300 ms. Audio đến theo từng frame qua mạng, khoảng cách giữa các frame không đều. Hãy đệm 150-300 ms trước khi bắt đầu phát, và đệm lại khi bộ đệm cạn, như ví dụ trên. Ít hơn dễ bị ngắt quãng; nhiều hơn làm agent trả lời chậm.
  • Dùng response_format: "pcm" và stream_audio: true cho độ trễ thấp nhất; không cần giải mã.
  • Gửi chữ ngay khi LLM sinh ra, đừng gom cả câu: server tự tách câu (split_granularity). clause tách cả ở dấu phẩy, chắc hơn nhưng ngữ điệu kém liền mạch và tốn GPU hơn.
  • Một kết nối cho cả cuộc hội thoại: dùng input.commit giữa các lượt, input.done khi kết thúc. Phiên tự đóng sau 5 phút không có input.text.
  • Mỗi tài khoản có giới hạn số phiên/request realtime đồng thời; vượt quá thì nhận 429 rate_limited ngay, không xếp hàng. Xem Giới hạn tốc độ.