AlphaAvatar：一个基于 LiveKit 的插件化实时 Omni-Avatar 架构

⚠️ 在开始阅读之前，如果你对 实时 Agent / 数字人 / 多模态系统 / LiveKit 架构 感兴趣，
欢迎先到 GitHub 给项目点一个 ⭐ Star，这是对开源作者最大的支持。

🚀 项目地址（强烈建议先收藏，该项目正在持续更新维护）：
👉 https://github.com/AlphaAvatar/AlphaAvatar

前言

近年来，大模型 Agent、语音助手、数字人等方向发展迅速，但在真实工程实践中，“实时交互 + 长期状态 + 多模态 + 可视化角色” 仍然是一个高度复杂的问题。

常见痛点包括：

  • 实时音视频链路（WebRTC）与 Agent 逻辑强耦合，系统难以维护；
  • 对话“记忆”与“用户画像”缺乏统一接口，往往是零散逻辑；
  • 多模态信息（文本 / 语音 / 人脸）难以在一个系统中整合；
  • 虚拟角色往往只是展示层 Demo，无法与 Agent 状态深度绑定。

AlphaAvatar 是在这一背景下诞生的一个工程化项目，目标是构建一个：

以 LiveKit 为实时通信基础、以插件化能力为核心的 Omni-Avatar 框架。

一、AlphaAvatar 的核心特点

在这里插入图片描述

AlphaAvatar 具有以下几个明确特征：

1. 插件化能力设计（avatar-plugins）

系统中的关键能力均以插件形式提供，包括但不限于：

  • Memory（对话记忆管理）
  • Persona（多模态用户画像）
  • Virtual Character（虚拟角色 / AIRI）
  • Tools：
    • DeepResearch

插件的设计目标是：

  • 对上层提供 统一接口
  • 对下层 封装具体开源实现
  • 允许独立安装、替换与演进

2. Agent pipline与实时链路解耦（avatar-agents + LiveKit）

AlphaAvatar 明确区分：

  • 实时通信层：由 LiveKit 负责音频 / 视频 / DataChannel
  • Agent 执行层：由 avatar-agents 负责 pipeline 与逻辑调度

Agent 不直接管理 WebRTC 细节，而是通过 LiveKit Adapter 与房间事件交互。

3. 面向多模态与长期状态

在这里插入图片描述

通过 Memory 与 Persona 插件，AlphaAvatar 支持：

  • 对话级与 Avatar 级的记忆管理
  • 文本、语音、人脸等多模态信号的 Persona 建模
  • 在实时交互中进行状态匹配与复用

同时，AlphaAvatar 的设计并不局限于当前已实现的 Memory 与 Persona，而是围绕
“长期状态 + 多模态 + 可控行为”逐步扩展插件体系，后续将引入以下能力模块：

  • Reflection（反思模块，Planned）

    • 对交互过程进行自动总结与归纳
    • 构建 Avatar 内部的长期知识片段
    • 为后续决策、规划与行为优化提供依据

  • Planning（规划模块，Planned）

    • 支持多步、跨时间尺度的任务规划
    • 确保 Agent 行为具有顺序性、连续性与可复现性
    • 为复杂任务提供稳定执行路径

  • Behavior（行为控制模块，Planned）

    • 统一管理 AlphaAvatar 的行为逻辑与流程控制
    • 决定何时调用工具、何时写入记忆、何时触发反思
    • 提升系统在真实场景下的可控性与工程可维护性

  • RAG（文档检索模块，Planned）

    • 支持访问用户上传文档或系统生成内容
    • 与 Reflection 模块产出的知识库联动
    • 为复杂知识型问题提供稳定信息来源

这些模块将与 Memory、Persona、Virtual Character、DeepResearch 等现有插件形成互补，
逐步构建一个具备 长期记忆、持续自我优化、可控行为与多模态感知能力 的 Omni-Avatar 系统。

4. 前后端分离的虚拟角色架构

虚拟角色（如 AIRI Live2D）作为独立插件存在：

  • Agent 决策与生成在服务端
  • 角色渲染与表现位于前端
  • 通过 LiveKit 数据通道同步状态

二、整体架构与代码结构

2.1 代码结构概览（简化）

AlphaAvatar/
├── avatar-agents/                 # Agent 运行时与 pipeline
│   ├── core/
│   └── examples/
│       ├── pipeline_openai_airi.yaml
│       └── pipeline_openai_tools.yaml
│
├── avatar-plugins/                # 插件体系
│   ├── avatar-plugins-memory/
│   ├── avatar-plugins-persona/
│   ├── avatar-plugins-character/  # 虚拟角色 / AIRI
│   └── avatar-plugins-deepresearch/
│
├── third_party/
│   └── airi/                      # AIRI Live2D 前端
└── README.md

