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.
This commit is contained in:
Xin Wang
110
docs/content/resources/faq.md
Normal file
110
docs/content/resources/faq.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# 常见问题
|
||||
|
||||
## API Key 配置
|
||||
|
||||
### Q: 如何配置 API Key？
|
||||
|
||||
进入 **LLM 库** 或 **语音库** 页面，点击对应模型的配置按钮填写 API Key。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. 在左侧导航栏选择 **模型配置**
|
||||
2. 选择 **LLM 库** 或 **语音库**
|
||||
3. 点击已添加模型的 **编辑** 按钮
|
||||
4. 在 API Key 字段填写你的密钥
|
||||
5. 点击 **保存**
|
||||
|
||||
## 助手问题
|
||||
|
||||
### Q: 助手无法回复？
|
||||
|
||||
可能的原因和解决方案：
|
||||
|
||||
1. **检查模型配置是否正确**
|
||||
- 确认 API Key 已正确填写
|
||||
- 测试模型连接是否正常
|
||||
|
||||
2. **确认知识库已正确关联**
|
||||
- 进入助手配置的 **知识** 标签页
|
||||
- 检查是否已选择知识库
|
||||
|
||||
3. **查看系统日志排查错误**
|
||||
- 打开浏览器开发者工具（F12）
|
||||
- 检查 Console 和 Network 标签页
|
||||
|
||||
### Q: 助手回复内容不相关？
|
||||
|
||||
- 检查系统提示词是否清晰明确
|
||||
- 调整 Temperature 参数（降低可提高准确性）
|
||||
- 确认知识库内容与问题相关
|
||||
- 增加知识库相似度阈值
|
||||
|
||||
## 语音识别
|
||||
|
||||
### Q: 语音识别不准确？
|
||||
|
||||
1. **确认 ASR 模型选择正确**
|
||||
- 中文场景推荐使用 SenseVoice
|
||||
- 英文场景推荐使用 Whisper
|
||||
|
||||
2. **检查音频采样率**
|
||||
- 推荐采样率：16kHz
|
||||
- 推荐格式：PCM 16-bit
|
||||
|
||||
3. **确认语言设置匹配**
|
||||
- 在 ASR 配置中选择正确的语言
|
||||
|
||||
### Q: 语音延迟较高？
|
||||
|
||||
- 检查网络连接稳定性
|
||||
- 尝试切换 ASR 服务提供商
|
||||
- 降低音频质量以减少传输数据量
|
||||
|
||||
## 语音合成
|
||||
|
||||
### Q: TTS 声音不自然？
|
||||
|
||||
- 尝试不同的音色选项
|
||||
- 调整语速参数（推荐 0.8-1.2）
|
||||
- 选择与内容风格匹配的声音
|
||||
|
||||
### Q: TTS 无法播放？
|
||||
|
||||
1. 检查浏览器是否允许自动播放音频
|
||||
2. 确认 TTS API Key 配置正确
|
||||
3. 检查网络连接
|
||||
|
||||
## 知识库
|
||||
|
||||
### Q: 知识库检索无结果？
|
||||
|
||||
- 确认文档已成功上传
|
||||
- 降低相似度阈值（默认 0.7）
|
||||
- 增加返回结果数量
|
||||
- 检查文档内容是否与查询相关
|
||||
|
||||
### Q: 文档上传失败？
|
||||
|
||||
- 检查文件大小是否超过 10MB
|
||||
- 确认文件格式支持（MD/PDF/TXT）
|
||||
- 尝试减小文档内容
|
||||
|
||||
## 部署问题
|
||||
|
||||
### Q: 页面空白或加载失败？
|
||||
|
||||
1. 检查浏览器控制台错误信息
|
||||
2. 确认后端服务已启动
|
||||
3. 检查 VITE_API_URL 环境变量配置
|
||||
|
||||
### Q: API 请求失败？
|
||||
|
||||
- 确认 VITE_API_URL 配置正确
|
||||
- 检查后端服务是否运行
|
||||
- 查看网络请求响应状态码
|
||||
|
||||
### Q: 静态资源 404？
|
||||
|
||||
- 检查 Nginx `try_files` 配置
|
||||
- 确认构建产物路径正确
|
||||
- 检查文件权限设置
|
||||
292
docs/content/resources/troubleshooting.md
Normal file
292
docs/content/resources/troubleshooting.md
Normal file
@@ -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 或联系技术支持
|
||||
Reference in New Issue
Block a user