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.
2026-03-09 05:38:43 +08:00
parent 65ae2287d5
commit b300b469dc
34 changed files with 1776 additions and 2981 deletions
--- a/docs/content/overview/architecture.md
+++ b/docs/content/overview/architecture.md
@@ -1,6 +1,6 @@
-# 系统架构
+# 系统架构

-本文档详细介绍 Realtime Agent Studio (RAS) 的系统架构设计。
+本文档只解释 Realtime Agent Studio (RAS) 的服务边界、数据流、部署形态和关键技术选型，不重复产品定位或上手流程。

 ---

@@ -61,12 +61,12 @@ flowchart TB

 ### 1. Web 前端 (React)

-管理控制台，提供可视化的配置和监控界面。
+管理控制台，提供可视化的配置、测试和监控界面。

 | 功能模块 | 说明 |
 |---------|------|
 | 助手管理 | 创建、配置、测试智能助手 |
-| 资源库 | LLM/ASR/TTS/VAD 等模型管理 |
+| 资源库 | LLM / ASR / TTS 等模型管理 |
 | 知识库 | RAG 文档上传与管理 |
 | 历史记录 | 会话日志查询与回放 |
 | 仪表盘 | 实时数据统计 |
@@ -74,7 +74,7 @@ flowchart TB

 ### 2. API 服务 (FastAPI)

-RESTful API 后端，处理所有管理操作。
+REST API 后端，处理资源管理、持久化配置和历史数据等控制面能力。

 ```mermaid
 flowchart LR
@@ -100,7 +100,7 @@ flowchart LR

 ### 3. 实时交互引擎 (Engine)

-核心组件，处理实时音视频对话。
+处理实时音视频对话、事件流转、模型调用与工具执行。

 ```mermaid
 flowchart TB
@@ -116,7 +116,7 @@ flowchart TB
            TTS[语音合成 TTS]
        end
        
-        subgraph Realtime["实时交互引擎连接"]
+        subgraph Realtime["实时引擎连接"]
            RTOpenAI[OpenAI Realtime]
            RTGemini[Gemini Live]
            RTDoubao[Doubao 实时交互]
@@ -144,9 +144,9 @@ flowchart TB

 | 类别 | 说明 | 可选项 |
 |------|------|--------|
-| **外部服务** | 管线式引擎各环节所依赖的云/本地服务 | OpenAI、SiliconFlow、DashScope、本地模型 |
-| **实时交互引擎** | 实时交互引擎可连接的后端 | OpenAI Realtime、Gemini Live、Doubao 实时交互引擎 |
-| **工具** | 管线式 LLM 与实时交互引擎均可调用 | Webhook、客户端工具、内建工具 |
+| **外部模型服务** | Pipeline 引擎各环节依赖的云端或本地服务 | OpenAI、SiliconFlow、DashScope、本地模型 |
+| **实时模型连接** | Realtime 引擎可直接连接的后端 | OpenAI Realtime、Gemini Live、Doubao 实时交互 |
+| **工具系统** | 由助手或引擎调用的外部执行能力 | Webhook、客户端工具、内建工具 |

 ---

@@ -154,7 +154,7 @@ flowchart TB

 ### 管线式全双工引擎

-管线式引擎包含：**声音活动检测（VAD）**、**语音识别（ASR）**、**回合检测（TD）**、**大语言模型（LLM）**、**语音合成（TTS）**。外部服务可选用 **OpenAI**、**SiliconFlow**、**DashScope**、**本地模型**。LLM 可连接**工具**（Webhook、客户端工具、内建工具）。
+管线式引擎由 **VAD → ASR → TD → LLM → TTS** 组成。每个环节可替换，适合需要精细控制、工具扩展和较高可解释性的场景。

 ```mermaid
 sequenceDiagram
@@ -170,33 +170,28 @@ sequenceDiagram
    C->>E: 音频流 (PCM)
    E->>VAD: 检测语音活动
    VAD-->>E: 有效语音段
-    E->>ASR: 语音转文字
+    E->>ASR: 语音转写
    ASR-->>E: 转写文本
-    E->>TD: 回合边界
-    TD-->>E: 可送 LLM 的输入
+    E->>TD: 判断回合边界
+    TD-->>E: 可送入 LLM 的输入
    E->>LLM: 生成回复
    LLM->>Tools: 可选：调用工具
    Tools-->>LLM: 工具结果
    LLM-->>E: 回复文本 (流式)
-    E->>TTS: 文字转语音
+    E->>TTS: 文本转语音
    TTS-->>E: 音频流
    E->>C: 播放音频
 ```

 **特点：**

