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
113
docs/content/assistants/configuration.md
Normal file
113
docs/content/assistants/configuration.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# 配置选项
|
||||
|
||||
助手配置界面包含多个标签页，每个标签页负责不同方面的配置。
|
||||
|
||||
## 全局设置
|
||||
|
||||
全局设置定义助手的核心对话能力。
|
||||
|
||||
| 配置项 | 说明 | 建议值 |
|
||||
|-------|------|--------|
|
||||
| 助手名称 | 用于标识和管理 | 简洁明确 |
|
||||
| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](prompts.md) |
|
||||
| 开场白 | 对话开始时的问候语 | 简短友好 |
|
||||
| 温度参数 | 控制回复随机性 | 0.7（通用）/ 0.3（严谨） |
|
||||
| 上下文长度 | 保留的历史消息数 | 10-20 |
|
||||
|
||||
### 高级选项
|
||||
|
||||
- **首轮模式** - 设置首次对话的触发方式
|
||||
- **打断检测** - 用户打断时的处理策略
|
||||
- **超时设置** - 无响应时的处理
|
||||
|
||||
## 语音配置
|
||||
|
||||
配置语音识别和语音合成参数。
|
||||
|
||||
### TTS 语音合成
|
||||
|
||||
| 配置 | 说明 |
|
||||
|------|------|
|
||||
| TTS 引擎 | 选择语音合成服务（阿里/火山/Minimax） |
|
||||
| 音色 | 选择语音风格和性别 |
|
||||
| 语速 | 语音播放速度（0.5-2.0） |
|
||||
| 音量 | 语音输出音量（0-100） |
|
||||
| 音调 | 语音音调高低（0.5-2.0） |
|
||||
|
||||
### ASR 语音识别
|
||||
|
||||
| 配置 | 说明 |
|
||||
|------|------|
|
||||
| ASR 引擎 | 选择语音识别服务 |
|
||||
| 语言 | 识别语言（中文/英文/多语言） |
|
||||
| 热词 | 提高特定词汇识别准确率 |
|
||||
|
||||
## 工具绑定
|
||||
|
||||
配置助手可调用的外部工具。
|
||||
|
||||
### 可用工具类型
|
||||
|
||||
| 工具 | 说明 |
|
||||
|------|------|
|
||||
| 搜索工具 | 网络搜索获取信息 |
|
||||
| 天气查询 | 查询天气预报 |
|
||||
| 计算器 | 数学计算 |
|
||||
| 知识库检索 | RAG 知识检索 |
|
||||
| 自定义工具 | HTTP 回调外部 API |
|
||||
|
||||
### 配置步骤
|
||||
|
||||
1. 在工具列表中勾选需要的工具
|
||||
2. 配置工具参数（如有）
|
||||
3. 测试工具调用是否正常
|
||||
|
||||
## 知识关联
|
||||
|
||||
关联 RAG 知识库，让助手能够回答专业领域问题。
|
||||
|
||||
### 配置参数
|
||||
|
||||
| 参数 | 说明 | 建议值 |
|
||||
|------|------|--------|
|
||||
| 知识库 | 选择要关联的知识库 | - |
|
||||
| 相似度阈值 | 低于此分数不返回 | 0.7 |
|
||||
| 返回数量 | 单次检索返回条数 | 3 |
|
||||
| 检索策略 | 混合/向量/关键词 | 混合 |
|
||||
|
||||
### 多知识库
|
||||
|
||||
支持关联多个知识库，系统会自动合并检索结果。
|
||||
|
||||
## 外部链接
|
||||
|
||||
配置第三方服务集成和 Webhook 回调。
|
||||
|
||||
### Webhook 配置
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 回调 URL | 接收事件的 HTTP 端点 |
|
||||
| 事件类型 | 订阅的事件（对话开始/结束/工具调用等） |
|
||||
| 认证方式 | API Key / Bearer Token / 无 |
|
||||
|
||||
### 支持的事件
|
||||
|
||||
- `conversation.started` - 对话开始
|
||||
- `conversation.ended` - 对话结束
|
||||
- `tool.called` - 工具被调用
|
||||
- `human.transfer` - 转人工
|
||||
|
||||
## 配置导入导出
|
||||
|
||||
### 导出配置
|
||||
|
||||
1. 在助手详情页点击 **更多**
|
||||
2. 选择 **导出配置**
|
||||
3. 下载 JSON 格式的配置文件
|
||||
|
||||
### 导入配置
|
||||
|
||||
1. 点击 **新建助手**
|
||||
2. 选择 **从配置导入**
|
||||
3. 上传配置文件
|
||||
57
docs/content/assistants/index.md
Normal file
57
docs/content/assistants/index.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# 助手管理
|
||||
|
||||
助手是 AI Video Assistant 的核心模块，用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
|
||||
|
||||
## 概述
|
||||
|
||||
|
||||
|
||||
## 助手能力
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| **智能对话** | 基于 LLM 的自然语言理解和生成 |
|
||||
| **语音交互** | 支持语音识别和语音合成 |
|
||||
| **知识检索** | 关联知识库回答专业问题 |
|
||||
| **工具调用** | 调用外部 API 执行操作 |
|
||||
| **工作流** | 支持复杂的多轮对话流程 |
|
||||
|
||||
## 创建助手
|
||||
|
||||
### 步骤
|
||||
|
||||
1. 进入 **助手管理** 页面
|
||||
2. 点击 **新建助手** 按钮
|
||||
3. 填写基本信息
|
||||
4. 配置各项参数
|
||||
5. 保存并发布
|
||||
|
||||
### 基本信息
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|-------|------|
|
||||
| 助手名称 | 唯一标识，用于区分不同助手 |
|
||||
| 提示词 | 定义助手的角色和行为 |
|
||||
| 温度参数 | 控制回复的随机性（0-1） |
|
||||
|
||||
## 调试助手
|
||||
|
||||
在助手详情页可进行实时调试：
|
||||
|
||||
- **文本对话测试** - 快速验证回复质量
|
||||
- **语音输入测试** - 测试 ASR 识别效果
|
||||
- **工具调用验证** - 确认工具正常执行
|
||||
|
||||
## 发布助手
|
||||
|
||||
配置完成后：
|
||||
|
||||
1. 点击 **保存** - 保存当前配置
|
||||
2. 点击 **发布** - 发布到生产环境
|
||||
3. 获取 API 调用地址 - 用于集成
|
||||
|
||||
## 下一步
|
||||
|
||||
- [配置选项](configuration.md) - 详细的配置标签页说明
|
||||
- [提示词指南](prompts.md) - 如何编写高质量的系统提示词
|
||||
- [测试调试](testing.md) - 助手测试与问题排查
|
||||
184
docs/content/assistants/prompts.md
Normal file
184
docs/content/assistants/prompts.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 提示词指南
|
||||
|
||||
系统提示词（System Prompt）是定义助手行为的核心配置。本指南介绍如何编写高质量的提示词。
|
||||
|
||||
## 提示词结构
|
||||
|
||||
一个完整的系统提示词通常包含以下部分：
|
||||
|
||||
```
|
||||
[角色定义]
|
||||
[任务描述]
|
||||
[行为约束]
|
||||
[输出格式]
|
||||
[示例（可选）]
|
||||
```
|
||||
|
||||
## 编写原则
|
||||
|
||||
### 1. 明确角色
|
||||
|
||||
告诉助手它是谁：
|
||||
|
||||
```
|
||||
你是一个专业的技术支持工程师，专门负责解答产品使用问题。
|
||||
```
|
||||
|
||||
### 2. 定义任务
|
||||
|
||||
明确助手需要完成什么：
|
||||
|
||||
```
|
||||
你的主要任务是：
|
||||
1. 解答用户关于产品功能的问题
|
||||
2. 提供使用指导和最佳实践
|
||||
3. 帮助用户排查常见故障
|
||||
```
|
||||
|
||||
### 3. 设置约束
|
||||
|
||||
限制不希望出现的行为：
|
||||
|
||||
```
|
||||
请注意：
|
||||
- 不要讨论与产品无关的话题
|
||||
- 不要编造不存在的功能
|
||||
- 如果不确定答案，请建议用户联系人工客服
|
||||
```
|
||||
|
||||
### 4. 指定风格
|
||||
|
||||
定义回复的语气和风格：
|
||||
|
||||
```
|
||||
回复风格要求：
|
||||
- 使用友好、专业的语气
|
||||
- 回答简洁明了，避免冗长
|
||||
- 适当使用列表和步骤说明
|
||||
```
|
||||
|
||||
## 提示词模板
|
||||
|
||||
### 客服助手
|
||||
|
||||
```
|
||||
你是 [公司名称] 的智能客服助手。
|
||||
|
||||
## 你的职责
|
||||
- 解答用户关于产品和服务的问题
|
||||
- 处理常见的投诉和建议
|
||||
- 引导用户完成操作流程
|
||||
|
||||
## 回复要求
|
||||
- 保持友好和耐心
|
||||
- 回答简洁，一般不超过 3 句话
|
||||
- 如果问题复杂，建议转接人工客服
|
||||
|
||||
## 禁止行为
|
||||
- 不要讨论竞争对手
|
||||
- 不要承诺无法兑现的事项
|
||||
- 不要透露内部信息
|
||||
```
|
||||
|
||||
### 技术支持
|
||||
|
||||
```
|
||||
你是一个技术支持工程师，专门帮助用户解决技术问题。
|
||||
|
||||
## 工作流程
|
||||
1. 首先了解用户遇到的具体问题
|
||||
2. 询问必要的环境信息（系统版本、错误信息等）
|
||||
3. 提供分步骤的解决方案
|
||||
4. 确认问题是否解决
|
||||
|
||||
## 回复格式
|
||||
- 使用编号列表说明操作步骤
|
||||
- 提供代码示例时使用代码块
|
||||
- 复杂问题可以分多次回复
|
||||
```
|
||||
|
||||
### 销售顾问
|
||||
|
||||
```
|
||||
你是一个产品销售顾问，帮助用户了解产品并做出购买决策。
|
||||
|
||||
## 沟通策略
|
||||
- 先了解用户需求，再推荐合适的产品
|
||||
- 突出产品优势，但不贬低竞品
|
||||
- 提供真实的价格和优惠信息
|
||||
|
||||
## 目标
|
||||
- 帮助用户找到最适合的方案
|
||||
- 解答购买相关的疑问
|
||||
- 促进成交但不过度推销
|
||||
```
|
||||
|
||||
## 动态变量
|
||||
|
||||
提示词支持动态变量，使用 `{{变量名}}` 语法：
|
||||
|
||||
```
|
||||
你好 {{customer_name}}，欢迎来到 {{company_name}}。
|
||||
你当前的会员等级是 {{membership_tier}}。
|
||||
```
|
||||
|
||||
在 `session.start` 时通过 `dynamicVariables` 传入：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "session.start",
|
||||
"metadata": {
|
||||
"dynamicVariables": {
|
||||
"customer_name": "张三",
|
||||
"company_name": "AI 公司",
|
||||
"membership_tier": "黄金会员"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 回复太长
|
||||
|
||||
在提示词中明确限制：
|
||||
|
||||
```
|
||||
回复长度要求：
|
||||
- 一般问题：1-2 句话
|
||||
- 复杂问题：不超过 5 句话
|
||||
- 避免重复和冗余内容
|
||||
```
|
||||
|
||||
### 答非所问
|
||||
|
||||
增加任务边界说明：
|
||||
|
||||
```
|
||||
重要提示：
|
||||
- 只回答与 [产品/服务] 相关的问题
|
||||
- 对于无关问题，礼貌地拒绝并引导回正题
|
||||
```
|
||||
|
||||
### 编造信息
|
||||
|
||||
强调诚实原则：
|
||||
|
||||
```
|
||||
信息准确性要求：
|
||||
- 只提供你确定的信息
|
||||
- 不确定时说"我不太确定，建议您..."
|
||||
- 绝对不要编造数据或功能
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **迭代优化** - 根据实际对话效果持续调整
|
||||
2. **测试覆盖** - 用各种场景测试提示词效果
|
||||
3. **版本管理** - 保存历史版本，便于回退
|
||||
4. **定期复盘** - 分析对话记录，发现改进点
|
||||
|
||||
## 下一步
|
||||
|
||||
- [测试调试](testing.md) - 验证提示词效果
|
||||
- [知识库配置](../customization/knowledge-base.md) - 补充专业知识
|
||||
162
docs/content/assistants/testing.md
Normal file
162
docs/content/assistants/testing.md
Normal file
@@ -0,0 +1,162 @@
|
||||
# 测试调试
|
||||
|
||||
本指南介绍如何测试和调试 AI 助手，确保其行为符合预期。
|
||||
|
||||
## 测试面板
|
||||
|
||||
在助手详情页，点击 **测试** 按钮打开测试面板。
|
||||
|
||||
### 功能介绍
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| 文本对话 | 直接输入文字进行测试 |
|
||||
| 语音测试 | 使用麦克风进行语音对话 |
|
||||
| 查看日志 | 实时查看系统日志 |
|
||||
| 事件追踪 | 查看 WebSocket 事件流 |
|
||||
|
||||
## 测试用例设计
|
||||
|
||||
### 基础功能测试
|
||||
|
||||
| 测试项 | 输入 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| 问候响应 | "你好" | 友好的问候回复 |
|
||||
| 功能介绍 | "你能做什么？" | 准确描述能力范围 |
|
||||
| 开场白 | 连接后自动 | 播放配置的开场白 |
|
||||
|
||||
### 业务场景测试
|
||||
|
||||
根据助手定位设计测试用例：
|
||||
|
||||
```
|
||||
场景：产品咨询助手
|
||||
|
||||
测试用例 1：常见问题
|
||||
- 输入："产品有哪些功能？"
|
||||
- 预期：准确列出主要功能
|
||||
|
||||
测试用例 2：价格询问
|
||||
- 输入："多少钱？"
|
||||
- 预期：提供价格信息或引导方式
|
||||
|
||||
测试用例 3：超出范围
|
||||
- 输入："帮我写一首诗"
|
||||
- 预期：礼貌拒绝并引导回业务话题
|
||||
```
|
||||
|
||||
### 边界测试
|
||||
|
||||
| 测试项 | 输入 | 预期结果 |
|
||||
|--------|------|---------|
|
||||
| 空输入 | "" | 提示用户输入内容 |
|
||||
| 超长输入 | 1000+ 字符 | 正常处理或提示过长 |
|
||||
| 特殊字符 | "<script>alert(1)</script>" | 安全处理，不执行 |
|
||||
| 敏感内容 | 不当言论 | 拒绝回复并提示 |
|
||||
|
||||
## 日志分析
|
||||
|
||||
### 查看日志
|
||||
|
||||
在测试面板的 **日志** 标签页，可以看到：
|
||||
|
||||
- ASR 识别结果
|
||||
- LLM 推理过程
|
||||
- TTS 合成状态
|
||||
- 工具调用记录
|
||||
|
||||
### 常见日志
|
||||
|
||||
```
|
||||
[ASR] transcript.final: "你好，请问有什么可以帮你"
|
||||
[LLM] request: messages=[...]
|
||||
[LLM] response: "您好！我是..."
|
||||
[TTS] synthesizing: "您好！我是..."
|
||||
[TTS] audio.start
|
||||
[TTS] audio.end
|
||||
```
|
||||
|
||||
## 事件追踪
|
||||
|
||||
在 **事件** 标签页查看完整的 WebSocket 事件流：
|
||||
|
||||
```json
|
||||
{"type": "session.started", "timestamp": 1704067200000}
|
||||
{"type": "input.speech_started", "timestamp": 1704067201000}
|
||||
{"type": "transcript.delta", "data": {"text": "你"}}
|
||||
{"type": "transcript.delta", "data": {"text": "好"}}
|
||||
{"type": "transcript.final", "data": {"text": "你好"}}
|
||||
{"type": "assistant.response.delta", "data": {"text": "您"}}
|
||||
{"type": "assistant.response.final", "data": {"text": "您好！..."}}
|
||||
{"type": "output.audio.start"}
|
||||
{"type": "output.audio.end"}
|
||||
```
|
||||
|
||||
## 性能指标
|
||||
|
||||
关注以下性能指标：
|
||||
|
||||
| 指标 | 说明 | 建议值 |
|
||||
|------|------|--------|
|
||||
| TTFB | 首字节时间 | < 500ms |
|
||||
| 识别延迟 | ASR 处理时间 | < 1s |
|
||||
| 回复延迟 | LLM 推理时间 | < 2s |
|
||||
| 合成延迟 | TTS 处理时间 | < 500ms |
|
||||
|
||||
## 常见问题排查
|
||||
|
||||
### 助手不响应
|
||||
|
||||
1. **检查连接状态**
|
||||
- 确认 WebSocket 连接成功
|
||||
- 查看是否收到 `session.started` 事件
|
||||
|
||||
2. **检查模型配置**
|
||||
- 确认 LLM 模型 API Key 有效
|
||||
- 测试模型连接是否正常
|
||||
|
||||
3. **查看错误日志**
|
||||
- 打开浏览器开发者工具
|
||||
- 检查 Console 和 Network 标签
|
||||
|
||||
### 回复质量差
|
||||
|
||||
1. **优化提示词**
|
||||
- 增加更明确的指令
|
||||
- 添加示例和约束
|
||||
|
||||
2. **调整温度参数**
|
||||
- 降低 temperature 提高一致性
|
||||
- 适当值通常在 0.3-0.7
|
||||
|
||||
3. **补充知识库**
|
||||
- 上传相关文档
|
||||
- 提高检索相关性
|
||||
|
||||
### 语音问题
|
||||
|
||||
1. **ASR 识别不准**
|
||||
- 检查麦克风权限
|
||||
- 尝试更换 ASR 引擎
|
||||
- 添加热词提高识别率
|
||||
|
||||
2. **TTS 不播放**
|
||||
- 检查浏览器自动播放限制
|
||||
- 确认 TTS 配置正确
|
||||
|
||||
## 自动化测试
|
||||
|
||||
使用自动化测试功能进行批量测试：
|
||||
|
||||
1. 进入 **自动化测试** 页面
|
||||
2. 创建测试任务
|
||||
3. 配置测试用例
|
||||
4. 运行测试并查看报告
|
||||
|
||||
详见 [自动化测试](../analysis/autotest.md)。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [自动化测试](../analysis/autotest.md) - 批量测试
|
||||
- [历史记录](../analysis/history.md) - 查看对话记录
|
||||
- [效果评估](../analysis/evaluation.md) - 评估对话质量
|
||||
Reference in New Issue
Block a user