AI-VideoAssistant/docs/content/concepts/index.md

核心概念

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

---

概念总览

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

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

---

助手 (Assistant)

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

助手配置

每个助手包含以下配置：

配置项	说明
名称	助手的显示名称
指令配置	使用提示词指令定义助手角色、行为、限制
语音设置	包括语音识别模型，语音合成模型
交互设置	包括用户打断机器人的灵敏度，检测用户语句结束的灵敏度
工具配置	配置助手可调用的外部工具
知识配置	关联的知识库（用于 RAG）
Webhooks	用于订阅助手的活动

---

会话 (Session)

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

会话状态

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 + 语义结合，减少误触发

打断流程

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	查询订单、预约日程
客户端工具	由客户端执行的操作	获取客户端地理位置、请求用户同意、打开客户端相机
内建工具	平台提供的工具	代码执行、计算器

工具调用流程

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（检索增强生成）。

工作原理

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 传入：

{
  "type": "session.start",
  "metadata": {
    "dynamicVariables": {
      "company_name": "ABC 公司",
      "customer_name": "张三",
      "tier": "VIP"
    }
  }
}

---

下一步

• 快速开始 - 创建第一个助手
• 助手配置 - 详细配置说明
• WebSocket 协议 - API 接口详情