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.
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 ────────│- Gửi
session.configtrước tiên và chờsession.configured. - Gửi bao nhiêu
input.textcũng được. Server tự tách câu; với mỗi đoạn được sinh, bạn nhậnaudio.start, các frame audio nhị phân, rồiaudio.done. - Gửi
input.commitđể đọc hết phần chữ đã gửi mà vẫn giữ kết nối (server trảinput.committedkhi audio của phần đó xong), hoặcinput.doneđể đọc hết và kết thúc: server gửisession.donerồ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:
type | Field | Ý nghĩa |
|---|---|---|
session.config | session | Cấu hình giọng và định dạng. Gửi đầu tiên. |
input.text | text | Chữ 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:
typekhác bốn giá trị trên: sự kiệnerrorvớicode: 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.configured | Cấu hình đã nhận (session_id, response_format, stream_audio, split_granularity). Bắt đầu gửi chữ. |
audio.start | Bắt đầu audio của một đoạn. |
| binary frame | Audio 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.done | Hết audio của đoạn. |
input.committed | Toàn bộ chữ đến input.commit đã đọc xong. |
session.done | Sau input.done; server đóng kết nối (1000). |
error | Có 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.
code | Khi nào | Sau đó |
|---|---|---|
insufficient_credit | Hết credit giữa phiên | Đóng kết nối, mã 1008 |
voice_not_found | session.voice không tồn tại | Phiên vẫn mở; gửi lại session.config đúng |
input_too_long | Mộ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_request | Text frame không phải JSON object hợp lệ, hoặc sai field | Phiên vẫn mở |
rate_limited | Quá số phiên đồng thời (thường đã trả 429 trước upgrade) | Thử lại sau |
upstream_unavailable | Dịch vụ giọng nói lỗi hoặc ngắt phiên | Đóng kết nối, mã 1013 |
internal_error | Lỗ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: truecho độ 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).clausetá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.commitgiữa các lượt,input.donekhi 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_limitedngay, không xếp hàng. Xem Giới hạn tốc độ.