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) - 实时对话事件和消息格式