摘要
AgentOS 2 Live 是一个使用 OpenAI Realtime API（GPT-4o Realtime）构建的高性能、低延迟实时语音助手平台，支持端到端的语音到语音交互，集成语音活动检测（VAD）、模块化工具调用系统，并提供机器人面部动画UI与硬件控制能力。通过 monorepo 架构（npm workspaces），同时包含 React 前端、Node.js 后端、共享类型协议以及针对 OrionStar 机器人的 Android WebView 桥接项目，适合开发低延迟语音交互应用，如人脸登记和3C产品导购场景。

实时语音交互如今已成为AI助手的重要形态。很多人会问：怎样才能用最少的延迟实现“听-想-说”全链路？AgentOS 2 Live 提供了一个现成的、可快速上手的解决方案。下面我们从架构到部署，一步步拆解这个项目到底是怎么做到的，以及你能怎样基于它开发自己的语音助手。

为什么实时语音助手需要特别关注延迟？

传统的语音助手通常走三步：语音转文字 → 大模型处理文字 → 文字转语音。这种流水线虽然成熟，但每一步都会引入几十到几百毫秒的延迟，累积下来用户会明显感觉到“卡顿”。

OpenAI Realtime API 改变了游戏规则。它直接在多模态模型（gpt-4o-realtime-preview）内部处理音频输入和输出，不依赖中间的文字转录环节。模型能听到语调、情绪、停顿，直接以语音形式思考并回复。这就是为什么 AgentOS 2 Live 把“低延迟”作为核心卖点——它充分利用了这个原生语音到语音的能力。

项目整体架构一览

AgentOS 2 Live 采用 monorepo 结构，使用 npm workspaces 管理多个包。这种方式让前端、后端、共享类型保持一致性，避免版本冲突。

目录 主要职责 核心技术栈
client/ 浏览器端界面与音频处理 React + TypeScript + Tailwind CSS + Web Audio API + VAD + Opus 编解码
server/ WebSocket 服务与 OpenAI 协调 Node.js + TypeScript + Express + WebSocket
shared/ 前后端共享的类型定义与通信协议 TypeScript 类型与协议定义
e2e_android/ OrionStar 机器人硬件桥接 Android WebView + Kotlin + RobotService SDK

前后端通过统一的 WebSocket 协议通信，协议本身也在 shared/ 中定义，保证类型安全。这一点对中大型团队尤其友好——改动一个接口，前后端都能立刻感知。

核心技术亮点拆解

1. 超低延迟语音交互

整个系统依赖 OpenAI Realtime API 的 speech-to-speech 能力。音频从麦克风采集后，经过 Opus 编码，通过 WebSocket 实时推送到后端，后端几乎不做额外处理，直接转发给 OpenAI，模型直接返回语音流。

客户端再把收到的音频流解码播放。中间省去了 ASR（自动语音识别）和 TTS（文本转语音）两个独立模型的往返时间。

2. 内置语音活动检测（VAD）

VAD 是实时语音系统的关键。没有 VAD，用户说话停顿时系统也会持续发送静音数据，既浪费带宽又增加延迟。

AgentOS 2 Live 在前端集成了 VAD 模块（通过 postinstall 脚本自动拷贝必要的资产到 public 目录）。一旦检测到用户停止说话，SDK 就会自动结束输入，触发模型生成回复，大幅降低交互往返时间。

3. 机器人面部动画UI

client 目录下有一个很实用的功能：实时机器人脸。它会根据当前状态（用户说话、AI 说话、思考中、空闲）切换不同的表情和口型动画。

这种视觉反馈能显著提升用户体验，尤其在机器人实体上使用时，能让交互更像“和一个人对话”而不是对着机器说话。

4. 两个内置场景

项目直接提供了两个典型场景，开箱即用：

  • Face Register：人脸登记与身份识别场景。适合需要实名或会员识别的业务。
  • Advice 3C：3C数码产品导购场景。AI 可以根据用户描述推荐手机、电脑、耳机等产品。

这两个场景证明了系统在垂直领域的可落地性。

5. OrionStar 机器人硬件控制能力

最独特的部分是 e2e_android/ 目录。这是一个 Android WebView 项目，专门为 OrionStar 机器人设计。

通过 RobotService SDK（需自行放入 libs 目录的 jar 包），Web 页面可以调用机器人的物理能力：

  • 头部转动
  • 底盘导航
  • 传感器读取
  • 其他硬件指令

这意味着你可以用 React 页面直接控制真机，实现“语音+肢体动作”的完整机器人交互。

手把手：本地开发与运行

