# 核心概念

本章节介绍 Realtime Agent Studio 中的核心概念，帮助你更好地理解和使用平台。

---

## 概念总览

```mermaid
flowchart TB
    subgraph Platform["RAS 平台"]
        Assistant[助手 Assistant]
        
        subgraph Resources["资源库"]
            LLM[LLM 模型]
            ASR[ASR 模型]
            TTS[TTS 声音]
            KB[知识库]
        end
        
        subgraph Engine["交互引擎"]
            Pipeline[管线式引擎]
            Multimodal[多模态引擎]
        end
        
        Session[会话 Session]
    end

    Assistant --> LLM
    Assistant --> ASR
    Assistant --> TTS
    Assistant --> KB
    Assistant --> Engine
    Engine --> Session
```

---

## 助手 (Assistant)

**助手**是 RAS 的核心实体，代表一个可对话的 AI 智能体。

### 助手配置

每个助手包含以下配置：

| 配置项 | 说明 |
|-------|------|
| **名称** | 助手的显示名称 |
| **系统提示词** | 定义助手角色、行为、限制 |
| **LLM 模型** | 选择用于生成回复的大语言模型 |
| **ASR 模型** | 选择用于语音识别的模型 |
| **TTS 声音** | 选择用于语音合成的音色 |
| **工具** | 配置助手可调用的外部工具 |
| **知识库** | 关联的知识库（用于 RAG） |

### 助手生命周期

```mermaid
stateDiagram-v2
    [*] --> Draft: 创建
    Draft --> Draft: 编辑配置
    Draft --> Published: 发布
    Published --> Draft: 取消发布
    Published --> Published: 更新配置
    Published --> [*]: 删除
```

---

## 会话 (Session)

**会话**代表一次完整的对话交互，从用户连接到断开。

### 会话状态

```mermaid
stateDiagram-v2
    [*] --> Connecting: WebSocket 连接
    Connecting --> Started: session.started
    Started --> Active: 对话中
    Active --> Active: 多轮对话
    Active --> Stopped: session.stop
    Stopped --> [*]: 连接关闭
```

### 会话数据

每个会话记录包含：

- **基本信息** - ID、时长、时间戳
- **音频数据** - 用户和助手的音频记录
- **转写文本** - ASR 识别结果
- **LLM 交互** - 输入输出和工具调用
- **元数据** - 渠道、来源、自定义变量

---

## 管线式引擎 vs 多模态引擎

RAS 支持两种引擎架构，适用于不同场景。

### 管线式引擎 (Pipeline)

将语音交互拆分为三个独立环节：

```
用户语音 → [ASR] → 文本 → [LLM] → 回复 → [TTS] → 助手语音
```

**优点：**

- 灵活选择各环节供应商
- 可独立优化每个环节
- 成本可控

**缺点：**

- 延迟较高（累加延迟）
- 需要协调多个服务

### 多模态引擎 (Multimodal)

使用端到端模型直接处理：

```
用户语音 → [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: 处理新输入
```

---

## 工具调用 (Tool Calling)

助手可以通过**工具**扩展能力，访问外部系统或执行特定操作。

### 工具类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **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 接口详情