AI-VideoAssistant/docs/content/resources/troubleshooting.md

故障排查

本文档汇总常见问题的排查步骤和解决方案。

连接问题

WebSocket 连接失败

症状：无法建立 WebSocket 连接，控制台显示连接错误。

排查步骤：

1. 检查服务状态

   # 检查 Engine 服务是否运行
   curl http://localhost:8000/health
   

2. 验证连接地址

   • 确认 host 和 port 正确
   • 确认 assistant_id 参数存在

3. 检查网络

   • 确认防火墙未阻止 WebSocket
   • 检查 Nginx 代理配置（如有）

4. 查看服务日志

   docker logs ai-assistant-engine
   

常见原因：

• Engine 服务未启动
• assistant_id 无效
• 防火墙阻止 WebSocket 端口

---

API 请求失败

症状：REST API 返回错误或超时。

排查步骤：

1. 检查 API 服务

   curl http://localhost:8080/health
   

2. 验证请求格式

   • Content-Type 是否为 application/json
   • 请求体是否为有效 JSON

3. 检查认证

   • Authorization header 是否正确
   • API Key 是否有效

4. 查看响应详情

   curl -v http://localhost:8080/api/v1/assistants
   

---

助手问题

助手不回复

症状：发送消息后没有收到助手回复。

排查步骤：

1. 检查会话状态

   • 确认收到 session.started 事件
   • 确认没有 error 事件

2. 检查 LLM 配置

   • API Key 是否有效
   • 模型配置是否正确
   • 测试模型连接

3. 查看日志

   • 检查 LLM 调用是否成功
   • 查看是否有超时错误

常见原因：

• LLM API Key 无效或过期
• 模型服务不可用
• 请求超时

---

回复质量差

症状：助手回复不准确、不相关或格式混乱。

排查步骤：

1. 检查提示词

   • 是否有明确的角色定义
   • 是否有清晰的任务描述
   • 是否有必要的约束

2. 调整参数

   • 降低 temperature 提高一致性
   • 调整 max_tokens 控制长度

3. 检查知识库

   • 确认知识库已关联
   • 测试检索结果是否相关

4. 查看对话历史

   • 分析问题出现的模式
   • 收集典型的失败案例

---

语音问题

语音识别不准确

症状：ASR 识别结果与实际说话内容不符。

排查步骤：

1. 检查音频质量

   • 麦克风是否正常工作
   • 环境是否嘈杂
   • 采样率是否正确（16kHz）

2. 验证 ASR 配置

   • 语言设置是否正确
   • 是否配置了热词

3. 测试不同引擎

   • 尝试切换 ASR 服务提供商
   • 对比识别效果

改进建议：

• 添加业务相关的热词
• 使用降噪麦克风
• 选择针对中文优化的 ASR 引擎

---

语音无法播放

症状：TTS 合成成功但没有声音输出。

排查步骤：

1. 检查浏览器设置

   • 是否允许自动播放音频
   • 音量是否静音

2. 验证音频数据

   • 确认收到 output.audio.start 事件
   • 确认收到二进制音频帧
   • 确认收到 output.audio.end 事件

3. 检查音频解码

   • PCM 格式是否正确解析
   • AudioContext 是否正确初始化

4. 测试 TTS 服务

   • 单独测试 TTS 配置
   • 检查 TTS API 状态

---

部署问题

Docker 容器启动失败

症状：容器无法启动或立即退出。

排查步骤：

1. 查看容器日志

   docker logs <container_name>
   

2. 检查资源限制

   docker stats
   

3. 验证配置文件

   • 环境变量是否正确
   • 配置文件路径是否存在

4. 检查端口冲突

   netstat -an | grep <port>
   

---

页面加载空白

症状：浏览器打开页面但内容为空。

排查步骤：

1. 检查浏览器控制台

   • 打开 F12 开发者工具
   • 查看 Console 错误信息

2. 验证静态资源

   • 检查 Network 标签页
   • 确认 JS/CSS 文件加载成功

3. 检查 API 连接

   • 确认 VITE_API_URL 配置正确
   • 测试 API 是否可访问

4. 清除缓存

   # 强制刷新
   Ctrl + Shift + R
   

---

性能问题

响应延迟高

症状：从发送消息到收到回复时间过长。

排查步骤：

1. 定位延迟环节

   • ASR 处理时间
   • LLM 推理时间
   • TTS 合成时间

2. 查看性能指标

   • 检查 metrics.ttfb 事件
   • 分析各环节耗时

3. 优化配置

   • 使用更快的模型
   • 减少 max_tokens
   • 启用流式输出

4. 检查网络

   • 测试到各 API 的延迟
   • 考虑使用更近的服务区域

---

日志查看

服务端日志

# Docker 容器日志
docker logs -f ai-assistant-engine

# 查看最近 100 行
docker logs --tail 100 ai-assistant-engine

客户端日志

在浏览器开发者工具中：

1. Console - 查看 JavaScript 错误和日志
2. Network - 查看网络请求和响应
3. WebSocket - 查看 WS 消息（在 Network 标签页）

启用详细日志

设置环境变量启用调试日志：

# Engine 服务
LOG_LEVEL=debug

# API 服务
DEBUG=true

获取帮助

如果以上方法无法解决问题：

1. 收集相关日志和错误信息
2. 描述复现步骤
3. 提交 Issue 或联系技术支持