wx44wx/AI-VideoAssistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for Realtime Agent Studio with enhanced content and structure

Browse Source 
- 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
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
docs/content/assistants/configuration.md
View File

@@ -1,218 +1,8 @@
# 配置选项
# 配置选项（旧入口）
助手配置界面包含多个标签页，每个标签页负责不同方面的配置。
本页保留旧链接，用于承接历史导航或外部引用。助手配置的正式文档已经迁移到：
## 全局设置
- [配置选项](../concepts/assistants/configuration.md) - 助手配置界面与运行时配置层说明
- [助手概念](../concepts/assistants.md) - 先理解助手对象、会话与动态变量
全局设置定义助手的核心对话能力。
| 配置项 | 说明 | 建议值 |
|-------|------|--------|
| 助手名称 | 用于标识和管理 | 简洁明确 |
| 系统提示词 | 定义角色、任务和约束 | 详见[提示词指南](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. 上传配置文件
如果你是从创建路径进入，也可以直接回到 [快速开始](../quickstart/index.md)。

61
docs/content/assistants/index.md
View File

@@ -1,57 +1,10 @@
# 助手管理
# 助手管理（旧入口）
助手是 Realtime Agent Studio (RAS) 的核心模块，用于创建和配置智能对话机器人。每个助手都可以独立配置提示词、语音、知识库和工具。
本页保留旧链接，用于承接历史导航或外部引用。助手相关内容已经拆分到更明确的文档中：
## 概述
- [助手概念](../concepts/assistants.md) - 了解助手是什么、由哪些部分组成，以及会话如何运行
- [配置选项](../concepts/assistants/configuration.md) - 查看控制台和运行时配置项的分工
- [提示词指南](../concepts/assistants/prompts.md) - 编写高质量系统提示词
- [测试调试](../concepts/assistants/testing.md) - 验证助手行为并排查问题
![助手管理](../images/assistants.png)
## 助手能力
| 能力 | 说明 |
|------|------|
| **智能对话** | 基于 LLM 的自然语言理解和生成 |
| **语音交互** | 支持语音识别和语音合成 |
| **知识检索** | 关联知识库回答专业问题 |
| **工具调用** | 调用外部 API 执行操作 |
| **工作流** | 支持复杂的多轮对话流程 |
## 创建助手
### 步骤
1. 进入 **助手管理** 页面
2. 点击 **新建助手** 按钮
3. 填写基本信息
4. 配置各项参数
5. 保存并发布
### 基本信息
| 配置项 | 说明 |
|-------|------|
| 助手名称 | 唯一标识，用于区分不同助手 |
| 提示词 | 定义助手的角色和行为 |
| 温度参数 | 控制回复的随机性（0-1） |
## 调试助手
在助手详情页可进行实时调试：
- **文本对话测试** - 快速验证回复质量
- **语音输入测试** - 测试 ASR 识别效果
- **工具调用验证** - 确认工具正常执行
## 发布助手
配置完成后：
1. 点击 **保存** - 保存当前配置
2. 点击 **发布** - 发布到生产环境
3. 获取 API 调用地址 - 用于集成
## 下一步
- [配置选项](configuration.md) - 详细的配置标签页说明
- [提示词指南](prompts.md) - 如何编写高质量的系统提示词
- [测试调试](testing.md) - 助手测试与问题排查
如果你是第一次上手，建议直接从 [快速开始](../quickstart/index.md) 进入。

186
docs/content/assistants/prompts.md
View File

@@ -1,184 +1,8 @@
# 提示词指南
# 提示词指南（旧入口）
系统提示词（System Prompt）是定义助手行为的核心配置。本指南介绍如何编写高质量的提示词。
本页保留旧链接，用于承接历史导航或外部引用。提示词的正式文档已经迁移到：
## 提示词结构
- [提示词指南](../concepts/assistants/prompts.md) - 设计角色、任务、限制与风格
- [助手概念](../concepts/assistants.md) - 理解提示词在助手体系中的位置
一个完整的系统提示词通常包含以下部分：
```
[角色定义]
[任务描述]
[行为约束]
[输出格式]
[示例（可选）]
```
## 编写原则
### 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) - 补充专业知识
如果你想先完成最小可用配置，请从 [快速开始](../quickstart/index.md) 继续。

164
docs/content/assistants/testing.md
View File

@@ -1,162 +1,8 @@
# 测试调试
# 测试调试（旧入口）
本指南介绍如何测试和调试 AI 助手，确保其行为符合预期。
本页保留旧链接，用于承接历史导航或外部引用。测试与调试的正式文档已经迁移到：
## 测试面板
- [测试调试](../concepts/assistants/testing.md) - 验证助手行为、事件流和常见问题定位
- [故障排查](../resources/troubleshooting.md) - 进入更细的链路排查步骤
在助手详情页，点击 **测试** 按钮打开测试面板。
### 功能介绍
| 功能 | 说明 |
|------|------|
| 文本对话 | 直接输入文字进行测试 |
| 语音测试 | 使用麦克风进行语音对话 |
| 查看日志 | 实时查看系统日志 |
| 事件追踪 | 查看 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) - 评估对话质量
如果你还没创建助手，请先完成 [快速开始](../quickstart/index.md)。

