【阿里开源】Python对话式数字人-Open Avatar Chat

图片[1]-【阿里开源】Python对话式数字人-Open Avatar Chat - 盘古CG网-盘古CG网

演示地址:Open Avatar Chat – a Hugging Face Space by HumanAIGC-Engineering-Team

一种模块化的交互式数字人机对话实现,可在单台 PC 上运行全部功能。

🤗 演示 | 演示 |💬 微信

🔥 核心亮点

  • 低延迟数字人实时对话:平均响应延迟约为 2.2 秒。
  • 多模态语言模型:支持文本、音频、视频等多模态语言模型。
  • 模块化设计:采用模块化设计,允许灵活的组件更换,实现不同的功能组合。

📢 新闻

更改日志

  • [2025.04.18] ⭐️⭐️⭐️ 0.3.0 版本已发布:
    • 🎉🎉🎉 祝贺 LAM 团队的论文被 SIGGRAPH 2025 接受!🎉🎉🎉
    • 增加了对数字人中 LAM 的支持,在选择 LAM 时启用并发配置。TTS 现在支持 edge_tts 和 BaiLian CosyVoice。
    • 更新了基于 UV 和处理程序模块的依赖管理方法,支持直接执行或使用 Docker。
    • 更新了 CSS 响应式布局。
  • [2025.04.14] ⭐️⭐️⭐️ 0.2.2 版本发布:
  • [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 + CosyVoiceLiteAvatarLAM

演示视频

LiteAvatar (英语) OpenAvatarChat_Demo.mp4 议员 OpenAvatarChat_LAM_Demo.mp4 

📖 内容

概述

介绍

Open Avatar Chat 是一种模块化的交互式数字人类对话实现,可以在单台 PC 上运行全部功能。它目前支持将 MiniCPM-o 作为多模态语言模型,或使用基于云的 API 来取代传统的 ASR + LLM + TTS 设置。这两种模式的架构如下图所示。有关更多预设模式,请参见下文

图片[2]-【阿里开源】Python对话式数字人-Open Avatar Chat - 盘古CG网-盘古CG网

要求

  • 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-int4OpenBMB/MiniCPM-o🤗  
化身HumanAIGC/lite-头像
TTSFunAudioLLM/CosyVoice
化身AIGC3D/LAM_Audio2Expression🤗
脸书/WAV2VEC2-BASE-960H🤗  

预设模式

CONFIG 名称ASR法学硕士TTS化身
chat_with_gs.yaml商汤语音应用程序接口应用程序接口议员
chat_with_minicpm.yamlMiniCPM-oMiniCPM-oMiniCPM-olite-头像
chat_with_openai_compatible.yaml商汤语音应用程序接口CosyVoice (舒适语音)lite-头像
chat_with_openai_compatible_bailian_cosyvoice.yaml商汤语音应用程序接口应用程序接口lite-头像
chat_with_openai_compatible_edge_tts.yaml商汤语音应用程序接口Edgettslite-头像

🚀 开始使用

在安装部署相应模式之前,请参考相关模块的安装方法和 可选部署

选择配置

OpenAvatarChat 的功能将遵循启动期间指定的配置。我们在 config 文件夹下提供了几个示例配置文件。

chat_with_gs.yaml

此配置使用 LAM 生成的高斯展开资产作为客户端渲染的头像。使用来自百联平台的基于 api 的 openai 兼容 llm 和 tts,只有 vad 和 asr 处理程序在本地运行,因此这是最轻量级的配置选择,它支持单个服务上的多个连接。

使用的处理程序

类型处理器安装 Notes
客户客户端/h5_rendering_client/cllient_handler_lamLAM 客户端渲染处理程序
VAD系列vad/silerovad/vad_handler/silero
ASRASR/SenseVoice/asr_handler_sensevoice
法学硕士llm/openai_compatible/llm_handler/llm_handler_openai_compatibleOpenAI 兼容的 LLM 处理程序
TTStts/bailian_tts/tts_handler_cosyvoice_bailian百联 Cosy语音处理器
化身头像/lam/avatar_handler_lam_audio2expressionLAM 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_minicpmMiniCPM Omni Speech2Speech 处理程序
化身头像/lite头像/avatar_handler_liteavatarLiteAvatar 头像处理程序

chat_with_openai_compatible.yaml

此配置使用兼容 openai 的 api 作为 llm provider,使用 CosyVoice 作为本地 tts 模型。

使用的处理程序

类型处理器安装 Notes
客户客户端/rtc_client/client_handler_rtc服务端渲染 RTC 客户端处理程序
VAD系列vad/silerovad/vad_handler/silero
ASRASR/SenseVoice/asr_handler_sensevoice
法学硕士llm/openai_compatible/llm_handler/llm_handler_openai_compatibleOpenAI 兼容的 LLM 处理程序
TTStts/cosyvoice/tts_handler_cosyvoiceCosyVoice 本地推理处理程序
化身头像/lite头像/avatar_handler_liteavatarLiteAvatar 头像处理程序

chat_with_openai_compatible_bailian_cosyvoice.yaml

LLM 和 TTS 都是由 API 提供的,它是 LiteAvatar 最轻量级的配置。

使用的处理程序

类型处理器安装 Notes
客户客户端/rtc_client/client_handler_rtc服务端渲染 RTC 客户端处理程序
VAD系列vad/silerovad/vad_handler/silero
ASRASR/SenseVoice/asr_handler_sensevoice
法学硕士llm/openai_compatible/llm_handler/llm_handler_openai_compatibleOpenAI 兼容的 LLM 处理程序
TTStts/bailian_tts/tts_handler_cosyvoice_bailian百联 Cosy语音处理器
化身头像/lite头像/avatar_handler_liteavatarLiteAvatar 头像处理程序

chat_with_openai_compatible_edge_tts.yaml

此配置使用 Edge TTS,不需要百联的 API Key。

类型处理器安装 Notes
客户客户端/rtc_client/client_handler_rtc服务端渲染 RTC 客户端处理程序
VAD系列vad/silerovad/vad_handler/silero
ASRASR/SenseVoice/asr_handler_sensevoice
法学硕士llm/openai_compatible/llm_handler/llm_handler_openai_compatibleOpenAI 兼容的 LLM 处理程序
TTStts/edgets/tts_handler_edgettsEdge TTS 处理程序
化身头像/lite头像/avatar_handler_liteavatarLiteAvatar 头像处理程序

本地执行

重要

本项目中的子模块和依赖模型需要 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 | sh

PyPI 安装

# 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 进行安装。具体的依赖安装和执行过程如下:

  1. 安装 Anaconda 或 Miniconda
conda create -n openavatarchat python=3.10
conda activate openavatarchat
conda install -c conda-forge pynini==2.1.6
  1. 将 UV 索引的环境变量设置为 Conda 环境
# cmd
set VIRTUAL_ENV=%CONDA_PREFIX%
# powershell 
$env:VIRTUAL_ENV=$env:CONDA_PREFIX
  1. 在安装依赖项并使用 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-SFTChinese Femaleref_audio_pathref_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_filessl_certs/localhost.crtssl 的证书文件,如果同时找到 cert_file 和 cert_key,则启用 https。
service.cert_keyssl_certs/localhost.keyssl 的证书文件,如果同时找到 cert_file 和 cert_key,则启用 https。
chat_engine.model_root模型查找模型的路径。
chat_engine.handler_configs不适用处理程序配置由每个处理程序提供。

当前实现的处理程序提供以下配置:

  • VAD系列
参数违约描述
SileraVad.speaking_threshold0.5阈值,用于确定用户是开始说话还是结束说话。
SileraVad.start_delay2048说话概率应高于阈值,才能在音频样本中被识别为说话开始,单位。
SileraVad.end_delay2048说话概率应低于阈值,才能在音频样本中被识别为说话结束的单位。
SileraVad.buffer_look_back1024对于高阈值,声部的最开始部分可能会被削波,使用它来补偿,单位在音频样本中。
SileraVad.speech_padding512此长度的静音将在音频样本的开始和结束单位上填充。
  • 法学硕士
参数违约描述
S2S_MiniCPM.model_nameMiniCPM-o-2_6要加载的模型可以是 “MiniCPM-o-2_6” 或 “MiniCPM-o-2_6-int4”,它应该与模型目录下的文件夹名称相匹配。
S2S_MiniCPM.voice_promptMiniCPM-o 的语音提示。
S2S_MiniCPM.assistant_promptMiniCPM-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_nameiic/SenseVoiceSmall该参数从 FunASR 中选择一个模型。模型会自动下载。要使用本地模型,请提供绝对路径。

LLM 纯文本模型

参数默认值描述
LLM_Bailian.model_nameqwen-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_name20250408/sample_data数字人类数据的名称。在 ModelScope 上提供了 100 个头像。有关更多详细信息,请参阅 LiteAvatarGallery
LiteAvatar.fps25数字人的帧速率。在高性能 CPU 上,它可以设置为 30 FPS。
LiteAvatar.enable_fast_mode低延迟模式。启用此选项可减少响应延迟,但可能会导致在功率不足的系统上响应开始时出现卡顿。
LiteAvatar.use_gpu是否使用 GPU 加速。CUDA 后端。

重要

配置中的所有 path 参数都可以使用绝对路径或相对于项目根目录的 paths 。

社区感谢

  • 感谢社区成员 “titan909” 在 Bilibili 上发布部署教程视频
  • 感谢另一位社区成员 “十字鱼” 在 Bilibili 上分享了一个包含一键安装包的视频,并提供了下载链接。(提取代码包含在视频描述中 – 请仔细查看!一键打包

Star 历史

图片[3]-【阿里开源】Python对话式数字人-Open Avatar Chat - 盘古CG网-盘古CG网

引文

如果您发现 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}
}
© 版权声明
THE END
喜欢就支持一下吧
点赞10 分享
评论 抢沙发

请登录后发表评论

    暂无评论内容