用 LiveKit 集成 AI Avatar：Spatius LiveKit Plugin 开发者指南

如果你正在用 LiveKit Agents 构建语音 AI 应用，给它加上一张实时数字人面孔，往往是提升感知参与度的高杠杆改动。技术门槛比想象中低：如果你的语音管线已经跑在 LiveKit 上，Spatius LiveKit Plugin 可以作为一个依赖接入，并保持配置最小化。

这篇指南解释集成如何工作、如何设置，以及生产环境里要注意什么。

为什么 LiveKit + AI Avatar 是天然组合

LiveKit 是流行的开源 WebRTC 框架，常被用于实时语音和视频应用。LiveKit Agents 是构建 AI voice agents 的 Python 框架，负责 ASR、LLM 和 TTS 编排。Spatius 负责 LiveKit Agents 本身不处理的部分：根据语音 AI 生成的音频，实时驱动数字人的脸。

这种集成之所以自然，是因为 Spatius 的架构很清晰。Spatius 不替换也不接管你的语音管线；你的 LLM、语音模型和会话逻辑保持不变。Spatius 增加的是数字人的面部渲染层。

为什么不直接从云端推视频？ 原因和选择 LiveKit 而不是完全托管视频会议产品类似：控制权、延迟和成本。云渲染数字人视频通常需要每路 1-2 MB/s。Spatius 的端侧渲染方式只传输 10-20 KB/s 的 Motion data（驱动参数），减少约 99% 带宽，因为传的是 Motion data，不是渲染后的视频帧。数字人在浏览器中用 WebGL 或 WebGPU 渲染。

架构概览

User Speech
    ↓
[LiveKit Room] -> ASR -> LLM -> TTS (your stack)
                                    ↓
                            Spatius Plugin
                                    ↓
                    [Cloud: Motion Server]
                                    ↓
                          Motion data (~10-20 KB/s)
                                    ↓
                        [Browser: 3DGS avatar renders locally]

Spatius LiveKit Plugin 接入 Agent 的 TTS 音频输出，将 AI 生成音频发送到 Motion Server，生成 Motion data（驱动参数）。浏览器端 SDK 接收 Motion data 并用 WebGL/WebGPU 实时渲染 3DGS 数字人。口型和表情由 Motion data 驱动，不依赖视频推流。

重要范围说明：LiveKit Plugin 当前仅支持 Web。iOS 和 Android 部署请使用 Basic Mode 或 Custom Mode，并接入对应平台 SDK：iOS 使用 AvatarKit.xcframework，Android 使用 Gradle 包 ai.spatialwalk:avatarkit。

前置条件

开始前需要：

LiveKit Cloud 账号或自托管 LiveKit server
已有 LiveKit Agents 语音管线（Python）
Spatius 账号。Free tier 包含 500 credits/月，约 50 分钟，足够开发和测试
浏览器客户端 Node.js 环境。Spatius client SDK 通过 npm 包 @spatius/avatarkit-rtc 分发

需要的 Spatius 凭证包括 App ID、API Key、Avatar ID 和 Session Token，可在 app.spatius.ai 控制台获取。

服务端：Python 设置

安装 Spatius LiveKit plugin：

pip install livekit-plugins-spatius

在 LiveKit Agents 管线中，与 TTS 一起导入并配置 Spatius plugin：

from livekit.plugins import spatius

spatius_plugin = spatius.AvatarPlugin(
    app_id="your_app_id",
    api_key="your_api_key",
    avatar_id="your_avatar_id",
)

agent = VoicePipelineAgent(
    vad=...,
    stt=...,
    llm=...,
    tts=...,
    avatar=spatius_plugin,
)

Plugin 会把 TTS 音频流发送到 Spatius Motion Server，并让客户端获得同步的 Motion data（驱动参数）。

关键版本说明：浏览器客户端要求 livekit-client 精确为 2.16.1。其他版本可能导致连接或音频同步问题。请在 package.json 中锁定：

{
  "dependencies": {
    "livekit-client": "2.16.1",
    "@spatius/avatarkit-rtc": "latest"
  }
}

浏览器客户端设置

安装客户端 SDK：

npm install @spatius/avatarkit-rtc livekit-client@2.16.1

在浏览器应用中初始化数字人：