69
docs/content/assistants/workflow-configuration.md
View File

@@ -1,68 +1,7 @@
# 工作流配置选项（TODO 版本）
# 工作流配置（旧入口）
本文档是工作流配置页的第一版草稿，后续会根据实际能力继续细化。
本页保留旧链接，用于承接早期草稿和历史引用。工作流的正式文档已收敛到：
## 配置目标
- 将多步骤对话拆分为可编排节点
- 为不同分支定义独立提示词和工具权限
- 在会话中按条件切换节点并透传上下文
## 基础配置项（建议）
| 配置项 | 说明 | 建议值 |
|---|---|---|
| 工作流名称 | 用于区分业务流程 | 简洁、业务语义明确 |
| 入口节点 | 用户进入后的首个节点 | 固定单入口 |
| 全局提示词 | 对所有节点生效的共性约束 | 保持简短，避免与节点提示词冲突 |
| 节点提示词 | 当前节点的任务说明 | 单一职责，明确输入/输出 |
| 节点工具白名单 | 当前节点可调用工具集合 | 最小权限原则 |
| 节点超时 | 节点等待超时处理 | 3-10 秒 |
| 失败回退节点 | 异常时兜底节点 | 建议统一到人工或澄清节点 |
## 节点建议类型
- 意图识别节点：判断用户诉求并路由
- 信息收集节点：收集订单号、手机号等关键信息
- 处理节点：执行查询、计算、调用工具
- 回复节点：组织最终答复
- 结束节点：输出结束语并关闭会话
## 配置示例
```yaml
workflow:
name: "订单咨询流程"
entry: "intent_router"
global_prompt: "优先给出可执行步骤，必要时先澄清信息。"
nodes:
- id: "intent_router"
type: "router"
prompt: "识别用户意图：查订单、退款、投诉"
next:
- when: "intent == query_order"
to: "collect_order_id"
- when: "intent == refund"
to: "refund_policy"
- id: "collect_order_id"
type: "collect"
prompt: "请用户提供订单号"
tools: ["query_order"]
fallback: "human_handoff"
- id: "human_handoff"
type: "end"
prompt: "转人工处理"
```
## 已知限制（当前）
- 不支持在文档中完整定义所有表达式语法
- 不同执行引擎的节点字段可能存在差异
- 可视化编排与 YAML 字段暂未完全一一对应
## 后续计划
- 补充节点字段的完整 Schema
- 补充路由条件表达式规范
- 增加“调试与回放”章节
- [工作流](../customization/workflows.md) - 了解工作流的定位、节点结构、设计建议和当前边界
如果你正在配置助手中的流程能力，请优先阅读上述页面，再结合 [工具](../customization/tools.md) 与 [助手概念](../concepts/assistants.md) 一起使用。