Update documentation for Realtime Agent Studio with enhanced content and structure
- Revised site name and description for clarity and detail. - Updated navigation structure to better reflect the organization of content. - Improved changelog entries for better readability and consistency. - Migrated assistant configuration and prompt guidelines to new documentation paths. - Enhanced core concepts section to clarify the roles and capabilities of assistants and engines. - Streamlined workflow documentation to provide clearer guidance on configuration and usage.
This commit is contained in:
Xin Wang
218
docs/content/concepts/assistants/configuration.md
Normal file
218
docs/content/concepts/assistants/configuration.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 配置选项
|
||||
|
||||
助手配置界面包含多个标签页，每个标签页负责不同方面的配置。
|
||||
|
||||
## 全局设置
|
||||
|
||||
全局设置定义助手的核心对话能力。
|
||||
|
||||
| 配置项 | 说明 | 建议值 |
|
||||
|-------|------|--------|
|
||||
| 助手名称 | 用于标识和管理 | 简洁明确 |
|
||||
| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](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. **数据库持久化配置（基线配置）**：通过助手管理 API 保存，后续会话默认读取这一层。
|
||||
2. **会话级覆盖配置（runtime overrides）**：仅对当前 WebSocket 会话生效，不会写回数据库。
|
||||
|
||||
### 哪些配置会存到数据库
|
||||
|
||||
以下字段会持久化在 `assistants` / `assistant_opener_audio` 等表中（通过创建/更新助手写入）：
|
||||
|
||||
| 类别 | 典型字段 |
|
||||
|------|---------|
|
||||
| 对话行为 | `name`、`prompt`、`opener`、`firstTurnMode`、`generatedOpenerEnabled` |
|
||||
| 输出与打断 | `voiceOutputEnabled`、`voice`、`speed`、`botCannotBeInterrupted`、`interruptionSensitivity` |
|
||||
| 工具与知识库 | `tools`、`knowledgeBaseId` |
|
||||
| 模型与外部模式 | `configMode`、`apiUrl`、`apiKey`、`llmModelId`、`asrModelId`、`embeddingModelId`、`rerankModelId` |
|
||||
| 开场音频 | `openerAudioEnabled` 及音频文件状态（`ready`、`durationMs` 等） |
|
||||
|
||||
> 引擎在连接时通过 `assistant_id` 从后端读取该助手的 `sessionStartMetadata` 作为默认运行配置。
|
||||
|
||||
### 哪些配置可以在会话中覆盖
|
||||
|
||||
客户端可在 `session.start.metadata.overrides` 中覆盖以下白名单字段（仅当前会话有效）：
|
||||
|
||||
- `systemPrompt`
|
||||
- `greeting`
|
||||
- `firstTurnMode`
|
||||
- `generatedOpenerEnabled`
|
||||
- `output`
|
||||
- `bargeIn`
|
||||
- `knowledgeBaseId`
|
||||
- `knowledge`
|
||||
- `tools`
|
||||
- `openerAudio`
|
||||
|
||||
以下字段不能由客户端覆盖：
|
||||
|
||||
- `services`（模型 provider / apiKey / baseUrl 等）
|
||||
- `assistantId` / `appId` / `configVersionId`（及下划线变体）
|
||||
- 包含密钥语义的字段（如 `apiKey`、`token`、`secret`、`password`、`authorization`）
|
||||
|
||||
### 覆盖示例（代码）
|
||||
|
||||
下面示例展示「数据库基线配置 + 会话 overrides」的最终效果。
|
||||
|
||||
```json
|
||||
// 1) 数据库存储的基线配置（示意）
|
||||
// GET /api/v1/assistants/asst_demo/config -> sessionStartMetadata
|
||||
{
|
||||
"systemPrompt": "你是电商客服助手，回答要简洁。",
|
||||
"greeting": "你好，我是你的客服助手。",
|
||||
"firstTurnMode": "bot_first",
|
||||
"output": { "mode": "audio" },
|
||||
"knowledgeBaseId": "kb_orders",
|
||||
"tools": [
|
||||
{ "type": "function", "function": { "name": "query_order" } }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// 2) 客户端发起会话时的覆盖
|
||||
{
|
||||
"type": "session.start",
|
||||
"metadata": {
|
||||
"channel": "web",
|
||||
"history": { "userId": 1001 },
|
||||
"overrides": {
|
||||
"greeting": "你好，我来帮你查订单进度。",
|
||||
"output": { "mode": "text" },
|
||||
"knowledgeBaseId": "kb_vip_orders",
|
||||
"tools": [
|
||||
{ "type": "function", "function": { "name": "query_vip_order" } }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// 3) 引擎合并后的有效配置（示意）
|
||||
{
|
||||
"assistantId": "asst_demo",
|
||||
"systemPrompt": "你是电商客服助手，回答要简洁。",
|
||||
"greeting": "你好，我来帮你查订单进度。",
|
||||
"firstTurnMode": "bot_first",
|
||||
"output": { "mode": "text" },
|
||||
"knowledgeBaseId": "kb_vip_orders",
|
||||
"tools": [
|
||||
{ "type": "function", "function": { "name": "query_vip_order" } }
|
||||
],
|
||||
"channel": "web",
|
||||
"history": { "userId": 1001 }
|
||||
}
|
||||
```
|
||||
|
||||
合并规则可简化为：
|
||||
|
||||
```python
|
||||
effective = {**db_session_start_metadata, **metadata.overrides}
|
||||
```
|
||||
|
||||
当 `WS_EMIT_CONFIG_RESOLVED=true` 时，服务端会返回 `config.resolved`（公开、安全裁剪后的快照）用于前端调试当前生效配置。
|
||||
|
||||
## 配置导入导出
|
||||
|
||||
### 导出配置
|
||||
|
||||
1. 在助手详情页点击 **更多**
|
||||
2. 选择 **导出配置**
|
||||
3. 下载 JSON 格式的配置文件
|
||||
|
||||
### 导入配置
|
||||
|
||||
1. 点击 **新建助手**
|
||||
2. 选择 **从配置导入**
|
||||
3. 上传配置文件
|
||||
184
docs/content/concepts/assistants/prompts.md
Normal file
184
docs/content/concepts/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/concepts/assistants/testing.md
Normal file
162
docs/content/concepts/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