如何调试实时 AI 数字人会话

调试实时 AI 数字人会话时，应沿着一次用户轮次依次检查输入、Agent、TTS、动作服务、客户端渲染和产品状态，并停在第一个缺失或明显迟到的事件上。屏幕上的“面部冻结”只是现象，不等于根因。

核心结论

• 使用关联 ID、UTC 时间和可复现输入追踪一次完整轮次。
• 在调查动作前先确认 TTS 音频是否真实产生并被发送。
• 区分连接故障、动作故障与本地渲染故障。
• 保留错误码和关闭原因，不要全部改写成“会话失败”。

从第一个缺失事件开始

先写出预期序列：收到输入、转写完成、Agent 开始响应、产生 TTS 分片、动作服务接收音频、客户端收到动作、开始播放、播放完成。OpenTelemetry Trace可以把这些事件连接起来，而无需让所有组件使用同一种日志格式。

先用一段已知正常的短 PCM 音频复现。如果这段音频能推动数字人，问题更可能位于上游 TTS、编码、分片或应用状态；如果仍失败，再检查动作会话与客户端。Web Audio API有助于确认浏览器是否正确解码、调度和播放音频。

把现象映射到责任层

用户说话后没有反应。 检查麦克风权限、输入帧、VAD 与最终转写。浏览器的 getUserMedia需要安全上下文与明确授权，数字人渲染器无法修复被阻止的麦克风。

Agent 已回答但数字人无声。 检查 TTS 格式、采样率、声道、分片顺序和结束信号。

有声音但面部冻结。 问题范围已缩小到动作传递、资源状态、渲染或回退路径。背景标签页和刷新率也会影响 requestAnimationFrame的视觉更新。

口型启动过晚。 比较音频调度与首个动作消费时间，不要直接叠加固定延迟。

会话断开。 记录 WebSocket close code 或 RTC 状态变化、网络状态、Token 年龄与最后一个成功事件。MDN 提供了 WebSocket close code说明。

数字人说错内容。 这通常属于 Agent、检索、工具或应用问题，而不是动画问题。工具参数、结果、错误与执行时间应和对话轮次一起关联。

使用受控复现

先把变量缩减为一个数字人、一个声音、一个浏览器、一段输入音频且不调用可选工具，然后逐项加回。对 RTC 路径使用 getStats观察丢包、抖动与帧表现；对 WebSocket 路径记录连接状态与消息序号。

日志不应默认保存完整 Prompt、转写、API Key 或工具负载。参考 OWASP Logging Cheat Sheet，记录足够定位问题的上下文，但不要制造第二份敏感数据仓库。

调试 Spatius 集成

Spatius Motion Server 接收数字人语音音频并返回动作数据，AvatarKit 在本地渲染；应用仍然拥有 ASR、LLM、TTS、工具和工作流状态。不同集成路径的连接责任不同，因此相同现象可能对应不同责任方。

常见问题