# 故障排查

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

## 连接问题

### 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 或联系技术支持