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) - 验证助手质量并定位问题
|
||||
|
||||
Reference in New Issue
Block a user