2.2 初版系统架构图

User

AiriUI

LiveKitRoom

AgentAdapter

AgentCore

LLM

MemoryPlugin

PersonaPlugin

CharacterPlugin

ToolPlugin

Qdrant

LangChain

SpeakerModels

FaceRecognizer

该结构体现了当前 AlphaAvatar 的真实工程状态，而非概念化设计。

三、AlphaAvatar 目前支持【内部】插件（实时更新）

3.1 Memory 插件（alpha-avatar-plugins-memory）

3.1.1 插件定位

Memory 插件用于 在 Avatar 内部统一管理会话记忆，并对接开源记忆与向量存储框架。

其目标并非绑定某一种记忆策略，而是：

  • 提供统一的 Memory 接口
  • 封装存储与检索细节
  • 降低开发者对底层实现的感知
3.1.2 核心特性

在 AlphaAvatar 的设计里，Memory 不只是一种“单一对话记忆”，而是分为三条主线，分别服务不同的实时场景：

  1. Avatar 全局 Memory（Global / Avatar-wide）

    • 用于存储与检索 Avatar 级别的全局记忆（跨用户共享的知识、规则、长期状态）
    • 适合用于“公共知识、系统策略、长期可复用经验”等

  2. Avatar ↔ 单个用户交互 Memory（Per-user Interaction Memory）

    • 用于管理 Avatar 与某个用户之间的历史交互记忆
    • 让 Avatar 在与同一用户多次交互时能够稳定保持上下文一致性（偏好、习惯、历史事实等）

  3. Avatar ↔ 工具调用 Memory（Tool-call Memory）

    • 用于记录工具调用相关上下文与结果（例如 DeepResearch 的检索结果、调用轨迹、置信度线索等）

    • 该类记忆主要服务两类目标：

      • 反思/复盘：后续可用于总结“为什么这样调用工具”“调用是否有效”
      • 提升调用精度：在相似任务中复用历史调用经验，减少无效搜索与重复调用

此外，Memory 插件本身也支持 README 中强调的能力：

  • Real-time Context Updates

    • 记忆可在对话过程中实时写入与刷新

  • 统一接口

    • 对上层 Agent 隐藏具体后端实现

未来规划（Memory）：多用户并行 Memory 存储/维护/更新
AlphaAvatar 后续会强化“一个 Avatar 同时与多个人交互”的场景：
在同一实时系统里，为多个用户并行维护各自的记忆状态，并且能够在全局记忆与个人记忆之间做有控制的融合与更新（更接近真人在多人对话中的状态管理方式）。

3.1.3 支持的开源组件

  • Vector Store

    • Qdrant（默认）

  • Memory Framework

    • LangChain（默认）
3.1.4 安装
pip install alpha-avatar-plugins-memory

3.2 Persona 插件（alpha-avatar-plugins-persona）

3.2.1 插件定位

Persona 插件用于 自动抽取与实时匹配用户的全模态 Persona，支持：

  • 用户画像建模（profiling：语义 + 向量表示）
  • 身份识别（speaker / face）
  • 个性化交互支持

插件通过统一接口封装 profiling、speaker、face 等能力。

3.2.2 核心功能
Automatic Persona Extraction
  • 基于对话历史、行为特征与多模态输入进行实时 profiling
  • Persona 以向量嵌入形式存储，便于相似度搜索
Real-time Persona Matching
  • 实时生成说话人语音向量特征
  • 新输入语音信号实时匹配已有 Persona Profile
  • 支持即时召回用户特征与历史状态

你项目当前强调的 Persona 核心特色（补充）：多用户 Profile + 语音特征的全链路维护
Persona 插件支持同时面对多个用户的场景：

  1. 多用户 Profile 的持续维护与更新

    • 每个用户都有独立的 Profile（向量画像 + 语义画像），可随交互持续演进

  2. 多用户语音特征的抽取、匹配与维护

    • 对每个用户维护 speaker embedding 等语音特征
    • 新的语音输入能够实时匹配到正确的用户 Profile

  3. 面向“多人同时交流”的交互模型

    • 更接近真人在多人对话中：识别“谁在说话”、回忆“这个人是谁”、并维持“每个人各自的上下文与偏好”
3.2.3 支持的模块

  • Vector Store

    • Qdrant（默认）

  • Profiler

    • LangChain（默认）

  • Speaker

    • ERes2NetV2
    • wav2vec2-large-robust-6-ft-age-gender

  • Face Recognizer

    • Face ID（如 InsightFace）