import { AvatarKitRTC } from '@spatius/avatarkit-rtc';

const avatarKit = new AvatarKitRTC({
  appId: 'your_app_id',
  sessionToken: 'your_session_token',
  avatarId: 'your_avatar_id',
  container: document.getElementById('avatar-container'),
});

await avatarKit.connect(livekitRoomUrl, livekitToken);

SDK 会处理 WebGL/WebGPU 初始化、3DGS 模型加载（约 5-10 MB，首次使用下载）和 Motion data 渲染循环。数字人 canvas 会渲染到你提供的容器中。

Demo 仓库

完整 demo 包含服务端 Python agent 和浏览器客户端：

Voice Agent Demo（全平台）：github.com/spatialwalk/avatarkit-voice-agent-demo
Web client：sdk-mode/clients/web

完整 API 参考：docs.spatius.ai

延迟：LiveKit Plugin vs Basic Mode

LiveKit Plugin 的目标是降低 Web 部署的端到端数字人延迟。

Basic Mode 让客户端直接连接 Spatius Motion Server。Spatius 层的额外延迟通常低于 300ms，也就是从 TTS 音频准备好到数字人面部开始动作之间的时间。

LiveKit Plugin 更适合已经用 LiveKit Agents 的 Web 项目，因为它贴合现有 LiveKit-based flow，减少集成复杂度。高并发或跨区域访问时，这种差异更容易被感知。

如果你已经使用 LiveKit Agents 且目标端是 Web，LiveKit Plugin 是推荐路径。如果需要移动端支持（iOS/Android），或希望不依赖 LiveKit 的更简单集成，Basic Mode 更合适。

浏览器渲染发生了什么

浏览器 SDK 使用 WebGL 或 WebGPU 渲染数字人，优先使用 WebGPU，必要时回退到 WebGL。3DGS 模型体积约 5-10 MB，把数字人表示为一组 3D Gaussian splats。相比传统多边形网格，它能在典型会话尺寸下实现高保真、自然光照的外观。

这就是带宽保持在 10-20 KB/s 的原因。 SDK 不从云端拉取视频帧，只接收 Motion data（驱动参数）。计算量较大的渲染发生在用户设备上。

对共享或公开 kiosk 的浏览器部署，这种架构也有隐私优势：数字人在本地渲染，头像层接收的是 AI 生成音频，transcript、prompt 和敏感用户数据可以留在你自己的语音栈里；3DGS 模型首次加载后会缓存。

处理 Avatar Session Token

Session Token 是短期凭证，必须由服务端生成。不要把 API Key 写到客户端代码里。

你的服务端使用 App ID 和 API Key 调用 Spatius API，生成 Session Token 后只把 token 返回给浏览器。浏览器用 token 连接 AvatarKit SDK。demo 仓库提供了 Python 和 Go 的服务端 token 生成示例。

Go SDK：github.com/spatius-ai/spatius-sdk-go
Python SDK：pip install spatius，仓库为 github.com/spatius-ai/spatius-sdk-python

常见问题

数字人渲染了，但口型不同步：通常是 TTS 音频格式不匹配。Spatius 要求 mono 16-bit PCM（s16le），支持 8kHz、16kHz、22050、24kHz、32kHz、44.1kHz 和 48kHz。SDK 不自动重采样，所以需要确认传入格式一致。Python SDK 额外支持 Ogg Opus 输入。

WebSocket 连接失败：确认 endpoint 区域和网络路径。Spatius 服务区域包括 ap-northeast 和 us-west；App ID、API Key、Avatar ID、Session Token 跨区域通用。

iOS 或 Android 上看不到数字人：LiveKit Plugin 仅支持 Web。移动端需要切换到 Basic Mode，并使用平台原生 SDK。iOS 渲染必须用真机测试，模拟器不支持 Metal 渲染。

livekit-client 版本不匹配：如果安装依赖后出现连接或音频问题，运行 npm list livekit-client，确认版本精确为 2.16.1。

先试用再集成

在集成 SDK 前最快的评估方式是使用 Playground。它可以在浏览器中运行一个实时 Spatius 数字人会话，无需注册：spatius.ai/playground

如需了解如何评估任何实时数字人平台，可读：Avatar SDK Demo: How to Test a Real-Time AI Avatar Before You Commit to a Platform