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. 上传配置文件
|
||||
Reference in New Issue
Block a user