- 灵活选择各环节供应商（OpenAI、SiliconFlow、DashScope、本地模型）
- 可独立优化 VAD、ASR、TD、LLM、TTS 每个环节
- LLM 与工具联动（Webhook、客户端工具、内建工具）
- 延迟约 500-1500ms
+- 各环节可单独替换和优化
+- 便于接入知识库、工具、工作流等能力
+- 延迟通常高于端到端实时模型，但可控性更强

-### 实时交互引擎
+### Realtime 引擎

-实时交互引擎可连接**实时交互引擎**，包括 **OpenAI Realtime**、**Gemini Live**、**Doubao 实时交互引擎**等，同样可连接**工具**（Webhook、客户端工具、内建工具）。
-
-### 原生多模态引擎
-
-使用端到端多模态模型（如 GPT-4o Realtime）：
+Realtime 引擎直接连接端到端实时模型，适合追求更低延迟和更自然多模态交互的场景。

 ```mermaid
 sequenceDiagram
@@ -204,17 +199,17 @@ sequenceDiagram
    participant E as 引擎
    participant RT as Realtime Model

-    C->>E: 音频流
-    E->>RT: 音频输入
-    RT-->>E: 音频输出 (流式)
-    E->>C: 播放音频
+    C->>E: 音频/视频/文本输入
+    E->>RT: 实时流输入
+    RT-->>E: 流式文本/音频输出
+    E->>C: 播放或渲染结果
 ```

 **特点：**

- 更低延迟 (< 300ms)
- 更自然的语音交互
- 依赖特定模型供应商
+- 交互链路更短，延迟更低
+- 更依赖具体模型供应商的能力边界
+- 适合强调自然对话和多模态体验的入口

 ---

@@ -234,11 +229,11 @@ sequenceDiagram
    API->>DB: 查询助手
    DB-->>API: 助手数据
    API-->>E: 配置信息
-    
+
    C->>E: session.start
    E-->>C: session.started
    E-->>C: config.resolved
-    
+
    loop 对话循环
        C->>E: 音频帧 (binary)
        E-->>C: input.speech_started
@@ -249,7 +244,7 @@ sequenceDiagram
        E-->>C: 音频帧 (binary)
        E-->>C: output.audio.end
    end
-    
+
    C->>E: session.stop
    E->>API: 保存会话记录
    API->>DB: 存储
@@ -266,19 +261,19 @@ sequenceDiagram

    Note over E: 正在播放 TTS 音频
    E->>C: 音频帧...
-    
+
    C->>E: 用户说话 (VAD 检测)
    E->>E: 触发打断
    E->>TTS: 停止合成
    E-->>C: output.audio.interrupted
