Revamp documentation structure in mkdocs.yml by reorganizing navigation for improved accessibility. Remove outdated content from previous sections and introduce new topics including detailed guides on assistant management, configuration options, and tool integrations. Enhance API reference documentation with comprehensive error codes and WebSocket protocol details. Add new sections for automated testing, data analysis, and knowledge base management, ensuring a cohesive and user-friendly documentation experience.

2026-03-01 22:38:50 +08:00
parent 6a46ec69f4
commit 2418df80e5
33 changed files with 3664 additions and 693 deletions
--- a/docs/content/resources/troubleshooting.md
+++ b/docs/content/resources/troubleshooting.md
@@ -0,0 +1,292 @@
+# 故障排查
+
+本文档汇总常见问题的排查步骤和解决方案。
+
+## 连接问题
+
+### 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 或联系技术支持