liveavatar-debug

LiveAvatar 调试指南

根据症状排查 LiveAvatar 集成问题。找到下方对应的症状并按照修复方法操作。

虚拟形象没有声音／不响应语音

最可能的原因：FULL 模式中缺少 context_id。

如果没有 context_id，虚拟形象会进入受限模式——只传输视频，但忽略用户输入。不会抛出错误。

**修复方法：**通过 POST /v1/contexts 创建上下文，至少包含 prompt 字段。将返回的 context_id 添加到会话令牌的 avatar_persona 中。

其他原因：

• 浏览器麦克风权限被阻止（检查 iframe 上的 allow="microphone"）
• 已启用按键通话，但未发送 PTT 事件
• 操作系统级别的麦克风静音

音频杂乱或失真（LITE 模式）

最可能的原因：音频格式错误。

必需格式：PCM 16 位有符号、24KHz、base64。格式错误时不会返回错误。

检查清单：

• 采样率恰好为 24,000 Hz
• 原始 PCM（没有 WAV/MP3/OGG 标头）
• 16 位有符号，而不是 8 位或 32 位浮点数
• 已进行 Base64 编码
• 分块小于 1MB

**快速测试：**发送已知正常的 440Hz 测试音。如果测试音正常，但 TTS 输出不正常，请重新采样 TTS 输出。

401 错误／会话无法启动

最可能的原因：认证标头错误。

端点	正确的认证方式
POST /v1/sessions/token	X-API-KEY: <api_key>
POST /v1/sessions/start	Authorization: Bearer <session_token>

常见错误：在 /start 上使用 API 密钥，在 /token 上使用 Bearer 令牌，或使用 Bearer 格式传递 API 密钥。

未收到事件（FULL 模式）

• 是否订阅了正确的主题？向 agent-control 发送，从 agent-response 接收
• LiveKit 房间是否已连接？检查连接状态
• JSON 解析是否正确？事件包含 event_type、event_id、session_id

WebSocket 事件被静默丢弃（LITE 模式）

最可能的原因：在 connected 之前发送。

发送任何命令前，请等待 {"type": "session.state_updated", "state": "connected"}。

另请检查：

• 是否使用了正确的事件名称？LITE 使用 agent.*，而不是 avatar.*（后者用于 FULL）
• WebSocket 是否仍处于打开状态？不活动 5 分钟后超时

会话超时

不活动 5 分钟会导致会话终止。

• **FULL：**使用 Bearer <session_token> 调用 POST /v1/sessions/keep-alive
• **LITE：**通过 WebSocket 发送 {"type": "session.keep_alive", "event_id": "..."}

每隔 2-3 分钟发送一次。

沙盒无法启动

• 在会话令牌中设置了 is_sandbox: true
• 虚拟形象 ID 为 dd73ea75-1218-4ef3-92ce-606d5f7fbc0a（会话）或 65f9e3c9-d48b-4118-b73a-4ae2e3cbb8f0（嵌入）
• 未在沙盒模式下使用其他虚拟形象

约 1 分钟后自动终止属于预期行为。

图片虚拟形象失败／没有音频

图片虚拟形象不会自动生成语音。请在 avatar_persona 中指定 voice_id。通过 GET /v1/voices 浏览语音。

自定义 LLM／TTS 无法正常工作

LLM 检查清单：

• 密钥：secret_type: "LLM_API_KEY"
• 配置：正确的 model、secret_id、base_url
• 会话令牌中包含 llm_configuration_id
• 端点支持 OpenAI /chat/completions 协议

TTS 检查清单：

• 密钥：secret_type: "ELEVENLABS_API_KEY"
• 通过 POST /v1/voices/third_party 导入语音
• 使用返回的 LiveAvatar voice_id（而不是 ElevenLabs ID）

CORS／网络错误

• API 调用应来自后端，而不是浏览器
• 为 LiveKit 和 WebSocket 放行出站 wss:// 连接
• 放行 *.livekit.cloud、api.liveavatar.com、embed.liveavatar.com

通用处理方法

1. 从沙盒模式开始，以排除计费问题
2. 检查会话状态：GET /v1/sessions/{id}
3. 检查转录文本：GET /v1/sessions/{id}/transcript
4. 检查额度：GET /v1/users/credits
5. 确认未混用 FULL 和 LITE 事件系统