-    
+
    Note over E: 处理新的用户输入
    E-->>C: input.speech_started
 ```

 ---

-## 部署架构
+## 部署形态

 ### 开发环境

@@ -299,56 +294,19 @@ flowchart LR

 ## 技术选型

-| 组件 | 技术 | 选型理由 |
-|------|------|---------|
-| **前端框架** | React 18 | 成熟生态，组件化开发 |
-| **状态管理** | Zustand | 轻量级，TypeScript 友好 |
-| **UI 组件** | Tailwind CSS | 原子化 CSS，快速开发 |
-| **后端框架** | FastAPI | 高性能，自动 API 文档 |
-| **WebSocket** | websockets | Python 异步 WebSocket |
-| **ORM** | SQLAlchemy | 功能完善，支持多数据库 |
-| **数据库** | SQLite/PostgreSQL | 开发简单/生产可靠 |
-
---
-
-## 扩展性设计
-
-### 模型适配器模式
-
-```mermaid
-classDiagram
-    class ModelAdapter {
-        <<interface>>
-        +generate(prompt) string
-        +stream(prompt) AsyncIterator
-    }
-    
-    class OpenAIAdapter {
-        +generate(prompt) string
-        +stream(prompt) AsyncIterator
-    }
-    
-    class AzureAdapter {
-        +generate(prompt) string
-        +stream(prompt) AsyncIterator
-    }
-    
-    class LocalAdapter {
-        +generate(prompt) string
-        +stream(prompt) AsyncIterator
-    }
-    
-    ModelAdapter <|-- OpenAIAdapter
-    ModelAdapter <|-- AzureAdapter
-    ModelAdapter <|-- LocalAdapter
-```
-
-通过适配器模式，可以轻松接入新的模型供应商。
+| 组件 | 技术 | 说明 |
+|------|------|------|
+| **前端框架** | React 18 | 管理控制台与调试界面 |
+| **状态管理** | Zustand | 前端轻量状态管理 |
+| **UI 样式** | Tailwind CSS | 快速构建控制台界面 |
+| **后端框架** | FastAPI | 管理接口与配置持久化 |
+| **WebSocket** | websockets | 实时事件与音频流通信 |
+| **数据库** | SQLite / PostgreSQL | 配置与历史数据存储 |

 ---

 ## 相关文档

- [WebSocket 协议](../api-reference/websocket.md) - 详细的协议规范
- [部署概览](../deployment/index.md) - Docker 部署
- [核心概念](../concepts/index.md) - 助手、管线等概念说明
+- [产品概览](index.md) - 产品定位、核心模块与适用场景
+- [引擎架构](../concepts/engines.md) - Pipeline 与 Realtime 的选择指南
+- [WebSocket 协议](../api-reference/websocket.md) - 实时对话事件和消息格式
--- a/docs/content/overview/index.md
+++ b/docs/content/overview/index.md
@@ -1,148 +1,84 @@
-# 产品概览
+# 产品概览

-了解 Realtime Agent Studio 的核心功能和设计理念。
+Realtime Agent Studio (RAS) 是一个通过管理控制台与 API 构建、部署和运营实时多模态助手的开源平台。

 ---

-## 什么是 RAS？
+## 产品定位

-Realtime Agent Studio (RAS) 是一个**开源的实时交互智能体工作平台**，让开发者能够快速构建和部署具备语音对话能力的 AI 助手。
+RAS 面向需要构建实时语音或视频助手的团队，目标不是替代你的业务系统，而是提供一套可组合的助手基础设施：

-### 核心价值
+- **控制台**：让团队快速配置助手、资源库、知识库、工具、工作流与评估策略
+- **API 与实时运行时**：让应用、设备和第三方系统稳定接入实时对话能力
+- **运维与分析能力**：让团队能观察会话效果、排查问题并持续迭代助手质量

-| 价值主张 | 说明 |
-|---------|------|
-| **低代码配置** | 可视化界面配置助手，无需编写复杂代码 |
-| **实时交互** | 毫秒级响应，支持语音打断，自然对话体验 |
-| **开放灵活** | 支持多种模型供应商，自由选择最适合的方案 |
-| **私有部署** | 完全自主可控，数据不出域 |
+如果你把实时助手看作一条完整的产品链路，RAS 负责其中的“构建、接入、运行、观测”四个阶段。

---
+## 核心模块

-## 功能模块
+| 模块 | 负责什么 | 适合谁使用 |
+|------|----------|------------|
+| **助手** | 定义角色、行为、模型、知识、工具和会话策略 | 产品、运营、算法、开发 |
+| **引擎** | 承载实时语音/多模态对话，输出事件流和音频流 | 开发、基础设施 |
+| **资源库** | 管理 LLM、ASR、TTS 等外部能力接入 | 平台管理员、开发 |
+| **知识库 / 工具 / 工作流** | 让助手获得领域知识、外部执行能力和复杂流程控制 | 业务设计者、开发 |
+| **分析与评估** | 记录会话、监控指标、做自动化回归和效果评估 | 运营、QA、开发 |

-```mermaid
-mindmap
-  root((RAS))
-    助手管理
-      创建配置
-      提示词编辑
-      模型选择
-      工具调用
-    资源库
-      LLM 模型
-      ASR 模型
-      TTS 声音
-    知识库
-      文档上传
-      向量检索
-      RAG 问答
-    监控分析
-      会话回放
-      数据统计
-      自动测试
-    部署集成
-      WebSocket API
-      REST API
-      SDK
-```
+## 为什么是“控制台 + API”

-### 助手管理
+RAS 采用“控制台配置 + API 接入”的组合方式，而不是把所有内容都固化在代码里：

-创建和配置智能对话助手：
+- **控制台负责提效**：让非后端角色也能参与提示词、工具、知识、流程的配置与调优
+- **API 负责集成**：让产品团队继续用自己的前端、服务端或设备侧应用承载最终体验
+- **同一套助手配置可复用**：控制台保存的助手定义可以被不同渠道重复接入和评估

- **系统提示词** - 定义助手角色和行为
- **模型配置** - 选择 LLM、ASR、TTS 模型
- **工具调用** - 配置 Webhook 和客户端工具
- **开场白** - 设置首轮对话模式
-
-### 资源库
-
-集中管理各类模型资源：
-
- **语音识别 (ASR)** - 多供应商 ASR 模型管理
- **大语言模型 (LLM)** - OpenAI、Azure、本地模型
- **语音合成 (TTS)** - 多音色声音资源
-
-### 知识库
-
-为助手提供专业知识：
-
- **文档上传** - 支持 PDF、Word、Markdown 等格式
- **向量化索引** - 自动分块和向量化
- **RAG 检索** - 基于语义的知识检索
-
-### 监控分析
-
-全面的数据分析能力：
-
- **会话回放** - 完整链路日志和音频回放
- **实时仪表盘** - 并发数、延迟、错误率统计
- **自动化测试** - 批量测试和效果评估
-
---
-
-## 对比其他方案
-
-| 特性 | RAS | Vapi | Retell | ElevenLabs |
-|------|-----|------|--------|------------|
-| **开源** | :white_check_mark: | :x: | :x: | :x: |
-| **私有部署** | :white_check_mark: | :x: | :x: | :x: |
-| **管线式引擎** | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| **多模态模型** | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
-| **自定义 ASR/TTS** | :white_check_mark: | 有限 | 有限 | :x: |
-| **知识库** | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
-| **工作流编辑** | 开发中 | :white_check_mark: | :x: | :x: |
-| **定价** | 免费 | 按量付费 | 按量付费 | 按量付费 |
-
---
-
-## 适用场景
+## 典型使用方式

 <div class="grid cards" markdown>

-   :telephone_receiver: **智能客服**
+-   :material-headset: **客户服务与运营自动化**

    ---

-    7x24 小时自动接听，处理常见咨询，复杂问题转人工
+    在客服、外呼、预约、售后等场景中接入实时语音助手，并保留人工接管与工具调用能力。

-   :hospital: **医疗问诊**
+-   :material-school-outline: **培训、陪练与问答**

    ---

-    预问诊信息收集，健康咨询，用药提醒
+    用知识库、提示词和流程编排构建可持续优化的教学、培训或辅导助手。

-   :school: **教育培训**
+-   :material-domain: **企业内部助手**

    ---

-    口语练习，知识问答，个性化辅导
+    通过私有部署、内部知识库和业务系统工具，把助手接入内部流程或设备终端。

-   :handshake: **销售助手**
+-   :material-devices: **多端集成**

    ---

-    产品介绍，需求挖掘，预约安排
-
-   :headphones: **语音助手**
-
-    ---
-
-    智能家居控制，日程管理，信息查询
-
-   :robot: **虚拟人**
-
-    ---
-
-    数字人直播，虚拟主播，交互式展示
+    通过 WebSocket API 将同一个助手接入 Web、移动端、坐席工作台或自有硬件设备。

 </div>

---
+## 与其他方案的差异

-## 下一步
+本页是站内唯一保留“产品对比”视角的地方，用于帮助你快速判断 RAS 的定位边界。

- [快速开始](../quickstart/index.md) - 5 分钟创建第一个助手
- [系统架构](architecture.md) - 深入了解技术实现
- [核心概念](../concepts/index.md) - 学习关键概念
+| 特性 | RAS | Vapi | Retell | ElevenLabs Agents |
+|------|-----|------|--------|-------------------|
+| **开源** | :white_check_mark: | :x: | :x: | :x: |
+| **私有部署** | :white_check_mark: | :x: | :x: | :x: |
+| **Pipeline 引擎** | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: |
+| **Realtime / 多模态引擎** | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: |
+| **自定义 ASR / TTS** | :white_check_mark: | 有限 | 有限 | :x: |
+| **知识库与工具扩展** | :white_check_mark: | :white_check_mark: | :white_check_mark: | 有限 |
+| **工作流编排** | 开发中 | :white_check_mark: | :x: | :x: |
+| **数据与链路可观测** | :white_check_mark: | 有限 | 有限 | 有限 |
+
+## 继续阅读
+
+- [系统架构](architecture.md) - 从服务边界、数据流和部署形态理解系统如何组成
+- [核心概念](../concepts/index.md) - 先建立助手、引擎与工作流的心智模型
+- [快速开始](../quickstart/index.md) - 以最短路径创建第一个助手