准备工作

  • Node.js ≥ v18
  • npm ≥ v9
  • 一个有 Realtime API 权限的 OpenAI Key（gpt-4o-realtime-preview 模型）

配置 .env 文件

在项目根目录创建 .env：

OPENAI_API_KEY=sk-你的密钥
PORT=8081
USE_SSL=false

USE_SSL 如果设为 true，需要自行准备 HTTPS 证书和域名，否则 WebSocket 会用 wss:// 协议。

安装依赖

npm install

这一步会自动触发 postinstall，把 VAD 相关文件拷贝到 client/public 目录。

开发模式启动

npm run dev
  • 前端：http://localhost:3000
  • 后端：http://localhost:8081

打开浏览器访问 3000 端口，就能看到机器人脸界面并开始语音对话。

生产部署

先构建：

npm run build

然后启动服务：

node server/dist/index.js

server 会同时提供静态文件（打包后的 React）和 WebSocket 服务，一机搞定。

如何在 OrionStar 机器人上运行

准备

  • Android Studio
  • 从机器人系统获取 robotservice_xx.jar，放入 e2e_android/app/libs/

构建与安装

  1. 用 Android Studio 打开 e2e_android 文件夹
  2. Gradle 同步
  3. 用 USB 连接机器人（确保 ADB 已开启）
  4. 点击 Run 安装
  5. 首次启动授予相机、麦克风等权限

默认加载 http://localhost:3000。如果你的 server 部署在其他地址，修改 MainActivity.kt 中的 DEFAULT_URL，或者通过 Intent 传入。

AgentSDK：最简单的接入方式

项目提供了一个封装良好的 AgentSDK，使用起来非常直观：

import { AgentSDK } from './sdk';

const agent = new AgentSDK({
  modelType: 'openai',
  systemPrompt: '你是一个友好的3C产品导购。',
  voice: 'alloy',
  tools: [
    {
      name: 'get_weather',
      description: '查询某地当前天气',
      parameters: {
        type: 'object',
        properties: { location: { type: 'string' } }
      }
    }
  ],
});

agent.on('ready', () => console.log('助手已就绪'));
agent.on('text_output', ({ text }) => console.log('AI 说：', text));
agent.on('tool_call', (toolCall) => {
  console.log('需要执行工具：', toolCall.name);
  // 在这里实现工具逻辑，例如调用天气API
});

await agent.initialize();
agent.connect();

通过监听事件，你可以轻松拿到文本输出、工具调用请求，并实现自己的业务逻辑。

常见问题 FAQ

Q1：一定要用 OpenAI 的 Realtime API 吗？能换其他模型吗？
目前项目明确基于 OpenAI Realtime API 构建，modelType 只支持 ‘openai’。但由于通信协议在 shared 中定义清晰，理论上可以扩展支持其他兼容 WebSocket 的实时模型。

Q2：延迟大概多少？
官方没有给出具体数值，但得益于 speech-to-speech 架构和前端 VAD，通常在安静环境下首句回复延迟可控制在 800–1500ms 以内（包含网络往返）。

Q3：机器人面部动画是怎么实现的？
通过 React 组件实时监听当前对话状态（用户说话、AI 说话、思考、空闲），切换不同的 SVG 或 Lottie 动画。代码在 client 目录的 UI 组件中。

Q4：我想自己加新场景，应该怎么做？
最简单的方式是修改 systemPrompt，或者在后端维护多 session，根据用户意图动态切换 prompt。工具调用机制也支持扩展复杂业务流程。

Q5：商用需要注意什么？
README 中明确标注：本项目仅用于演示与测试，商用时必须遵守 OpenAI 使用政策，特别是语音合成的披露要求（需告知用户声音为 AI 生成）。

总结：适合哪些开发者？

如果你正在寻找一个现成的、可快速落地的实时语音助手框架，尤其希望：

  • 直接用 OpenAI Realtime API
  • 需要前端机器人动画
  • 想控制实体机器人（如 OrionStar）
  • 追求低延迟语音交互

那么 AgentOS 2 Live 是一个非常值得 fork 和二次开发的起点。它已经帮你解决了最麻烦的几件事：音频编解码、VAD、前后端协议一致性、机器人硬件桥接。

从克隆仓库到本地跑通对话，通常不到 30 分钟。剩下的就是根据你的业务场景，调整 prompt、增加工具、优化动画表现了。

希望这篇文章让你对 AgentOS 2 Live 有更清晰的认识。如果你已经上手，欢迎在评论区分享你的使用体验或遇到的问题，我们一起把这个实时语音框架玩得更深入。