基于 LiveKit 构建的可学习、可配置、高度插件化的全能型实时交互虚拟助手框架，支持多模态记忆、用户画像与外部工具集成。
项目概述#
AlphaAvatar 是一个 Apache-2.0 开源项目，旨在构建通用虚拟助手。它是一个基于 Python 的 Agent 框架，核心解决如何将实时音视频交互（LiveKit）、大语言模型推理、长期记忆、用户画像以及虚拟形象有机整合，提供具备「自我进化」能力的数字助手解决方案。
核心价值：降低构建具备长期记忆和个性化交互能力的实时语音/视频 AI Agent 的门槛。
适用场景：
- 实时语音/视频虚拟陪伴与助手
- 具备长期记忆的智能客服或教育辅导 Agent
- 多模态交互研究（语音识别、说话人区分、Live2D 形象驱动）
- 集成外部知识库（RAG）与网络深度搜索的智能问答系统
核心能力与插件#
项目采用插件化设计，分为 AlphaAvatar 核心插件与工具插件两大类。
AlphaAvatar 核心插件#
| 插件 | 状态 | 能力说明 |
|---|---|---|
| 🧠 Memory | 已实现 | 自我改进的记忆模块，支持 Assistant–User/Assistant–Tools/Assistant's self-memory 的记忆捕获与检索 |
| 🧬 Persona | 已实现 | 全自动多模态用户画像，支持语音说话人识别、自动用户画像抽取与实时匹配 |
| 😊 Virtual Character | 已实现 | 实时生成的虚拟形象，已集成 AIRI live2d |
| 💡 Reflection | 计划中 | 自我优化器，自动构建内部知识库 |
| 🗺️ Planning | 计划中 | 长期规划能力，使 Agent 在更长时间维度上进行可靠有序的行动规划 |
| 🤖 Behavior | 计划中 | 行为逻辑控制器 |
工具插件#
| 插件 | 状态 | 能力说明 |
|---|---|---|
| 🔍 DeepResearch | 已实现 | 网络接入与深度搜索，集成 Tavily API，支持快速检索/深度搜索/网页转PDF |
| 📖 RAG | 已实现 | 文档知识库访问，集成 RAG Anything，支持基于 DeepResearch 插件页面的查询与索引 |
安装与快速开始#
环境要求#
- Python 3.11+
- 依赖服务：LiveKit Server, OpenAI API Key, Qdrant (云服务或自建), Tavily API Key (可选)
从 PyPI 安装稳定版#
uv venv .my-env --python 3.11
source .my-env/bin/activate
pip install alpha-avatar-agents
从 GitHub 安装最新版#
git clone --recurse-submodules https://github.com/AlphaAvatar/AlphaAvatar.git
cd AlphaAvatar
uv venv .venv --python 3.11
source .venv/bin/activate
uv sync --all-packages
环境变量配置#
export LIVEKIT_API_KEY=<your API Key>
export LIVEKIT_API_SECRET=<your API Secret>
export LIVEKIT_URL=<your LiveKit server URL>
export OPENAI_API_KEY=<your OpenAI API Key>
export QDRANT_URL='https://xxxxxx.us-east.aws.cloud.qdrant.io:6333'
export QDRANT_API_KEY=<your QDRANT API Key>
export TAVILY_API_KEY=<your TAVILY API Key> # Optional
启动开发模式#
alphaavatar download-files
alphaavatar dev examples/pipline_openai_airi.yaml
# 或
alphaavatar dev examples/pipline_openai_tools.yaml
架构设计#
- 核心框架：基于 LiveKit Agents 构建实时交互流
- 模块化设计：
avatar-agents(核心 Agent 逻辑与编排) +avatar-plugins(各类功能插件实现) - 上下文管理器：核心路由组件，将实时交互数据分发至不同插件模型处理
- 数据存储：使用 Qdrant 向量数据库存储 Memory 和 Persona 的 Embedding 数据
- 多模态处理链路：LiveKit 音视频流 → STT → Context Manager (Persona/Memory) → LLM 推理 → Tools (DeepResearch/RAG) → TTS → 音频流 + Live2D 驱动
CLI 命令#
alphaavatar download-files：初始化下载所需资源文件alphaavatar dev <config_path>：以开发模式启动 Agent，加载指定 YAML 配置文件
版本历史#
| 时间 | 版本 | 关键更新 |
|---|---|---|
| 2026-01 | v0.3.1 | ADD tool calls during user-Assistant interactions to the Memory module |
| 2026-01 | v0.3.0 | Support DeepResearch by tavily API |
| 2025-12 | v0.2.0 | Support AIRI live2d-based virtual character display |
| 2025-11 | v0.1.0 | Support automatic memory extraction, automatic user persona extraction and matching |
项目愿景#
Build a universal assistant capable of recognizing users through multimodal streaming input. It should possess self-memory, autonomous reflection, and iterative self-evolution for real-time interaction. The assistant will seamlessly integrate with mainstream external tools to solve practical problems efficiently.