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
@@ -1,236 +1,147 @@
|
||||
# 助手概念详解
|
||||
|
||||
深入了解助手（Assistant）的设计理念和配置细节。
|
||||
助手（Assistant）是 Realtime Agent Studio（RAS）中最核心的配置单元，也是控制台和 API 对外暴露能力的基本对象。
|
||||
|
||||
---
|
||||
|
||||
## 什么是助手？
|
||||
## 什么是助手
|
||||
|
||||
**助手**是 RAS 中的核心实体，代表一个具有特定角色、能力和行为的 AI 对话智能体。每个助手都是独立配置的，可以服务于不同的业务场景。
|
||||
一个助手代表一个可接入、可测试、可发布的实时 AI 入口。它回答三个问题：
|
||||
|
||||
### 助手的组成
|
||||
- **它是谁**：角色、语气、目标、限制、开场方式、静默时候的行动（比如静默时候的询问 Ask-on-Idle）
|
||||
- **它能做什么**：语言模型能力、语音模型能力（ASR、TTS、用户打断灵敏度（Barge-in）、语句端点设置（End-of-Utterance））、知识库、记忆、工具（Webhook、客户端工具、系统工具、MCP）、输出模式
|
||||
- **它在一次会话中如何运行**：通过 `assistant_id` 载入配置，并在运行时接收动态变量、对话时候的上下文更新
|
||||
|
||||
```mermaid
|
||||
flowchart
|
||||
subgraph Assistant["助手"]
|
||||
direction TB
|
||||
Prompts[指令配置]
|
||||
Audio[语音配置]
|
||||
Interaction[交互配置]
|
||||
tool[工具配置]
|
||||
knowledge[知识配置]
|
||||
webhooks[webhooks]
|
||||
end
|
||||
如果把引擎理解为“运行时”，那么助手就是“运行时要执行的那份定义”。
|
||||
|
||||
subgraph Prompts
|
||||
Name[名称]
|
||||
Prompt[提示词]
|
||||
Opener[开场白]
|
||||
end
|
||||
## 助手由哪些部分组成
|
||||
|
||||
subgraph Audio
|
||||
LLM[LLM 模型]
|
||||
ASR[ASR 模型]
|
||||
TTS[TTS 声音]
|
||||
end
|
||||
| 层次 | 负责什么 | 典型内容 |
|
||||
|------|----------|----------|
|
||||
| **身份层** | 定义助手角色和交互风格 | 系统提示词、限制、开场白、静默处理 |
|
||||
| **模型层** | 决定理解与生成能力 | LLM、ASR、TTS、引擎类型、用户打断、语句端点 |
|
||||
| **能力层** | 扩展知识和执行能力 | 知识库、工具、记忆 |
|
||||
| **会话层** | 决定运行时上下文如何注入 | `assistant_id`、动态变量 |
|
||||
|
||||
subgraph Interaction
|
||||
Tools[工具调用]
|
||||
KB[知识库]
|
||||
end
|
||||
## 身份层
|
||||
|
||||
subgraph tool
|
||||
Greeting[开场白]
|
||||
Interruption[打断设置]
|
||||
Output[输出模式]
|
||||
end
|
||||
|
||||
subgraph knowledge
|
||||
Greeting[开场白]
|
||||
Interruption[打断设置]
|
||||
Output[输出模式]
|
||||
end
|
||||
|
||||
subgraph webhooks
|
||||
Greeting[开场白]
|
||||
Interruption[打断设置]
|
||||
Output[输出模式]
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 身份定义
|
||||
助手首先是一个“被约束的角色”，而不是一段孤立的模型调用。
|
||||
|
||||
### 系统提示词
|
||||
|
||||
系统提示词是助手最重要的配置，它定义了：
|
||||
系统提示词定义助手的角色、任务、边界和风格，是所有能力组合的基础。
|
||||
|
||||
| 要素 | 说明 | 示例 |
|
||||
| 要素 | 作用 | 示例 |
|
||||
|------|------|------|
|
||||
| **角色** | 助手扮演什么身份 | "你是一名专业的医疗咨询顾问" |
|
||||
| **能力** | 助手能做什么 | "你可以回答健康问题，但不能开具处方" |
|
||||
| **限制** | 助手不能做什么 | "不要讨论政治话题" |
|
||||
| **风格** | 回复的语气和格式 | "保持友好专业，回答简洁" |
|
||||
| **角色** | 告诉模型“自己是谁” | 客服助手、销售顾问、培训教练 |
|
||||
| **任务** | 指定要完成的结果 | 解答咨询、收集信息、调用工具处理业务 |
|
||||
| **限制** | 明确哪些事不能做 | 不承诺超权限优惠、不输出未经验证的结论 |
|
||||
| **风格** | 约束回答节奏和措辞 | 简洁、口语化、每次 2-3 句 |
|
||||
|
||||
### 提示词模板
|
||||
### 开场白
|
||||
|
||||
```markdown
|
||||
## 角色
|
||||
你是{{company}}的智能客服助手"小智"。
|
||||
一个助手还要定义会话应该如何开始，以及用户静默时候如何处理，包括：
|
||||
|
||||
## 任务
|
||||
- 回答用户关于产品和服务的问题
|
||||
- 协助处理订单查询和售后问题
|
||||
- 收集用户反馈
|
||||
- **首轮模式**：助手先说、用户先说或者机器先说
|
||||
- **开场白**：使用固定开场白或者AI生成开场白
|
||||
|
||||
## 限制
|
||||
- 不讨论竞争对手产品
|
||||
- 不承诺超出权限的优惠
|
||||
- 遇到复杂问题引导用户联系人工客服
|
||||
### 静默处理
|
||||
|
||||
## 风格
|
||||
- 语气友好亲切
|
||||
- 回答简洁明了，每次 2-3 句话
|
||||
- 适当使用语气词使对话更自然
|
||||
```
|
||||
用户静默时候是否询问用户是否在线
|
||||
|
||||
---
|
||||
## 模型层
|
||||
|
||||
## 模型配置
|
||||
模型决定助手的基础理解、推理和表达能力，但不是助手定义的全部。
|
||||
|
||||
### LLM 模型
|
||||
- **LLM** 决定对话推理与文本生成能力
|
||||
- **ASR** 决定语音输入如何被实时转写
|
||||
- **TTS** 决定文本回复如何转成可播放语音
|
||||
- **引擎类型** 决定运行链路是分段可控还是端到端低延迟
|
||||
- **VAD** 声音活动模型，判断用户是否在说话
|
||||
- **EOU** 语句端点模型，判断用户是否完成一段语句等待回复
|
||||
- **Barge In** 由于用户声音活动或者手动请求，是否打断助手当前的回复
|
||||
|
||||
大语言模型是助手的"大脑"，负责理解用户意图和生成回复。
|
||||
## 能力层
|
||||
|
||||
| 参数 | 说明 | 建议值 |
|
||||
|------|------|--------|
|
||||
| **温度** | 回复随机性，越高越发散 | 0.7 (对话) / 0.3 (问答) |
|
||||
| **最大 Token** | 单次回复长度上限 | 256-512 |
|
||||
| **上下文长度** | 记忆的对话轮数 | 10-20 轮 |
|
||||
### 知识库
|
||||
|
||||
### ASR 模型
|
||||
|
||||
语音识别模型将用户语音转为文字。
|
||||
|
||||
| 配置 | 说明 |
|
||||
|------|------|
|
||||
| **语言** | 识别语言，如中文、英文 |
|
||||
| **热词** | 提高特定词汇识别率 |
|
||||
| **标点** | 是否自动添加标点 |
|
||||
|
||||
### TTS 声音
|
||||
|
||||
语音合成将助手回复转为语音输出。
|
||||
|
||||
| 配置 | 说明 |
|
||||
|------|------|
|
||||
| **音色** | 选择声音角色 |
|
||||
| **语速** | 说话速度，0.5-2.0 |
|
||||
| **音调** | 声音高低 |
|
||||
|
||||
---
|
||||
|
||||
## 能力扩展
|
||||
|
||||
### 工具调用
|
||||
|
||||
通过工具让助手能够执行外部操作：
|
||||
知识库用于补充私有领域知识，让助手回答超出基础模型常识之外的问题。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User[用户] -->|"查询订单"| Assistant[助手]
|
||||
Assistant -->|调用工具| API[订单 API]
|
||||
API -->|返回数据| Assistant
|
||||
Assistant -->|回复| User
|
||||
```
|
||||
|
||||
**工具定义示例：**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "get_order_status",
|
||||
"description": "查询用户订单状态",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"order_id": {
|
||||
"type": "string",
|
||||
"description": "订单编号"
|
||||
}
|
||||
},
|
||||
"required": ["order_id"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 知识库关联
|
||||
|
||||
让助手基于私有文档回答问题：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Question[用户问题] --> Search[知识检索]
|
||||
Search --> KB[(知识库)]
|
||||
KB --> Context[相关内容]
|
||||
Question[用户问题] --> Retrieval[检索]
|
||||
Retrieval --> KB[(知识库)]
|
||||
KB --> Context[相关片段]
|
||||
Context --> LLM[LLM]
|
||||
LLM --> Answer[回答]
|
||||
```
|
||||
|
||||
---
|
||||
知识库适合承载政策、产品资料、流程说明、FAQ 和内部文档，而不是把所有业务知识堆进系统提示词。
|
||||
|
||||
## 行为控制
|
||||
### 工具
|
||||
|
||||
### 开场白设置
|
||||
工具让助手从“会说”变成“能做事”。
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| **助手先说** | 连接后助手主动问候 |
|
||||
| **用户先说** | 等待用户开口 |
|
||||
| **静默** | 不自动开场 |
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User[用户] --> Assistant[助手]
|
||||
Assistant --> Tool[工具 / 外部系统]
|
||||
Tool --> Assistant
|
||||
Assistant --> User
|
||||
```
|
||||
|
||||
### 打断设置
|
||||
适合用工具处理的任务包括：订单查询、预约、外部搜索、写入业务系统、调用客户端能力等。
|
||||
|
||||
| 选项 | 说明 |
|
||||
|------|------|
|
||||
| **允许打断** | 用户可随时插话 |
|
||||
| **禁止打断** | 助手说完才能输入 |
|
||||
| **灵敏度** | 打断触发的敏感程度 |
|
||||
## 会话层
|
||||
|
||||
### 输出模式
|
||||
### `assistant_id` 的作用
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| **语音** | TTS 语音输出 |
|
||||
| **文本** | 纯文本输出 |
|
||||
| **混合** | 同时输出语音和文本 |
|
||||
在接入层面，客户端通过 `assistant_id` 指定要加载哪一个助手。引擎据此读取默认配置，并把同一份助手定义应用到当前会话。
|
||||
|
||||
---
|
||||
### 会话生命周期
|
||||
|
||||
## 最佳实践
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Connecting: WebSocket 连接
|
||||
Connecting --> Started: session.started
|
||||
Started --> Active: config.resolved / 开始对话
|
||||
Active --> Active: 多轮交互
|
||||
Active --> Stopped: session.stop 或连接关闭
|
||||
Stopped --> [*]
|
||||
```
|
||||
|
||||
### 1. 提示词工程
|
||||
一次会话通常会沉淀以下信息：
|
||||
|
||||
- **明确角色**: 清晰定义助手身份
|
||||
- **设定边界**: 明确能做什么、不能做什么
|
||||
- **控制长度**: 语音场景下回复要简短
|
||||
- 用户与助手消息时间线
|
||||
- 音频流、转写结果和模型输出
|
||||
- 工具调用记录与中间事件
|
||||
- 自定义 metadata、渠道和业务上下文
|
||||
|
||||
### 2. 模型选择
|
||||
|
||||
- **平衡成本与效果**: 不一定需要最强模型
|
||||
- **测试不同供应商**: 找到最适合场景的组合
|
||||
- **考虑延迟**: 语音交互对延迟敏感
|
||||
### 动态变量与会话级覆盖
|
||||
|
||||
### 3. 工具设计
|
||||
助手的默认配置不需要为每个用户都重新复制一份。RAS 提供两种常见的运行时注入方式：
|
||||
|
||||
- **单一职责**: 每个工具做一件事
|
||||
- **清晰描述**: 让 LLM 正确理解何时调用
|
||||
- **错误处理**: 工具失败时优雅降级
|
||||
- **动态变量**：在提示词中使用 `{{variable}}` 占位，并在会话开始时传入具体值
|
||||
- **会话级覆盖**：仅对当前会话覆盖部分运行时参数，不回写助手基线配置
|
||||
|
||||
---
|
||||
```json
|
||||
{
|
||||
"type": "session.start",
|
||||
"metadata": {
|
||||
"dynamicVariables": {
|
||||
"company_name": "ABC 公司",
|
||||
"customer_name": "张三",
|
||||
"tier": "VIP"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这种设计让你既能复用标准助手，又能在每次接入时注入渠道、用户、订单或上下文信息。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [助手配置](../assistants/configuration.md) - 配置界面详解
|
||||
- [提示词指南](../assistants/prompts.md) - 编写高质量提示词
|
||||
- [工具集成](../customization/tools.md) - 工具配置详情
|
||||
- [配置选项](assistants/configuration.md) - 查看助手在控制台和运行时有哪些配置层
|
||||
- [提示词指南](assistants/prompts.md) - 设计角色、任务、限制和语气
|
||||
- [测试调试](assistants/testing.md) - 验证助手质量并定位问题
|
||||
|
||||
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) - 评估对话质量
|
||||
@@ -1,349 +1,107 @@
|
||||
# 引擎架构详解
|
||||
# 引擎架构
|
||||
|
||||
深入了解 RAS 的两种引擎架构：管线式引擎和多模态引擎。
|
||||
RAS 提供两类实时运行时：**Pipeline 引擎** 和 **Realtime 引擎**。本页只回答一个问题：你的助手应该跑在哪种引擎上。
|
||||
|
||||
---
|
||||
|
||||
## 引擎概述
|
||||
## 先记住这条判断标准
|
||||
|
||||
引擎是 RAS 的核心，负责处理实时语音交互。根据不同需求，可以选择两种架构：
|
||||
- 如果你优先考虑 **可控性、可替换性、成本管理、工具 / 知识 / 流程编排**，优先选 **Pipeline 引擎**
|
||||
- 如果你优先考虑 **超低延迟、更自然的端到端语音体验**，优先选 **Realtime 引擎**
|
||||
|
||||
| 架构 | 特点 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| **管线式** | 灵活、可定制、成本可控 | 大多数场景 |
|
||||
| **多模态** | 低延迟、自然、简单 | 高端体验场景 |
|
||||
## 两类引擎的区别
|
||||
|
||||
---
|
||||
| 维度 | Pipeline 引擎 | Realtime 引擎 |
|
||||
|------|---------------|---------------|
|
||||
| **交互路径** | VAD → ASR → TD → LLM → TTS | 端到端实时模型 |
|
||||
| **可控性** | 高，每个环节可替换 | 中，更多依赖模型供应商 |
|
||||
| **延迟** | 中等，通常由多环节累加 | 低，链路更短 |
|
||||
| **能力编排** | 更适合接入工具、知识库、工作流 | 也可接工具，但流程可控性较弱 |
|
||||
| **成本结构** | 可按环节优化 | 往往更依赖单一供应商定价 |
|
||||
| **适合场景** | 企业客服、流程型助手、电话场景、知识问答 | 高拟真语音助手、多模态入口、高自然度体验 |
|
||||
|
||||
## 管线式引擎 (Pipeline)
|
||||
## Pipeline 引擎是什么
|
||||
|
||||
### 架构设计
|
||||
|
||||
管线式引擎包含 **声音活动检测（VAD）**、**语音识别（ASR）**、**回合检测（TD）**、**大语言模型（LLM）**、**语音合成（TTS）**，各环节可对接**外部服务**（OpenAI、SiliconFlow、DashScope、本地模型）。LLM 可连接**工具**（Webhook、客户端工具、内建工具）。
|
||||
Pipeline 引擎把实时语音拆成多个明确环节：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Input["输入处理"]
|
||||
Audio[用户音频] --> VAD[声音活动检测 VAD]
|
||||
VAD --> ASR[语音识别 ASR]
|
||||
ASR --> Text[转写文本]
|
||||
Text --> TD[回合检测 TD]
|
||||
end
|
||||
|
||||
subgraph Process["语义处理"]
|
||||
TD --> LLM[大语言模型 LLM]
|
||||
LLM --> Response[回复文本]
|
||||
LLM --> Tools[工具]
|
||||
end
|
||||
|
||||
subgraph Output["输出生成"]
|
||||
Response --> TTS[语音合成 TTS]
|
||||
TTS --> OutputAudio[助手音频]
|
||||
end
|
||||
VAD[VAD] --> ASR[ASR]
|
||||
ASR --> TD[回合检测]
|
||||
TD --> LLM[LLM]
|
||||
LLM --> TTS[TTS]
|
||||
```
|
||||
|
||||
### 数据流详解
|
||||
这样做的好处是：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant ASR as ASR 服务
|
||||
participant LLM as LLM 服务
|
||||
participant TTS as TTS 服务
|
||||
- 你可以分别选择 ASR、LLM、TTS 的供应商
|
||||
- 你可以单独优化某一个环节，而不是整体替换
|
||||
- 工具、知识库和工作流更容易插入到链路中
|
||||
|
||||
U->>E: 音频帧 (PCM 16kHz)
|
||||
|
||||
Note over E: VAD 检测语音活动
|
||||
E->>E: 累积音频缓冲
|
||||
|
||||
Note over E: 回合检测 (TD) 确定可送 LLM 的输入
|
||||
E->>ASR: 发送音频
|
||||
ASR-->>E: 转写文本 (流式)
|
||||
E-->>U: transcript.delta
|
||||
E-->>U: transcript.final
|
||||
|
||||
E->>LLM: 发送对话历史 + 用户输入
|
||||
LLM-->>E: 回复文本 (流式)
|
||||
E-->>U: assistant.response.delta
|
||||
|
||||
loop 流式合成
|
||||
E->>TTS: 文本片段
|
||||
TTS-->>E: 音频片段
|
||||
E-->>U: 音频帧
|
||||
end
|
||||
|
||||
E-->>U: assistant.response.final
|
||||
```
|
||||
代价是：
|
||||
|
||||
### 延迟分析
|
||||
- 延迟会累加
|
||||
- 系统集成更复杂
|
||||
- 你需要同时管理多类外部依赖
|
||||
|
||||
管线式引擎的延迟由各环节累加：
|
||||
## Realtime 引擎是什么
|
||||
|
||||
| 环节 | 典型延迟 | 优化方向 |
|
||||
|------|---------|---------|
|
||||
| VAD/EOU | 200-500ms | 调整灵敏度 |
|
||||
| ASR | 100-300ms | 选择快速模型 |
|
||||
| LLM TTFT | 200-500ms | 选择低延迟模型 |
|
||||
| TTS | 100-200ms | 流式合成 |
|
||||
| **总计** | **600-1500ms** | - |
|
||||
|
||||
### 流式优化
|
||||
|
||||
为降低感知延迟，采用流式处理：
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title 非流式 vs 流式处理
|
||||
dateFormat X
|
||||
axisFormat %s
|
||||
|
||||
section 非流式
|
||||
ASR完成 :a1, 0, 300ms
|
||||
LLM完成 :a2, after a1, 800ms
|
||||
TTS完成 :a3, after a2, 500ms
|
||||
播放 :a4, after a3, 500ms
|
||||
|
||||
section 流式
|
||||
ASR :b1, 0, 300ms
|
||||
LLM开始 :b2, after b1, 200ms
|
||||
TTS开始 :b3, after b2, 100ms
|
||||
边生成边播放 :b4, after b3, 600ms
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实时交互引擎与多模态
|
||||
|
||||
### 实时交互引擎连接
|
||||
|
||||
实时交互引擎可连接**实时交互引擎**后端，包括：
|
||||
|
||||
| 后端 | 说明 |
|
||||
|------|------|
|
||||
| **OpenAI Realtime** | OpenAI 实时语音模型 |
|
||||
| **Gemini Live** | Google 实时多模态 |
|
||||
| **Doubao 实时交互引擎** | 豆包实时交互 |
|
||||
|
||||
实时交互引擎与管线式引擎中的 LLM 一样，均可连接**工具**：Webhook、客户端工具、内建工具。
|
||||
|
||||
### 多模态引擎架构
|
||||
|
||||
多模态引擎使用端到端模型，直接处理音频输入输出：
|
||||
Realtime 引擎直接连接端到端实时模型，让模型同时处理输入、理解、生成与打断。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Client["客户端"]
|
||||
Mic[麦克风] --> AudioIn[音频输入]
|
||||
AudioOut[音频输出] --> Speaker[扬声器]
|
||||
end
|
||||
|
||||
subgraph Engine["引擎"]
|
||||
AudioIn --> RT[Realtime Model]
|
||||
RT --> AudioOut
|
||||
RT --> Tools[工具]
|
||||
end
|
||||
|
||||
subgraph Model["实时交互引擎"]
|
||||
RT --> GPT4o[OpenAI Realtime]
|
||||
RT --> Gemini[Gemini Live]
|
||||
RT --> Doubao[Doubao 实时]
|
||||
end
|
||||
Input[音频 / 视频 / 文本输入] --> RT[Realtime Model]
|
||||
RT --> Output[音频 / 文本输出]
|
||||
RT --> Tools[工具]
|
||||
```
|
||||
|
||||
### 数据流详解
|
||||
这样做的好处是：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant RT as Realtime Model
|
||||
- 链路更短，延迟更低
|
||||
- 全双工与打断通常更自然
|
||||
- 接入路径更简单，适合强调体验的入口
|
||||
|
||||
U->>E: 音频帧
|
||||
E->>RT: 转发音频
|
||||
|
||||
Note over RT: 端到端处理
|
||||
|
||||
RT-->>E: 音频响应 (流式)
|
||||
E-->>U: 播放音频
|
||||
|
||||
Note over U,RT: 支持全双工<br/>用户可随时打断
|
||||
```
|
||||
代价是：
|
||||
|
||||
### 外部服务（管线式）
|
||||
- 更依赖特定模型供应商
|
||||
- 对 ASR / TTS / 回合检测的独立控制更弱
|
||||
- 成本和能力边界受实时模型限制更大
|
||||
|
||||
管线式引擎各环节可选用以下**外部服务**：
|
||||
## 怎么选
|
||||
|
||||
| 服务 | 说明 |
|
||||
|------|------|
|
||||
| **OpenAI** | LLM / ASR / TTS 等 |
|
||||
| **SiliconFlow** | 国内 API 服务 |
|
||||
| **DashScope** | 阿里云灵积 |
|
||||
| **本地模型** | 私有化部署模型 |
|
||||
### 适合选择 Pipeline 的情况
|
||||
|
||||
### 支持的实时交互模型
|
||||
- 你要接入特定 ASR 或 TTS 供应商
|
||||
- 你需要知识库、工具、工作流形成稳定业务流程
|
||||
- 你更在意可解释性、观测和分段优化
|
||||
- 你需要把成本按环节精细控制
|
||||
|
||||
| 模型 | 供应商 | 特点 |
|
||||
|------|--------|------|
|
||||
| **OpenAI Realtime** | OpenAI | 最自然的语音，延迟极低 |
|
||||
| **Gemini Live** | Google | 多模态能力强 |
|
||||
| **Doubao 实时交互** | 字节跳动 | 国内可用，中文优化 |
|
||||
### 适合选择 Realtime 的情况
|
||||
|
||||
### 延迟对比
|
||||
- 你把“自然对话感”放在首位
|
||||
- 你需要更低的首响和更顺滑的打断体验
|
||||
- 你可以接受对某个模型供应商的依赖
|
||||
- 你的场景更接近语音助手、陪练、虚拟角色或多模态入口
|
||||
|
||||
```mermaid
|
||||
xychart-beta
|
||||
title "端到端延迟对比"
|
||||
x-axis ["管线式 (普通)", "管线式 (优化)", "多模态"]
|
||||
y-axis "延迟 (ms)" 0 --> 1500
|
||||
bar [1200, 700, 300]
|
||||
```
|
||||
## 简化决策表
|
||||
|
||||
---
|
||||
| 场景 | 推荐引擎 | 原因 |
|
||||
|------|----------|------|
|
||||
| 企业客服 / 电话机器人 | Pipeline | 可控、可审计、易接工具与业务系统 |
|
||||
| 知识问答 / 业务流程助手 | Pipeline | 更适合接知识库与工作流 |
|
||||
| 高拟真语音助手 | Realtime | 更自然、更低延迟 |
|
||||
| 多模态入口 | Realtime | 端到端处理音频 / 视频 / 文本 |
|
||||
| 预算敏感场景 | Pipeline | 更容易逐环节优化成本 |
|
||||
|
||||
## 智能打断机制
|
||||
## 智能打断的差异
|
||||
|
||||
两种引擎都支持智能打断，但实现方式不同。
|
||||
两类引擎都支持打断，但边界不同：
|
||||
|
||||
### 管线式引擎打断
|
||||
- **Pipeline**：由 VAD / 回合检测与 TTS 停止逻辑协同实现，行为更可控
|
||||
- **Realtime**：更多由实时模型内部完成，体验更自然，但可解释性更低
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant TTS as TTS
|
||||
## 继续阅读
|
||||
|
||||
Note over E,TTS: TTS 正在合成播放
|
||||
E->>U: 音频帧...
|
||||
|
||||
U->>E: 用户说话 (检测到 VAD)
|
||||
E->>E: 判断是否有效打断
|
||||
|
||||
alt 有效打断
|
||||
E->>TTS: 停止合成
|
||||
E->>E: 清空音频缓冲
|
||||
E-->>U: output.audio.interrupted
|
||||
Note over E: 处理新输入
|
||||
else 噪音/误触发
|
||||
Note over E: 继续播放
|
||||
end
|
||||
```
|
||||
|
||||
### 多模态引擎打断
|
||||
|
||||
多模态模型原生支持全双工，打断由模型内部处理：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant RT as Realtime Model
|
||||
|
||||
Note over RT: 模型正在输出
|
||||
RT-->>E: 音频流...
|
||||
E-->>U: 播放
|
||||
|
||||
U->>E: 用户说话
|
||||
E->>RT: 转发用户音频
|
||||
|
||||
Note over RT: 模型检测到打断<br/>自动停止输出
|
||||
|
||||
RT-->>E: 新的响应
|
||||
E-->>U: 播放新响应
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 引擎选择指南
|
||||
|
||||
### 决策流程
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start[选择引擎] --> Q1{延迟要求?}
|
||||
|
||||
Q1 -->|< 500ms| Q2{预算充足?}
|
||||
Q1 -->|> 500ms 可接受| Pipeline[管线式引擎]
|
||||
|
||||
Q2 -->|是| Q3{模型可用?}
|
||||
Q2 -->|否| Pipeline
|
||||
|
||||
Q3 -->|GPT-4o/Gemini 可用| Multimodal[多模态引擎]
|
||||
Q3 -->|国内环境受限| Q4{Step Audio?}
|
||||
|
||||
Q4 -->|可用| Multimodal
|
||||
Q4 -->|不可用| Pipeline
|
||||
```
|
||||
|
||||
### 场景推荐
|
||||
|
||||
| 场景 | 推荐引擎 | 理由 |
|
||||
|------|---------|------|
|
||||
| **企业客服** | 管线式 | 成本可控，可定制 ASR |
|
||||
| **高端虚拟人** | 多模态 | 最自然的交互体验 |
|
||||
| **电话机器人** | 管线式 | 可对接电信 ASR |
|
||||
| **语音助手** | 多模态 | 低延迟，自然对话 |
|
||||
| **口语练习** | 管线式 | 需要精确的 ASR 评分 |
|
||||
|
||||
### 混合方案
|
||||
|
||||
也可以根据用户等级使用不同引擎：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User[用户请求] --> Router{路由判断}
|
||||
|
||||
Router -->|VIP 用户| Multimodal[多模态引擎]
|
||||
Router -->|普通用户| Pipeline[管线式引擎]
|
||||
|
||||
Multimodal --> Response[响应]
|
||||
Pipeline --> Response
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 管线式引擎配置
|
||||
|
||||
```json
|
||||
{
|
||||
"engine": "pipeline",
|
||||
"asr": {
|
||||
"provider": "openai-compatible",
|
||||
"model": "FunAudioLLM/SenseVoiceSmall",
|
||||
"language": "zh"
|
||||
},
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-mini",
|
||||
"temperature": 0.7
|
||||
},
|
||||
"tts": {
|
||||
"provider": "openai-compatible",
|
||||
"model": "FunAudioLLM/CosyVoice2-0.5B",
|
||||
"voice": "anna"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 多模态引擎配置
|
||||
|
||||
```json
|
||||
{
|
||||
"engine": "multimodal",
|
||||
"model": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-realtime-preview",
|
||||
"voice": "alloy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [系统架构](../overview/architecture.md) - 整体架构设计
|
||||
- [WebSocket 协议](../api-reference/websocket.md) - 协议详情
|
||||
- [部署指南](../deployment/index.md) - 引擎部署配置
|
||||
- [Pipeline 引擎](pipeline-engine.md) - 查看分段链路、延迟构成与配置示例
|
||||
- [Realtime 引擎](realtime-engine.md) - 查看端到端实时模型的交互路径
|
||||
- [系统架构](../overview/architecture.md) - 从服务边界理解引擎在整体系统中的位置
|
||||
|
||||
@@ -1,296 +1,49 @@
|
||||
# 核心概念
|
||||
# 核心概念
|
||||
|
||||
本章节介绍 Realtime Agent Studio 中的核心概念，帮助你更好地理解和使用平台。
|
||||
本章节只解释 Realtime Agent Studio 的关键心智模型，不重复环境部署或助手构建的操作细节。
|
||||
|
||||
---
|
||||
|
||||
## 概念总览
|
||||
## 先建立这三个概念
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Platform["RAS 平台"]
|
||||
Assistant[助手 Assistant]
|
||||
|
||||
subgraph Resources["资源库"]
|
||||
LLM[LLM 模型]
|
||||
ASR[ASR 模型]
|
||||
TTS[TTS 声音]
|
||||
KB[知识库]
|
||||
end
|
||||
|
||||
subgraph Engine["交互引擎"]
|
||||
Pipeline[Pipeline引擎]
|
||||
Multimodal[Realtime引擎]
|
||||
end
|
||||
|
||||
Session[会话 Session]
|
||||
end
|
||||
### 1. 助手是“对外提供能力的配置单元”
|
||||
|
||||
Assistant --> LLM
|
||||
Assistant --> ASR
|
||||
Assistant --> TTS
|
||||
Assistant --> KB
|
||||
Assistant --> Engine
|
||||
Engine --> Session
|
||||
```
|
||||
助手决定了一个实时 AI 入口对外表现成什么角色：它使用什么提示词、哪些模型、能访问哪些知识和工具、会话如何开始以及运行时如何被覆盖。
|
||||
|
||||
- [助手概念](assistants.md) — 统一理解助手、会话、动态变量与能力边界
|
||||
- [配置选项](assistants/configuration.md) — 了解界面层和运行时配置项如何分工
|
||||
- [提示词指南](assistants/prompts.md) — 学会定义助手的角色、任务、风格与约束
|
||||
- [测试调试](assistants/testing.md) — 理解如何验证助手行为和定位问题
|
||||
|
||||
### 2. 引擎是“承载实时交互的运行时”
|
||||
|
||||
RAS 同时提供 Pipeline 引擎与 Realtime 引擎。它们都能驱动实时助手，但在延迟、可控性、成本和可替换性上各有取舍。
|
||||
|
||||
- [引擎概览](engines.md) — 两类引擎的能力边界与选择建议
|
||||
- [Pipeline 引擎](pipeline-engine.md) — VAD/ASR/TD/LLM/TTS 串联的可组合链路
|
||||
- [Realtime 引擎](realtime-engine.md) — 面向端到端实时模型的低延迟交互路径
|
||||
|
||||
### 3. 工作流是“把复杂业务拆成步骤和分支的方法”
|
||||
|
||||
当单一提示词不足以稳定处理多步骤、多条件、多工具的业务流程时，应使用工作流来显式编排节点、路由和回退策略。
|
||||
|
||||
- [工作流](../customization/workflows.md) — 了解何时需要工作流、它由哪些部分组成、如何设计可维护的流程
|
||||
|
||||
---
|
||||
|
||||
## 助手 (Assistant)
|
||||
## 本章节不负责什么
|
||||
|
||||
**助手**是 RAS 的核心实体，代表一个可对话的 AI 智能体。
|
||||
以下内容属于“如何搭建和使用”，不在本章节展开说明：
|
||||
|
||||
### 助手配置
|
||||
- 助手搭建、模型/知识库/工具/工作流配置：从 [助手概览](assistants.md) 进入构建链路
|
||||
- 部署与环境变量：见 [环境与部署](../getting-started/index.md)
|
||||
- 第一个助手的最短操作路径：见 [快速开始](../quickstart/index.md)
|
||||
- 事件格式与接入协议：见 [API 参考](../api-reference/index.md)
|
||||
|
||||
每个助手包含以下配置：
|
||||
## 建议阅读顺序
|
||||
|
||||
| 配置项 | 说明 |
|
||||
|-------|------|
|
||||
| **名称** | 助手的显示名称 |
|
||||
| **指令配置** | 使用提示词指令定义助手角色、行为、限制 |
|
||||
| **语音设置** | 包括语音识别模型，语音合成模型 |
|
||||
| **交互设置** | 包括用户打断机器人的灵敏度，检测用户语句结束的灵敏度 |
|
||||
| **工具配置** | 配置助手可调用的外部工具 |
|
||||
| **知识配置** | 关联的知识库（用于 RAG） |
|
||||
| **Webhooks** | 用于订阅助手的活动 |
|
||||
1. 先读 [助手概念](assistants.md)，明确你要配置的对象到底是什么
|
||||
2. 再读 [引擎概览](engines.md)，决定应该选择 Pipeline 还是 Realtime
|
||||
3. 如果场景涉及多步骤流程，再读 [工作流](../customization/workflows.md)
|
||||
4. 最后回到 [快速开始](../quickstart/index.md) 或 [助手概览](assistants.md) 开始具体配置
|
||||
|
||||
---
|
||||
|
||||
## 会话 (Session)
|
||||
|
||||
**会话**代表一次完整的对话交互，从用户连接到断开。
|
||||
|
||||
### 会话状态
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Connecting: WebSocket 连接
|
||||
Connecting --> Started: session.started
|
||||
Started --> Active: 对话中
|
||||
Active --> Active: 多轮对话
|
||||
Active --> Stopped: session.stop
|
||||
Stopped --> [*]: 连接关闭
|
||||
```
|
||||
|
||||
### 会话数据
|
||||
|
||||
每个会话记录包含：
|
||||
|
||||
- **基本信息** - ID、时长、时间戳
|
||||
- **音频数据** - 用户和助手的音频记录
|
||||
- **转写文本** - ASR 识别结果
|
||||
- **LLM 交互** - 输入输出和工具调用
|
||||
- **元数据** - 渠道、来源、自定义变量
|
||||
|
||||
---
|
||||
|
||||
## Pipeline引擎 vs Realtime引擎
|
||||
|
||||
RAS 支持两种引擎架构，适用于不同场景。
|
||||
|
||||
### 管线式引擎 (Pipeline)
|
||||
|
||||
将语音交互拆分为多个环节，包含 **VAD（声音活动检测）**、**ASR（语音识别）**、**TD（回合检测）**、**LLM（大语言模型）**、**TTS（语音合成）**。外部服务可选 **OpenAI**、**SiliconFlow**、**DashScope**、**本地模型**。LLM 与实时交互引擎均可连接**工具**（Webhook、客户端工具、内建工具）。
|
||||
|
||||
```
|
||||
用户语音 → [VAD] → [ASR] → [TD] → 文本 → [LLM] → 回复 → [TTS] → 助手语音
|
||||
```
|
||||
|
||||
**优点：**
|
||||
|
||||
- 灵活选择各环节供应商（OpenAI、SiliconFlow、DashScope、本地模型）
|
||||
- 可独立优化 VAD、ASR、TD、LLM、TTS 每个环节
|
||||
- 成本可控
|
||||
|
||||
**缺点：**
|
||||
|
||||
- 延迟较高（累加延迟）
|
||||
- 需要协调多个服务
|
||||
|
||||
### 实时交互引擎 (Realtime)
|
||||
|
||||
实时交互引擎可连接 **OpenAI Realtime**、**Gemini Live**、**Doubao 实时交互引擎** 等，同样可连接工具。使用端到端模型直接处理：
|
||||
|
||||
```
|
||||
用户语音 → [Realtime Model] → 助手语音
|
||||
```
|
||||
|
||||
**优点：**
|
||||
|
||||
- 更低延迟
|
||||
- 更自然的语音
|
||||
- 架构简单
|
||||
|
||||
**缺点：**
|
||||
|
||||
- 依赖特定供应商
|
||||
- 成本较高
|
||||
- 可定制性有限
|
||||
|
||||
### 选择建议
|
||||
|
||||
| 场景 | 推荐引擎 |
|
||||
|------|---------|
|
||||
| 成本敏感 | 管线式 |
|
||||
| 延迟敏感 | 多模态 |
|
||||
| 需要特定 ASR/TTS | 管线式 |
|
||||
| 追求最自然体验 | 多模态 |
|
||||
|
||||
---
|
||||
|
||||
## 智能打断 (Barge-in)
|
||||
|
||||
**智能打断**是指用户在助手说话时可以随时插话，系统能够：
|
||||
|
||||
1. 检测用户开始说话
|
||||
2. 立即停止 TTS 播放
|
||||
3. 处理用户新的输入
|
||||
|
||||
### 打断检测方式
|
||||
|
||||
| 方式 | 说明 |
|
||||
|------|------|
|
||||
| **VAD** | Voice Activity Detection，检测到声音活动即打断 |
|
||||
| **语义** | 基于语音内容判断是否有意义的打断 |
|
||||
| **混合** | VAD + 语义结合，减少误触发 |
|
||||
|
||||
### 打断流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant Engine as 引擎
|
||||
participant TTS as TTS
|
||||
|
||||
Note over Engine,TTS: 助手正在播放回复
|
||||
Engine->>User: 音频流...
|
||||
User->>Engine: 开始说话 (VAD 触发)
|
||||
Engine->>Engine: 打断判断
|
||||
Engine->>TTS: 停止合成
|
||||
Engine->>User: output.audio.interrupted
|
||||
Note over Engine: 处理新输入
|
||||
```
|
||||
|
||||
## 用户语句端点（EoU End-of-Utterance）
|
||||
|
||||
**用户语句端点（EoU）** 指系统判断「用户已经说完」的时刻。在管线式引擎中，只有检测到 EoU 后，才会把当前轮次的转写文本送给 LLM 并触发回复，避免用户短暂停顿时就误判为说完。
|
||||
|
||||
### 检测方式
|
||||
|
||||
EoU 基于 **VAD（声音活动检测）** 的输出：在用户**连续静音**达到设定时长后触发一次 EoU。若静音期间用户再次说话，静音计时会重置，因此句间短暂停顿不会触发 EoU，只有用户真正停止说话后才触发。
|
||||
|
||||
| 概念 | 说明 |
|
||||
|------|------|
|
||||
| **静音阈值** | 连续静音超过该时长（毫秒）即判定为 EoU，对应配置如 `vad_eou_threshold_ms`（默认约 800ms） |
|
||||
| **最短语音** | 若语音过短（如杂音），不触发 EoU，避免误判 |
|
||||
| **一次一轮** | 每轮用户输入只产生一次 EoU，之后需重新检测语音再静音才会再次触发 |
|
||||
|
||||
### 在管线中的位置
|
||||
|
||||
```
|
||||
用户语音 → [VAD] → [EoU 检测] → 静音达阈值 → 文本送 LLM → 回复 → [TTS]
|
||||
```
|
||||
|
||||
助手配置中的 **「检测用户语句结束的灵敏度」** 即对应 EoU 的静音阈值：阈值越小，越容易判定为「说完」，响应更快但易在用户思考或短暂停顿时误触发；阈值越大，更稳但响应会稍慢。
|
||||
|
||||
---
|
||||
|
||||
## 工具调用 (Tool Calling)
|
||||
|
||||
助手可以通过**工具**扩展能力，访问外部系统或执行特定操作。
|
||||
|
||||
### 工具类型
|
||||
|
||||
管线式引擎中的 LLM 与实时交互引擎均可连接**工具**，包括：
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| **Webhook** | 调用外部 HTTP API | 查询订单、预约日程 |
|
||||
| **客户端工具** | 由客户端执行的操作 | 获取客户端地理位置、请求用户同意、打开客户端相机 |
|
||||
| **内建工具** | 平台提供的工具 | 代码执行、计算器 |
|
||||
|
||||
### 工具调用流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant LLM as LLM
|
||||
participant Tool as 工具
|
||||
|
||||
User->>LLM: "帮我查一下订单状态"
|
||||
LLM->>LLM: 决定调用工具
|
||||
LLM->>Tool: get_order_status(order_id)
|
||||
Tool-->>LLM: {status: "已发货"}
|
||||
LLM->>User: "您的订单已发货"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 知识库 (Knowledge Base)
|
||||
|
||||
**知识库**让助手能够基于私有文档回答问题，实现 RAG（检索增强生成）。
|
||||
|
||||
### 工作原理
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Indexing["索引阶段"]
|
||||
Doc[文档] --> Chunk[分块]
|
||||
Chunk --> Embed[向量化]
|
||||
Embed --> Store[(向量数据库)]
|
||||
end
|
||||
|
||||
subgraph Query["查询阶段"]
|
||||
Q[用户问题] --> QEmbed[问题向量化]
|
||||
QEmbed --> Search[相似度搜索]
|
||||
Store --> Search
|
||||
Search --> Context[相关上下文]
|
||||
Context --> LLM[LLM 生成回答]
|
||||
end
|
||||
```
|
||||
|
||||
### 支持的文档格式
|
||||
|
||||
- PDF
|
||||
- Word (.docx)
|
||||
- Markdown
|
||||
- 纯文本
|
||||
- HTML
|
||||
|
||||
---
|
||||
|
||||
## 动态变量
|
||||
|
||||
**动态变量**允许在运行时向助手注入上下文信息。
|
||||
|
||||
### 使用方式
|
||||
|
||||
在系统提示词中使用 `{{variable}}` 占位符：
|
||||
|
||||
```
|
||||
你是{{company_name}}的客服助手。
|
||||
当前用户是{{customer_name}}，会员等级为{{tier}}。
|
||||
```
|
||||
|
||||
连接时通过 `dynamicVariables` 传入：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "session.start",
|
||||
"metadata": {
|
||||
"dynamicVariables": {
|
||||
"company_name": "ABC 公司",
|
||||
"customer_name": "张三",
|
||||
"tier": "VIP"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 下一步
|
||||
|
||||
- [快速开始](../quickstart/index.md) - 创建第一个助手
|
||||
- [助手配置](../assistants/configuration.md) - 详细配置说明
|
||||
- [WebSocket 协议](../api-reference/websocket.md) - API 接口详情
|
||||
|
||||
137
docs/content/concepts/pipeline-engine.md
Normal file
137
docs/content/concepts/pipeline-engine.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# Pipeline 引擎
|
||||
|
||||
Pipeline 引擎把实时对话拆成多个清晰环节，适合需要高可控性、可替换外部能力和复杂业务编排的场景。
|
||||
|
||||
---
|
||||
|
||||
## 运行链路
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Input["输入处理"]
|
||||
Audio[用户音频] --> VAD[声音活动检测 VAD]
|
||||
VAD --> ASR[语音识别 ASR]
|
||||
ASR --> TD[回合检测 TD]
|
||||
end
|
||||
|
||||
subgraph Reasoning["语义处理"]
|
||||
TD --> LLM[大语言模型 LLM]
|
||||
LLM --> Tools[工具]
|
||||
LLM --> Text[回复文本]
|
||||
end
|
||||
|
||||
subgraph Output["输出生成"]
|
||||
Text --> TTS[语音合成 TTS]
|
||||
TTS --> AudioOut[助手音频]
|
||||
end
|
||||
```
|
||||
|
||||
Pipeline 的关键价值不在于“环节多”，而在于每个环节都可以被单独选择、单独优化、单独观测。
|
||||
|
||||
## 它适合什么场景
|
||||
|
||||
- 需要接特定 ASR / TTS 供应商
|
||||
- 需要稳定接入知识库、工具和工作流
|
||||
- 需要把问题定位到具体环节，而不是只看到整体失败
|
||||
- 需要按延迟、成本、质量对不同环节分别优化
|
||||
|
||||
## 数据流
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant ASR as ASR 服务
|
||||
participant LLM as LLM 服务
|
||||
participant TTS as TTS 服务
|
||||
|
||||
U->>E: 音频帧 (PCM)
|
||||
E->>E: VAD / 回合检测
|
||||
E->>ASR: 发送可识别音频
|
||||
ASR-->>E: transcript.delta / transcript.final
|
||||
E->>LLM: 发送对话历史与当前输入
|
||||
LLM-->>E: assistant.response.delta
|
||||
E->>TTS: 文本片段
|
||||
TTS-->>E: 音频片段
|
||||
E-->>U: 音频流与事件
|
||||
```
|
||||
|
||||
## 延迟来自哪里
|
||||
|
||||
| 环节 | 典型影响 | 常见优化点 |
|
||||
|------|----------|------------|
|
||||
| **VAD / EoU** | 用户说完后多久触发回复 | 调整静音阈值和最短语音门限 |
|
||||
| **ASR** | 语音转写速度和准确率 | 选择合适模型、热词和语言设置 |
|
||||
| **LLM** | 首个 token 返回速度 | 选择低延迟模型、优化上下文 |
|
||||
| **TTS** | 文字到音频的生成速度 | 选择流式 TTS，缩短单次回复 |
|
||||
|
||||
Pipeline 的总延迟通常不是单点问题，而是链路总和。因此更适合做“逐环节调优”。
|
||||
|
||||
## EoU（用户说完）为什么重要
|
||||
|
||||
Pipeline 必须决定“什么时候把当前轮输入正式交给 LLM”。这个判断通常由 **EoU** 完成。
|
||||
|
||||
- 阈值小：响应更快，但更容易把用户停顿误判为说完
|
||||
- 阈值大：更稳，但首次响应会更慢
|
||||
|
||||
你可以把它理解为 Pipeline 中最直接影响“对话节奏感”的参数之一。
|
||||
|
||||
## 工具、知识库和工作流如何插入
|
||||
|
||||
Pipeline 特别适合把业务能力插入到对话中：
|
||||
|
||||
- **知识库**：在 LLM 生成前补充领域事实
|
||||
- **工具**：在需要外部信息或动作时调用系统能力
|
||||
- **工作流**：在多步骤、多分支流程中决定接下来走哪个节点
|
||||
|
||||
这也是它在企业客服、流程助手和知识问答场景中更常见的原因。
|
||||
|
||||
## 智能打断
|
||||
|
||||
在 Pipeline 中，打断通常由 VAD 检测和 TTS 停止逻辑协同完成：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant TTS as TTS
|
||||
|
||||
Note over E,TTS: 正在播放回复
|
||||
E->>U: 音频流...
|
||||
U->>E: 用户开始说话
|
||||
E->>E: 判定是否触发打断
|
||||
E->>TTS: 停止合成 / 播放
|
||||
E-->>U: output.audio.interrupted
|
||||
```
|
||||
|
||||
相比端到端实时模型，这种方式更容易解释“为什么打断”以及“在哪个环节发生了问题”。
|
||||
|
||||
## 配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"engine": "pipeline",
|
||||
"asr": {
|
||||
"provider": "openai-compatible",
|
||||
"model": "FunAudioLLM/SenseVoiceSmall",
|
||||
"language": "zh"
|
||||
},
|
||||
"llm": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-mini",
|
||||
"temperature": 0.7
|
||||
},
|
||||
"tts": {
|
||||
"provider": "openai-compatible",
|
||||
"model": "FunAudioLLM/CosyVoice2-0.5B",
|
||||
"voice": "anna"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [引擎架构](engines.md) - 回到选择指南
|
||||
- [Realtime 引擎](realtime-engine.md) - 对比端到端实时模型路径
|
||||
- [工具](../customization/tools.md) - 设计可被 LLM 安全调用的工具
|
||||
- [知识库](../customization/knowledge-base.md) - 在对话中补充领域知识
|
||||
97
docs/content/concepts/realtime-engine.md
Normal file
97
docs/content/concepts/realtime-engine.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Realtime 引擎
|
||||
|
||||
Realtime 引擎直接连接端到端实时模型，适合把低延迟和自然语音体验放在第一位的场景。
|
||||
|
||||
---
|
||||
|
||||
## 运行链路
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Input[音频 / 视频 / 文本输入] --> RT[Realtime Model]
|
||||
RT --> Output[音频 / 文本输出]
|
||||
RT --> Tools[工具]
|
||||
```
|
||||
|
||||
与 Pipeline 不同，Realtime 引擎不会把 ASR、回合检测、LLM、TTS 作为独立阶段暴露出来，而是更多依赖实时模型整体处理。
|
||||
|
||||
## 常见后端
|
||||
|
||||
| 后端 | 特点 |
|
||||
|------|------|
|
||||
| **OpenAI Realtime** | 语音交互自然，延迟低 |
|
||||
| **Gemini Live** | 多模态能力强 |
|
||||
| **Doubao 实时交互** | 更适合国内环境与中文场景 |
|
||||
|
||||
## 它适合什么场景
|
||||
|
||||
- 语音助手、陪练、虚拟角色等高自然度体验场景
|
||||
- 对首响和连续打断体验要求高的入口
|
||||
- 希望减少链路拼装复杂度，直接接入端到端模型的团队
|
||||
|
||||
## 数据流
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant RT as Realtime Model
|
||||
|
||||
U->>E: 音频 / 视频 / 文本输入
|
||||
E->>RT: 转发实时流
|
||||
RT-->>E: 流式文本 / 音频输出
|
||||
E-->>U: 播放或渲染结果
|
||||
```
|
||||
|
||||
## Realtime 的优势
|
||||
|
||||
- **延迟更低**：链路更短，用户感知更自然
|
||||
- **全双工更顺滑**：用户插话时，模型更容易在内部处理打断
|
||||
- **多模态更直接**：适合音频、视频、文本混合输入输出场景
|
||||
|
||||
## Realtime 的取舍
|
||||
|
||||
- 更依赖实时模型供应商的能力边界
|
||||
- 不容易对 ASR / TTS / 回合检测做独立替换
|
||||
- 成本和可观测性往往不如 Pipeline 那样可逐环节拆分
|
||||
|
||||
## 智能打断
|
||||
|
||||
Realtime 模型通常原生支持全双工和打断：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 用户
|
||||
participant E as 引擎
|
||||
participant RT as Realtime Model
|
||||
|
||||
Note over RT: 模型正在输出
|
||||
RT-->>E: 音频流...
|
||||
E-->>U: 播放
|
||||
U->>E: 用户开始说话
|
||||
E->>RT: 转发新输入
|
||||
Note over RT: 模型内部处理中断并切换回复
|
||||
RT-->>E: 新的响应
|
||||
E-->>U: 播放新响应
|
||||
```
|
||||
|
||||
这种方式更自然，但你通常只能看到模型的整体行为，而不是每个中间阶段的细节。
|
||||
|
||||
## 配置示例
|
||||
|
||||
```json
|
||||
{
|
||||
"engine": "multimodal",
|
||||
"model": {
|
||||
"provider": "openai",
|
||||
"model": "gpt-4o-realtime-preview",
|
||||
"voice": "alloy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [引擎架构](engines.md) - 回到两类引擎的选择指南
|
||||
- [Pipeline 引擎](pipeline-engine.md) - 查看分段可控的运行路径
|
||||
- [WebSocket 协议](../api-reference/websocket.md) - 了解客户端如何与引擎建立会话
|
||||
Reference in New Issue
Block a user