![图片[1]-【阿里开源】Python对话式数字人-Open Avatar Chat - 盘古CG网-盘古CG网](http://pangucg.com/wp-content/uploads/2025/05/微信截图_20250522190324.jpg)
演示地址:Open Avatar Chat – a Hugging Face Space by HumanAIGC-Engineering-Team
一种模块化的交互式数字人机对话实现,可在单台 PC 上运行全部功能。
🔥 核心亮点
- 低延迟数字人实时对话:平均响应延迟约为 2.2 秒。
- 多模态语言模型:支持文本、音频、视频等多模态语言模型。
- 模块化设计:采用模块化设计,允许灵活的组件更换,实现不同的功能组合。
📢 新闻
更改日志
- [2025.04.18] ⭐️⭐️⭐️ 0.3.0 版本已发布:
- [2025.04.14] ⭐️⭐️⭐️ 0.2.2 版本发布:
- 100 个新头像发布,请访问 LiteAvatarGallery
- 运行 LiteAvatar 默认使用 GPU
- [2025.04.07] ⭐️⭐️⭐️ 0.2.1 版本发布:
- 添加了对历史记录的支持
- 支持文本输入
- 启动时已删除相机要求
- 优化的模块化加载方法
- [2025.02.20] ⭐️⭐️⭐️ 已发布 0.1.0 版本:
- 模块化实时交互式数字人
- 支持将 MiniCPM-o 作为具有云 API 选项的多模态语言模型
待办事项列表
- 预设数字人体模型达到 100 个
- 集成 LAM:一个开源项目,能够在几秒钟内从单个图像创建超逼真的 3D 数字人
- 集成 Qwen2.5-Omni
演示
在线试用
我们在 ModelScope 上部署了一个 demo 服务,并且 🤗 拥抱脸。音频部分是使用 实现的。现在,您可以在 和 之间切换。请随意尝试。SenseVoice + Qwen-VL + CosyVoice
LiteAvatar
LAM
演示视频
📖 内容
概述
介绍
Open Avatar Chat 是一种模块化的交互式数字人类对话实现,可以在单台 PC 上运行全部功能。它目前支持将 MiniCPM-o 作为多模态语言模型,或使用基于云的 API 来取代传统的 ASR + LLM + TTS 设置。这两种模式的架构如下图所示。有关更多预设模式,请参见下文。
要求
- Python 版本 >=3.10、<3.12
- 支持 CUDA 的 GPU。NVIDIA 驱动程序支持的 CUDA 版本需要为 >= 12.4。
- 未量化的多模态语言模型 MiniCPM-o 需要超过 20GB 的 VRAM。
- 数字人组件可以使用 GPU/CPU 执行推理。测试设备是 i9-13980HX CPU,可实现高达 30 FPS 的 CPU 推理。
提示
使用语言模型的 int4 量化版本可以在 VRAM 小于 10GB 的显卡上运行,但量化可能会影响性能。
用云 API 代替 MiniCPM-o 来实现典型的 ASR + LLM + TTS 功能,可以大大降低配置要求。有关详细信息,请参阅 ASR + LLM + TTS 模式。
性能
在我们的测试中,使用配备 i9-13900KF 处理器和 Nvidia RTX 4090 显卡的 PC,我们记录了响应延迟。十次测试后,平均延迟约为 2.2 秒。延迟时间是从用户语音结束到数字人语音开始的间隔,包括 RTC 双向数据传输时间、VAD(Voice Activity Detection)停止延迟以及整个过程的计算时间。
组件依赖关系
类型 | 开源项目 | GitHub 链接 | 模型链接 |
---|---|---|---|
RTC (音视频) | HumanAIGC-工程/gradio-webrtc | ||
VAD系列 | Snakers4/Silero-VAD | ||
法学硕士 | OpenBMB/MiniCPM-o | 🤗 | |
LLM-int4 | OpenBMB/MiniCPM-o | 🤗 | |
化身 | HumanAIGC/lite-头像 | ||
TTS | FunAudioLLM/CosyVoice | ||
化身 | AIGC3D/LAM_Audio2Expression | 🤗 | |
脸书/WAV2VEC2-BASE-960H | 🤗 |
预设模式
CONFIG 名称 | ASR | 法学硕士 | TTS | 化身 |
---|---|---|---|---|
chat_with_gs.yaml | 商汤语音 | 应用程序接口 | 应用程序接口 | 议员 |
chat_with_minicpm.yaml | MiniCPM-o | MiniCPM-o | MiniCPM-o | lite-头像 |
chat_with_openai_compatible.yaml | 商汤语音 | 应用程序接口 | CosyVoice (舒适语音) | lite-头像 |
chat_with_openai_compatible_bailian_cosyvoice.yaml | 商汤语音 | 应用程序接口 | 应用程序接口 | lite-头像 |
chat_with_openai_compatible_edge_tts.yaml | 商汤语音 | 应用程序接口 | Edgetts | lite-头像 |
🚀 开始使用
在安装部署相应模式之前,请参考相关模块的安装方法和 可选部署。
选择配置
OpenAvatarChat 的功能将遵循启动期间指定的配置。我们在 config 文件夹下提供了几个示例配置文件。
chat_with_gs.yaml
此配置使用 LAM 生成的高斯展开资产作为客户端渲染的头像。使用来自百联平台的基于 api 的 openai 兼容 llm 和 tts,只有 vad 和 asr 处理程序在本地运行,因此这是最轻量级的配置选择,它支持单个服务上的多个连接。
使用的处理程序
类型 | 处理器 | 安装 Notes |
---|---|---|
客户 | 客户端/h5_rendering_client/cllient_handler_lam | LAM 客户端渲染处理程序 |
VAD系列 | vad/silerovad/vad_handler/silero | |
ASR | ASR/SenseVoice/asr_handler_sensevoice | |
法学硕士 | llm/openai_compatible/llm_handler/llm_handler_openai_compatible | OpenAI 兼容的 LLM 处理程序 |
TTS | tts/bailian_tts/tts_handler_cosyvoice_bailian | 百联 Cosy语音处理器 |
化身 | 头像/lam/avatar_handler_lam_audio2expression | LAM Avatar 驱动程序处理程序 |
chat_with_minicpm.yaml
使用 MiniCPM-o-2.6 作为 audio2audio 聊天模型,它需要足够的 VRAM 和 GPU 计算能力。
使用的处理程序
类型 | 处理器 | 安装 Notes |
---|---|---|
客户 | 客户端/rtc_client/client_handler_rtc | 服务端渲染 RTC 客户端处理程序 |
VAD系列 | vad/silerovad/vad_handler/silero | |
法学硕士 | 法学硕士/MiniCPM/llm_handler_minicpm | MiniCPM Omni Speech2Speech 处理程序 |
化身 | 头像/lite头像/avatar_handler_liteavatar | LiteAvatar 头像处理程序 |
chat_with_openai_compatible.yaml
此配置使用兼容 openai 的 api 作为 llm provider,使用 CosyVoice 作为本地 tts 模型。
使用的处理程序
类型 | 处理器 | 安装 Notes |
---|---|---|
客户 | 客户端/rtc_client/client_handler_rtc | 服务端渲染 RTC 客户端处理程序 |
VAD系列 | vad/silerovad/vad_handler/silero | |
ASR | ASR/SenseVoice/asr_handler_sensevoice | |
法学硕士 | llm/openai_compatible/llm_handler/llm_handler_openai_compatible | OpenAI 兼容的 LLM 处理程序 |
TTS | tts/cosyvoice/tts_handler_cosyvoice | CosyVoice 本地推理处理程序 |
化身 | 头像/lite头像/avatar_handler_liteavatar | LiteAvatar 头像处理程序 |
chat_with_openai_compatible_bailian_cosyvoice.yaml
LLM 和 TTS 都是由 API 提供的,它是 LiteAvatar 最轻量级的配置。
使用的处理程序
类型 | 处理器 | 安装 Notes |
---|---|---|
客户 | 客户端/rtc_client/client_handler_rtc | 服务端渲染 RTC 客户端处理程序 |
VAD系列 | vad/silerovad/vad_handler/silero | |
ASR | ASR/SenseVoice/asr_handler_sensevoice | |
法学硕士 | llm/openai_compatible/llm_handler/llm_handler_openai_compatible | OpenAI 兼容的 LLM 处理程序 |
TTS | tts/bailian_tts/tts_handler_cosyvoice_bailian | 百联 Cosy语音处理器 |
化身 | 头像/lite头像/avatar_handler_liteavatar | LiteAvatar 头像处理程序 |
chat_with_openai_compatible_edge_tts.yaml
此配置使用 Edge TTS,不需要百联的 API Key。
类型 | 处理器 | 安装 Notes |
---|---|---|
客户 | 客户端/rtc_client/client_handler_rtc | 服务端渲染 RTC 客户端处理程序 |
VAD系列 | vad/silerovad/vad_handler/silero | |
ASR | ASR/SenseVoice/asr_handler_sensevoice | |
法学硕士 | llm/openai_compatible/llm_handler/llm_handler_openai_compatible | OpenAI 兼容的 LLM 处理程序 |
TTS | tts/edgets/tts_handler_edgetts | Edge TTS 处理程序 |
化身 | 头像/lite头像/avatar_handler_liteavatar | LiteAvatar 头像处理程序 |
本地执行
重要
本项目中的子模块和依赖模型需要 git LFS 模块。请确保已安装 LFS 功能:
sudo apt install git-lfs git lfs install
此工程通过 git submodules 引用第三方库,因此您需要在运行前更新 submodules:
git submodule update --init --recursive
如果您遇到任何问题,请随时向我们提交问题。
本项目依赖 CUDA,请确保本地 NVIDIA 驱动支持的 CUDA 版本为 >= 12.4
UV 安装
建议安装 UV,使用 UV 进行本地环境管理。
官方独立安装程序
# On Windows. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # On macOS and Linux. curl -LsSf https://astral.sh/uv/install.sh | shPyPI 安装
# With pip. pip install uv # Or pipx. pipx install uv
依赖项安装
安装所有依赖项
uv sync --all-packages
仅安装所需模式的依赖项
uv run install.py --uv --config <absolute path to config file>.yaml
跑
uv run src/demo.py --config <absolute path to config file>.yaml
Docker 执行
容器化执行:容器依赖于 NVIDIA 的容器环境。准备好支持 GPU 的 Docker 环境后,执行以下命令完成镜像的构建和部署。
./build_and_run.sh --config <absolute path to config file>.yaml
处理程序依赖项安装说明
服务端渲染 RTC 客户端处理程序
目前没有额外的依赖项或基本配置。
LAM 客户端渲染处理程序
客户端渲染处理器源自 Server Rendering RTC Client Handler。它支持多连接。客户端 avatar asset 可以在 handler config 中选择。
选择 Avatar 资产
LAM 头像资产可以由 LAM 项目生成(现成的生成管道尚未准备好。保持兴奋!OpenAvatarChat 提供了 4 个示例资源。它们可以在下面找到 src/handlers/client/h5_rendering_client/lam_samples 的所选资产应设置为处理程序配置中的 asset_path 字段。您可以使用其中一个示例资产,即 LAM 创建的自有资产,请参考以下处理程序配置示例:
LamClient: module: client/h5_rendering_client/client_handler_lam asset_path: "lam_samples/barbara.zip" concurrent_limit: 5
OpenAI 兼容的 LLM 处理程序
本地 llm 处理程序具有相对较高的启动要求。如果您已经有可用的 LLM api_key,您可以通过这种方式开始体验交互式数字人。 修改相应的配置,如 config/chat_with_openai_compatible.yaml 中LLM_Bailian配置。代码中的 invocation 方法使用标准的 OpenAI 方法,理论上应该与类似的设置兼容。
LLM_Bailian: model_name: "qwen-plus" system_prompt: "You are an AI digital human. Respond to my questions briefly and insert punctuation where appropriate." api_url: 'https://dashscope.aliyuncs.com/compatible-mode/v1' api_key: 'yourapikey' # default=os.getenv("DASHSCOPE_API_KEY")
提示
OpenAvatarChat 将获取当前工作目录中的 .env 文件,它可以用来设置环境变量,而无需更改配置文件。
注意
- 内部代码调用方法
client = OpenAI( api_key= self.api_key, base_url=self.api_url, ) completion = client.chat.completions.create( model=self.model_name, messages=[ self.system_prompt, {'role': 'user', 'content': chat_text} ], stream=True )
- 默认的 LLM API 是百联 api_url。
MiniCPM Omni Speech2Speech 处理程序
使用的型号
在本项目中,MiniCPM-o-2.6 可以用作多模态语言模型,为数字人类提供对话能力。用户可以根据需要从 Huggingface 或 Modelscope 下载相关模型。建议直接下载模型到 /models/。默认配置指向此路径,因此如果模型放置在其他位置,则需要修改配置文件。scripts 目录下有对应的模型下载脚本,可以在 Linux 环境中使用。请在项目根目录下运行脚本:
scripts/download_MiniCPM-o_2.6.sh
scripts/download_MiniCPM-o_2.6-int4.sh
注意
全精度版本和 int4 量化版本均受支持。但是,int4 版本需要特殊版本的 AutoGPTQ 才能加载,请参考模型卡。
百联 Cosy语音处理器
百联提供了 CosyVoice API,可以作为本地 tts 推理处理器的替代方案。虽然它需要一个百联 API Key,但它减少了相当数量的系统要求。 示例处理程序配置如下所示:
CosyVoice:
module: tts/bailian_tts/tts_handler_cosyvoice_bailian
voice: "longxiaocheng"
model_name: "cosyvoice-v1"
api_key: 'yourapikey' # default=os.getenv("DASHSCOPE_API_KEY")
与 OpenAI Compatible LLM Handler 相同,api_key可以在处理程序配置中或从环境变量中设置。
提示
OpenAvatarChat 将获取当前工作目录中的 .env 文件,它可以用来设置环境变量,而无需更改配置文件。
CosyVoice 本地推理处理程序
警告
由于 Windows 上通过 PyPI 获取 pynini 包依赖项时,无法使用不支持的参数编译的问题,CosyVoice 目前推荐的解决方法是使用 Conda 在 Windows 上安装来自 conda-forge 的预编译 pynini 包。
在 Windows 上本地使用 CosyVoice 作为 TTS 时,需要结合 Conda 和 UV 进行安装。具体的依赖安装和执行过程如下:
- 安装 Anaconda 或 Miniconda
conda create -n openavatarchat python=3.10 conda activate openavatarchat conda install -c conda-forge pynini==2.1.6
- 将 UV 索引的环境变量设置为 Conda 环境
# cmd set VIRTUAL_ENV=%CONDA_PREFIX% # powershell $env:VIRTUAL_ENV=$env:CONDA_PREFIX
- 在安装依赖项并使用 UV 运行时,添加参数以优先使用已激活的虚拟环境
--active
# Install dependencies uv sync --active --all-packages # Install required dependencies only uv run --active install.py --uv --config config/chat_with_openai_compatible.yaml # Run CosyVoice uv run --active src/demo.py --config config/chat_with_openai_compatible.yaml
注意
- TTS 默认为 CosyVoice 的 + 您可以将其修改为其他模型并使用 和 用于语音克隆。
iic/CosyVoice-300M-SFT
Chinese Female
ref_audio_path
ref_audio_text
Edge TTS 处理程序
OpenAvatarChat 集成了 Microsoft Edge TTS,它是云端和 api key 的推理并不重要,示例处理程序配置如下所示:
Edge_TTS: module: tts/edgetts/tts_handler_edgetts voice: "zh-CN-XiaoxiaoNeural"
LiteAvatar 头像处理程序
LiteAvatar 致力于提供 2D 头像功能。目前,modelscope 项目 LiteAvatarGallery 上提供了 100 个头像资产,详情请参考此项目。 LiteAvatar 可以在 CPU 和 GPU 上运行。如果使用其他 GPU 密集型处理程序,让 liteavatar 在 cpu 上运行可能是一个不错的选择。 示例处理程序配置如下所示:
LiteAvatar: module: avatar/liteavatar/avatar_handler_liteavatar avatar_name: 20250408/sample_data fps: 25 use_gpu: true
LAM Avatar 驱动程序处理程序
使用的型号
- 脸书/WAV2VEC2-BASE-960H 🤗
- 从 huggingface 下载,确保 lfs 安装正确,在项目根目录下运行以下 cmd:
git clone --depth 1 https://huggingface.co/facebook/wav2vec2-base-960h ./models/wav2vec2-base-960h
- 从 modelscope 下载,确保 lfs 安装正确,在项目根目录下运行以下 cmd:
git clone --depth 1 https://www.modelscope.cn/AI-ModelScope/wav2vec2-base-960h.git ./models/wav2vec2-base-960h
- 🤗 LAM_audio2exp
- 从 huggingface 中下载,确保 lfs 安装正确,在项目根目录下运行以下 cmds:
wget https://huggingface.co/3DAIGC/LAM_audio2exp/resolve/main/LAM_audio2exp_streaming.tar -P ./models/LAM_audio2exp/ tar -xzvf ./models/LAM_audio2exp/LAM_audio2exp_streaming.tar -C ./models/LAM_audio2exp && rm ./models/LAM_audio2exp/LAM_audio2exp_streaming.tar
- 如果 huggingface 可以访问,也可以从 oss 下载,在项目根目录下运行以下 cmds:
wget https://virutalbuy-public.oss-cn-hangzhou.aliyuncs.com/share/aigc3d/data/LAM/LAM_audio2exp_streaming.tar -P ./models/LAM_audio2exp/ tar -xzvf ./models/LAM_audio2exp/LAM_audio2exp_streaming.tar -C ./models/LAM_audio2exp && rm ./models/LAM_audio2exp/LAM_audio2exp_streaming.tar
可选部署
准备 ssl 证书
由于我们使用 rtc 来流式传输视频和音频,如果没有从 localhost 链接,则需要 ssl 证书,用户可以将现有的证书放入 ssl_certs 文件夹中并在配置文件中配置它们,或者使用提供的脚本创建一个新的自签名证书。在项目根目录下运行脚本,将结果放到适当的位置。
scripts/create_ssl_certs.sh
TURN 服务器
如果点击“开始对话”后遇到持续等待状态,可能是由于您的部署环境(例如在云机上部署)的 NAT 遍历问题。在这种情况下,需要数据中继。在 Linux 系统上,您可以使用 coturn 设置 TURN 服务器。按照以下步骤在同一台计算机上安装、启动和配置 coturn:
- 运行安装脚本
$ chmod 777 scripts/setup_coturn.sh # scripts/setup_coturn.sh
- 修改配置文件,添加以下配置并启动服务
default: chat_engine: handler_configs: RtcClient: # If using Lam, this config should be LamClient turn_config: turn_provider: "turn_server" urls: ["turn:your-turn-server.com:3478", "turns:your-turn-server.com:5349"] username: "your-username" credential: "your-credential"
- 确保防火墙(包括云机安全组策略)开放 coturn 需要的端口
配置
默认参数将从 <project_root>/configs/chat_with_minicpm.yaml 加载配置。可以通过添加 –config 参数从其他文件加载 Config。
uv run src/demo.py --config <absolute-path-to-the-config>.yaml
此处列出了可配置的参数:
参数 | 违约 | 描述 |
---|---|---|
log.log_level | 信息 | 演示的日志级别。 |
service.host (服务主机) | 0.0.0.0 | 启动 gradio 应用程序的地址。 |
service.port 服务 | 8282 | 用于启动 gradio 应用程序的端口。 |
service.cert_file | ssl_certs/localhost.crt | ssl 的证书文件,如果同时找到 cert_file 和 cert_key,则启用 https。 |
service.cert_key | ssl_certs/localhost.key | ssl 的证书文件,如果同时找到 cert_file 和 cert_key,则启用 https。 |
chat_engine.model_root | 模型 | 查找模型的路径。 |
chat_engine.handler_configs | 不适用 | 处理程序配置由每个处理程序提供。 |
当前实现的处理程序提供以下配置:
- VAD系列
参数 | 违约 | 描述 |
---|---|---|
SileraVad.speaking_threshold | 0.5 | 阈值,用于确定用户是开始说话还是结束说话。 |
SileraVad.start_delay | 2048 | 说话概率应高于阈值,才能在音频样本中被识别为说话开始,单位。 |
SileraVad.end_delay | 2048 | 说话概率应低于阈值,才能在音频样本中被识别为说话结束的单位。 |
SileraVad.buffer_look_back | 1024 | 对于高阈值,声部的最开始部分可能会被削波,使用它来补偿,单位在音频样本中。 |
SileraVad.speech_padding | 512 | 此长度的静音将在音频样本的开始和结束单位上填充。 |
- 法学硕士
参数 | 违约 | 描述 |
---|---|---|
S2S_MiniCPM.model_name | MiniCPM-o-2_6 | 要加载的模型可以是 “MiniCPM-o-2_6” 或 “MiniCPM-o-2_6-int4”,它应该与模型目录下的文件夹名称相匹配。 |
S2S_MiniCPM.voice_prompt | MiniCPM-o 的语音提示。 | |
S2S_MiniCPM.assistant_prompt | MiniCPM-o 的 Assistant 提示符。 | |
S2S_MiniCPM.enable_video_input | 假 | 是否启用视频输入。当视频输入被限制时,VRAM 消耗将大幅增加,在具有非量化模型的 24GB GPU 上,推理期间可能会出现 OOM。 |
S2S_MiniCPM.skip_video_frame | -1 | 确定使用视频模式时将使用多少帧。-1 表示仅使用每 1 秒间隔内的最新帧。0 表示将使用所有帧。n>0 表示在每个接受的帧后将跳过 n 帧。 |
ASR FunASR 模型
参数 | 默认值 | 描述 |
---|---|---|
ASR_Funasr.model_name | iic/SenseVoiceSmall | 该参数从 FunASR 中选择一个模型。模型会自动下载。要使用本地模型,请提供绝对路径。 |
LLM 纯文本模型
参数 | 默认值 | 描述 |
---|---|---|
LLM_Bailian.model_name | qwen-plus | 百联测试环境的 API。免费额度可以从百联获得。 |
LLM_Bailian.system_prompt | 默认系统提示符 | |
LLM_Bailian.api_url | 模型的 API URL | |
LLM_Bailian.api_key | 模型的 API 密钥 |
TTS CosyVoice 模型
参数 | 默认值 | 描述 |
---|---|---|
TTS_CosyVoice.api_url | 如果在另一台机器上部署 CosyVoice 服务器,则需要。 | |
TTS_CosyVoice.model_name | 详情请参考 CosyVoice。 | |
TTS_CosyVoice.spk_id | ‘中文女’ | 使用官方 SFT 语音,如“英文女”或“英文男”。与 互斥。ref_audio_path |
TTS_CosyVoice.ref_audio_path | 参考音频的绝对路径。与 互斥。spk_id | |
TTS_CosyVoice.ref_audio_text | 参考音频的文本内容。 | |
TTS_CosyVoice.采样率 | 24000 | 输出音频采样率 |
LiteAvatar 数字人
参数 | 默认值 | 描述 |
---|---|---|
LiteAvatar.avatar_name | 20250408/sample_data | 数字人类数据的名称。在 ModelScope 上提供了 100 个头像。有关更多详细信息,请参阅 LiteAvatarGallery。 |
LiteAvatar.fps | 25 | 数字人的帧速率。在高性能 CPU 上,它可以设置为 30 FPS。 |
LiteAvatar.enable_fast_mode | 假 | 低延迟模式。启用此选项可减少响应延迟,但可能会导致在功率不足的系统上响应开始时出现卡顿。 |
LiteAvatar.use_gpu | 真 | 是否使用 GPU 加速。CUDA 后端。 |
重要
配置中的所有 path 参数都可以使用绝对路径或相对于项目根目录的 paths 。
社区感谢
- 感谢社区成员 “titan909” 在 Bilibili 上发布部署教程视频。
- 感谢另一位社区成员 “十字鱼” 在 Bilibili 上分享了一个包含一键安装包的视频,并提供了下载链接。(提取代码包含在视频描述中 – 请仔细查看!一键打包
Star 历史
引文
如果您发现 OpenAvatarChat 对您的研究/项目有帮助,我们将不胜感激 Star⭐ 和引用✏️
@software{avatarchat2025,
author = {Gang Cheng, Tao Chen, Feng Wang, Binchao Huang, Hui Xu, Guanqiao He, Yi Lu, Shengyin Tan},
title = {OpenAvatarChat},
year = {2025},
publisher = {GitHub},
url = {https://github.com/HumanAIGC-Engineering/OpenAvatarChat}
}
暂无评论内容