293 lines
5.2 KiB
Markdown
293 lines
5.2 KiB
Markdown
# 故障排查
|
||
|
||
本文档汇总常见问题的排查步骤和解决方案。
|
||
|
||
## 连接问题
|
||
|
||
### WebSocket 连接失败
|
||
|
||
**症状**：无法建立 WebSocket 连接，控制台显示连接错误。
|
||
|
||
**排查步骤**：
|
||
|
||
1. **检查服务状态**
|
||
```bash
|
||
# 检查 Engine 服务是否运行
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
2. **验证连接地址**
|
||
- 确认 host 和 port 正确
|
||
- 确认 assistant_id 参数存在
|
||
|
||
3. **检查网络**
|
||
- 确认防火墙未阻止 WebSocket
|
||
- 检查 Nginx 代理配置（如有）
|
||
|
||
4. **查看服务日志**
|
||
```bash
|
||
docker logs ai-assistant-engine
|
||
```
|
||
|
||
**常见原因**：
|
||
- Engine 服务未启动
|
||
- assistant_id 无效
|
||
- 防火墙阻止 WebSocket 端口
|
||
|
||
---
|
||
|
||
### API 请求失败
|
||
|
||
**症状**：REST API 返回错误或超时。
|
||
|
||
**排查步骤**：
|
||
|
||
1. **检查 API 服务**
|
||
```bash
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
2. **验证请求格式**
|
||
- Content-Type 是否为 application/json
|
||
- 请求体是否为有效 JSON
|
||
|
||
3. **检查认证**
|
||
- Authorization header 是否正确
|
||
- API Key 是否有效
|
||
|
||
4. **查看响应详情**
|
||
```bash
|
||
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. **查看容器日志**
|
||
```bash
|
||
docker logs <container_name>
|
||
```
|
||
|
||
2. **检查资源限制**
|
||
```bash
|
||
docker stats
|
||
```
|
||
|
||
3. **验证配置文件**
|
||
- 环境变量是否正确
|
||
- 配置文件路径是否存在
|
||
|
||
4. **检查端口冲突**
|
||
```bash
|
||
netstat -an | grep <port>
|
||
```
|
||
|
||
---
|
||
|
||
### 页面加载空白
|
||
|
||
**症状**：浏览器打开页面但内容为空。
|
||
|
||
**排查步骤**：
|
||
|
||
1. **检查浏览器控制台**
|
||
- 打开 F12 开发者工具
|
||
- 查看 Console 错误信息
|
||
|
||
2. **验证静态资源**
|
||
- 检查 Network 标签页
|
||
- 确认 JS/CSS 文件加载成功
|
||
|
||
3. **检查 API 连接**
|
||
- 确认 VITE_API_URL 配置正确
|
||
- 测试 API 是否可访问
|
||
|
||
4. **清除缓存**
|
||
```bash
|
||
# 强制刷新
|
||
Ctrl + Shift + R
|
||
```
|
||
|
||
---
|
||
|
||
## 性能问题
|
||
|
||
### 响应延迟高
|
||
|
||
**症状**：从发送消息到收到回复时间过长。
|
||
|
||
**排查步骤**：
|
||
|
||
1. **定位延迟环节**
|
||
- ASR 处理时间
|
||
- LLM 推理时间
|
||
- TTS 合成时间
|
||
|
||
2. **查看性能指标**
|
||
- 检查 `metrics.ttfb` 事件
|
||
- 分析各环节耗时
|
||
|
||
3. **优化配置**
|
||
- 使用更快的模型
|
||
- 减少 max_tokens
|
||
- 启用流式输出
|
||
|
||
4. **检查网络**
|
||
- 测试到各 API 的延迟
|
||
- 考虑使用更近的服务区域
|
||
|
||
---
|
||
|
||
## 日志查看
|
||
|
||
### 服务端日志
|
||
|
||
```bash
|
||
# Docker 容器日志
|
||
docker logs -f ai-assistant-engine
|
||
|
||
# 查看最近 100 行
|
||
docker logs --tail 100 ai-assistant-engine
|
||
```
|
||
|
||
### 客户端日志
|
||
|
||
在浏览器开发者工具中：
|
||
|
||
1. **Console** - 查看 JavaScript 错误和日志
|
||
2. **Network** - 查看网络请求和响应
|
||
3. **WebSocket** - 查看 WS 消息（在 Network 标签页）
|
||
|
||
### 启用详细日志
|
||
|
||
设置环境变量启用调试日志：
|
||
|
||
```bash
|
||
# Engine 服务
|
||
LOG_LEVEL=debug
|
||
|
||
# API 服务
|
||
DEBUG=true
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
如果以上方法无法解决问题：
|
||
|
||
1. 收集相关日志和错误信息
|
||
2. 描述复现步骤
|
||
3. 提交 Issue 或联系技术支持
|