3.2.4 安装
pip install alpha-avatar-plugins-persona

3.3 Virtual Character 插件（alpha-avatar-plugins-character）

3.3.1 插件定位

Virtual Character 插件是一个 模块化虚拟角色中间件，把高质量实时 Avatar 渲染能力引入 AlphaAvatar 的 Agent 生态。
它允许任何 AlphaAvatar 驱动的 AI Agent 去控制虚拟角色的表现层，覆盖：

  • 口型同步（lip-sync）
  • 表情控制（facial expressions）
  • 情绪/状态（emotional states）
  • 与视频生成/渲染同步（synchronized video generation）

该插件本身不把“渲染”塞进后端，而是以插件形式把 Agent 的输出（语音、情绪、表情、动作指令等）规范化后，传递给前端角色框架。

3.3.2 安装
pip install alpha-avatar-plugins-character
3.3.3 当前默认支持的开源虚拟角色框架：AIRI
  • Default：AIRI
  • 提供高质量 Live2D/VRM 实时渲染能力，支持口型、情绪控制与虚拟形象视频生成/渲染。

AIRI 环境安装（示例流程）：

curl https://get.volta.sh | bash

volta install node
volta install pnpm

alphaavatar-airi-install

备注：这部分是“虚拟形象前端依赖”安装，与 Python 侧插件安装是两条链路。

四、AlphaAvatar 目前支持【外部工具】插件（实时更新）

4.1 DeepResearch 插件（alpha-avatar-plugins-deepresearch）

4.1.1 插件定位

DeepResearch/Tools 插件用于把外部工具能力接入 AlphaAvatar，包括但不限于：

  • 联网搜索
  • 信息整合
  • 为 Agent 提供可复用的工具调用接口

当前版本中，外部搜索工具使用的是 Tavily API（作为检索入口）。

4.1.2 Tavily 配置（当前实现）

在环境变量中配置：

export TAVILY_API_KEY=xxx

随后在对应 pipeline（例如 pipeline_openai_tools.yaml）中启用 Tools/DeepResearch 插件即可。

五、安装与运行 AlphaAvatar

5.1 环境准备

uv venv .venv
source .venv/bin/activate

5.2 安装 Agent 主工程

pip install alpha-avatar-agents

或源码安装：

git clone https://github.com/AlphaAvatar/AlphaAvatar.git
cd AlphaAvatar
uv sync --all-packages

5.3 配置环境变量

export LIVEKIT_API_KEY=xxx
export LIVEKIT_API_SECRET=xxx
export LIVEKIT_URL=xxx

export OPENAI_API_KEY=xxx
export QDRANT_URL=xxx
export QDRANT_API_KEY=xxx

# 可选：启用 DeepResearch 能力
export TAVILY_API_KEY=xxx

5.4 启动示例 Pipeline

alphaavatar download-files
alphaavatar dev examples/pipeline_openai_airi.yaml

随后通过 LiveKit Playground 或自定义前端加入对应房间。

六、总结

AlphaAvatar 并非单一聊天机器人项目，而是一个：

  • 面向实时场景
  • 插件化能力组织
  • 支持多模态 Persona 与长期状态
  • 可扩展虚拟角色展示

的 工程级 Omni-Avatar 架构。

对于正在构建实时 Agent、数字人或多模态交互系统的开发者来说，它提供了一套可复用、可演进的基础设施。

# 人工智能 # 语言模型
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

2025大数据技术与应用：从技术重构到产业赋能的深度进化

avatar 2048 AI社区

VMnet1和VMnet8是什么？

当我们安装VMware Workstaition后，在宿主机（物理电脑）上会多出现VMnet1和VWnet8。这两个是两个虚拟网卡，主要作用是让虚拟机可以通过宿主机的网线上网。VMnet1 是 VMware 提供的虚拟交换机，仅支持虚拟机与宿主机、同网段虚拟机之间通信，无法连接外网。VMnet8 是 VMware 提供的虚拟交换机，虚拟机可通过宿主机的网络访问外网，同时宿主机和同网段虚拟机也能与它

avatar 2048 AI社区

深度学习基础（一）

你可以把它们理解为“人工智能（AI）”人工智能 > 机器学习 > 深度学习人工智能（AI）：目标是使计算机能够完成通常需要人类智能才能处理的任务，例如：感知（看、听、说）、推理（逻辑分析）、学习（从经验中进步）、决策（解决问题）等。机器学习（ML）：机器学习是人工智能的一种方法。它涉及到算法和统计模型使用，使得计算机系统能够从数据中‘学习’和改进任务的执行，而不是通过明确的编程来实现。机器学习包括

avatar 2048 AI社区