Demo | 💬 WeChat (微信)
English | 中文
模块化的交互数字人对话实现，能够在单台PC上运行完整功能。
🤗 Demo | Demo | 💬 WeChat (微信)
ModelScope
和
🤗
HuggingFace
上均部署了一个体验服务，音频部分采用``SenseVoice + Qwen-VL + CosyVoice``实现，可以对``LiteAvatar``和``LAM``两种数字人能力进行切换，欢迎体验。
### 视频
LiteAvatar |
LAM |
](https://github.com/HumanAIGC-Engineering/gradio-webrtc)||
| VAD | snakers4/silero-vad |[](https://github.com/snakers4/silero-vad)||
| LLM | OpenBMB/MiniCPM-o |[](https://github.com/OpenBMB/MiniCPM-o)| [🤗](https://huggingface.co/openbmb/MiniCPM-o-2_6) [](https://modelscope.cn/models/OpenBMB/MiniCPM-o-2_6) |
| LLM-int4 | OpenBMB/MiniCPM-o |[](https://github.com/OpenBMB/MiniCPM-o)|[🤗](https://huggingface.co/openbmb/MiniCPM-o-2_6-int4) [](https://modelscope.cn/models/OpenBMB/MiniCPM-o-2_6-int4)|
| Avatar | HumanAIGC/lite-avatar |[](https://github.com/HumanAIGC/lite-avatar)||
| TTS | FunAudioLLM/CosyVoice |[](https://github.com/FunAudioLLM/CosyVoice)||
|Avatar|aigc3d/LAM_Audio2Expression|[](https://github.com/aigc3d/LAM_Audio2Expression)|[🤗](https://huggingface.co/3DAIGC/LAM_audio2exp)|
||facebook/wav2vec2-base-960h||[🤗](https://huggingface.co/facebook/wav2vec2-base-960h) [](https://modelscope.cn/models/AI-ModelScope/wav2vec2-base-960h)|
### 预置模式
| CONFIG名称 | ASR | LLM | TTS | AVATAR|
|----------------------------------------------------|-----|:---------:|:---------:|------------|
| chat_with_gs.yaml |SenseVoice| API |API| LAM |
| chat_with_minicpm.yaml |MiniCPM-o| MiniCPM-o | MiniCPM-o | lite-avatar |
| chat_with_openai_compatible.yaml |SenseVoice|API|CosyVoice| lite-avatar |
| chat_with_openai_compatible_bailian_cosyvoice.yaml |SenseVoice|API|API| lite-avatar |
| chat_with_openai_compatible_edge_tts.yaml |SenseVoice|API|edgetts| lite-avatar |
## 🚀安装部署
安装部署对应的模式前请先查看该模式使用到的**相关模块的安装方法**和[相关部署需求](#相关部署需求)。
### 选择配置
OpenAvatarChat按照配置文件启动并组织各个模块，可以按照选择的配置现在依赖的模型以及需要准备的ApiKey。项目在config目录下，提供以下预置的配置文件供参考：
#### chat_with_gs.yaml
使用[LAM](https://github.com/aigc3d/LAM)项目生成的gaussion splatting资产进行端侧渲染，语音使用百炼上的Cosyvoice，只有vad和asr运行在本地gpu，对机器性能依赖很轻，可以支持一机多路。
##### 使用的Handler
|类别|Handler|安装说明|
|---|---|---|
|Client|client/h5_rendering_client/cllient_handler_lam| [LAM端侧渲染 Client Handler](#lam端侧渲染-client-handler)|
|VAD|vad/silerovad/vad_handler/silero||
|ASR|asr/sensevoice/asr_handler_sensevoice||
|LLM|llm/openai_compatible/llm_handler/llm_handler_openai_compatible|[OpenAI兼容API的语言模型Handler](#openai兼容api的语言模型handler)
|TTS|tts/bailian_tts/tts_handler_cosyvoice_bailian|[百炼 CosyVoice Handler](#百炼-cosyvoice-handler)|
|Avatar|avatar/lam/avatar_handler_lam_audio2expression|[LAM数字人驱动Handler](#lam数字人驱动handler)|
||||
#### chat_with_minicpm.yaml
使用minicpm进行本地的语音到语音的对话生成，对GPU的性能与显存大小有一定要求。
##### 使用的Handler
|类别|Handler|安装说明|
|---|---|---|
|Client|client/rtc_client/client_handler_rtc|[服务端渲染 RTC Client Handler](#服务端渲染-rtc-client-handler)|
|VAD|vad/silerovad/vad_handler/silero||
|LLM|llm/minicpm/llm_handler_minicpm|[MiniCPM多模态语言模型Handler](#minicpm多模态语言模型handler)|
|Avatar|avatar/liteavatar/avatar_handler_liteavatar|[LiteAvatar数字人Handler](#liteavatar数字人handler)|
||||
#### chat_with_openai_compatible.yaml
该配置使用云端语言模型API，TTS使用cosyvoice，运行在本地。
#### 使用的Handler
|类别|Handler|安装说明|
|---|---|---|
|Client|client/rtc_client/client_handler_rtc|[服务端渲染 RTC Client Handler](#服务端渲染-rtc-client-handler)|
|VAD|vad/silerovad/vad_handler/silero||
|ASR|asr/sensevoice/asr_handler_sensevoice||
|LLM|llm/openai_compatible/llm_handler/llm_handler_openai_compatible|[OpenAI兼容API的语言模型Handler](#openai兼容api的语言模型handler)
|TTS|tts/cosyvoice/tts_handler_cosyvoice|[CosyVoice本地推理Handler](#cosyvoice本地推理handler)|
|Avatar|avatar/liteavatar/avatar_handler_liteavatar|[LiteAvatar数字人Handler](#liteavatar数字人handler)|
||||
#### chat_with_openai_compatible_bailian_cosyvoice.yaml
语言模型与TTS都使用云端API，2D数字人下对设备要求较低的配置。
#### 使用的Handler
|类别|Handler|安装说明|
|---|---|---|
|Client|client/rtc_client/client_handler_rtc|[服务端渲染 RTC Client Handler](#服务端渲染-rtc-client-handler)|
|VAD|vad/silerovad/vad_handler/silero||
|ASR|asr/sensevoice/asr_handler_sensevoice||
|LLM|llm/openai_compatible/llm_handler/llm_handler_openai_compatible|[OpenAI兼容API的语言模型Handler](#openai兼容api的语言模型handler)
|TTS|tts/bailian_tts/tts_handler_cosyvoice_bailian|[百炼 CosyVoice Handler](#百炼-cosyvoice-handler)|
|Avatar|avatar/liteavatar/avatar_handler_liteavatar|[LiteAvatar数字人Handler](#liteavatar数字人handler)|
||||
#### chat_with_openai_compatible_edge_tts.yaml
该配置使用edge tts，效果稍差，但不需要百炼的API Key。
#### 使用的Handler
|类别|Handler|安装说明|
|---|---|---|
|Client|client/rtc_client/client_handler_rtc|[服务端渲染 RTC Client Handler](#服务端渲染-rtc-client-handler)|
|VAD|vad/silerovad/vad_handler/silero||
|ASR|asr/sensevoice/asr_handler_sensevoice||
|LLM|llm/openai_compatible/llm_handler/llm_handler_openai_compatible|[OpenAI兼容API的语言模型Handler](#openai兼容api的语言模型handler)
|TTS|tts/edgetts/tts_handler_edgetts|[Edge TTS Handler](#edge-tts-handler)|
|Avatar|avatar/liteavatar/avatar_handler_liteavatar|[LiteAvatar数字人Handler](#liteavatar数字人handler)|
||||
### 本地运行
> [!IMPORTANT]
> 本项目子模块以及依赖模型都需要使用git lfs模块，请确认lfs功能已安装
> ```bash
> sudo apt install git-lfs
> git lfs install
> ```
> 本项目通过git子模块方式引用三方库，运行前需要更新子模块
> ```bash
> git submodule update --init --recursive
> ```
> 强烈建议：国内用户依然使用git clone的方式下载，而不要直接下载zip文件，方便这里的git submodule和git lfs的操作，github访问的问题，可以参考[github访问问题](https://github.com/maxiaof/github-hosts)
>
> 如果遇到问题欢迎提 [issue](https://github.com/HumanAIGC-Engineering/OpenAvatarChat/issues) 给我们
>
> 本项目的运行依赖CUDA，请确保本机NVIDIA驱动程序支持的CUDA版本>=12.4
#### uv安装
推荐安装[uv](https://docs.astral.sh/uv/)，使用uv进行进行本地环境管理。
> 官方独立安装程序
> ```bash
> # 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
> ```
#### 依赖安装
##### 安装全部依赖
```bash
uv sync --all-packages
```
##### 仅安装所需模式的依赖
```bash
uv run install.py --uv --config <配置文件的绝对路径>.yaml
```
#### 运行
```bash
uv run src/demo.py --config <配置文件的绝对路径>.yaml
```
### Docker运行
容器化运行：容器依赖nvidia的容器环境，在准备好支持GPU的docker环境后，运行以下命令即可完成镜像的构建与启动：
```bash
./build_and_run.sh --config <配置文件的绝对路径>.yaml
```
## Handler依赖安装说明
### 服务端渲染 RTC Client Handler
暂无特别依赖和需要配置的内容。
### LAM端侧渲染 Client Handler
端侧渲染基于[服务端渲染 RTC Client Handler](#服务端渲染-rtc-client-handler)扩展，支持多路链接，可以通过配置文件选择形象。
#### 形象选择
形象可以通过[LAM](https://github.com/aigc3d/LAM)项目进行训练（LAM对话数字人资产生产流程待完善，敬请期待），本项目中预置了4个范例形象，位于src/handlers/client/h5_rendering_client/lam_samples下。用户可以通过在配置文件中用asset_path字段进行选择，也可以选择自行训练的资产文件。参考配置如下：
```yaml
LamClient:
module: client/h5_rendering_client/client_handler_lam
asset_path: "lam_samples/barbara.zip"
concurrent_limit: 5
```
### OpenAI兼容API的语言模型Handler
本地推理的语言模型要求相对较高，如果你已有一个可调用的 LLM api_key,可以用这种方式启动来体验对话数字人。
可以通过配置文件选择所使用模型、系统prompt、API和API Key。参考配置如下，其中apikey可以被环境变量覆盖。
```yaml
LLM_Bailian:
moedl_name: "qwen-plus"
system_prompt: "你是个AI对话数字人，你要用简短的对话来回答我的问题，并在合理的地方插入标点符号"
api_url: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
api_key: 'yourapikey' # default=os.getenv("DASHSCOPE_API_KEY")
```
> [!TIP]
> 系统默认会获取项目当前目录下的.env文件用来获取环境变量。
> [!Note]
> * 代码内部调用方式
> ```python
> 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_url + api_key
### MiniCPM多模态语言模型Handler
#### 依赖模型
* MiniCPM-o-2.6
本项目可以使用MiniCPM-o-2.6作为多模态语言模型为数字人提供对话能力，用户可以按需从[Huggingface](https://huggingface.co/openbmb/MiniCPM-o-2_6)或者[Modelscope](https://modelscope.cn/models/OpenBMB/MiniCPM-o-2_6)下载相关模型。建议将模型直接下载到 \](https://modelscope.cn/models/AI-ModelScope/wav2vec2-base-960h)
* 从huggingface下载, 确保lfs已安装，使当前路径位于项目根目录，执行：
```
git clone --depth 1 https://huggingface.co/facebook/wav2vec2-base-960h ./models/wav2vec2-base-960h
```
* 从modelscope下载, 确保lfs已安装，使当前路径位于项目根目录，执行：
```
git clone --depth 1 https://www.modelscope.cn/AI-ModelScope/wav2vec2-base-960h.git ./models/wav2vec2-base-960h
```
* LAM_audio2exp [🤗](https://huggingface.co/3DAIGC/LAM_audio2exp)
* 从huggingface下载, 确保lfs已安装，使当前路径位于项目根目录，执行：
```
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
```
* 国内用户可以从oss地址下载, 使当前路径位于项目根目录，执行：
```
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证书以开启https，默认配置会读取ssl_certs目录下的localhost.crt和localhost.key，用户可以相应修改配置来使用自己的证书。我们也在scripts目录下提供了生成自签名证书的脚本。需要在项目根目录下运行脚本以使生成的证书被放到默认位置。
```bash
scripts/create_ssl_certs.sh
```
### TURN Server
如果点击开始对话后，出现一直等待中的情况，可能你的部署环境存在NAT穿透方面的问题（如部署在云上机器等），需要进行数据中继。在Linux环境下，可以使用coturn来架设TURN服务。可参考以下操作在同一机器上安装、启动并配置使用coturn：
* 运行安装脚本
```console
$ chmod 777 scripts/setup_coturn.sh
# scripts/setup_coturn.sh
```
* 修改config配置文件，添加以下配置后启动服务。
```yaml
default:
chat_engine:
handler_configs:
RtcClient: #若使用Lam，则此项配置为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所需端口
### 配置说明
程序默认启动时，会读取 **