Lite-Avatar在Linux系统下的部署与优化

Lite-Avatar在Linux系统下的部署与优化

想自己搭建一个能实时对话的数字人吗？最近开源的Lite-Avatar项目让这件事变得简单了不少。它是个轻量级的2D数字人方案，用音频就能驱动虚拟形象的面部表情和口型，而且对硬件要求不高，CPU上都能跑到30帧。

不过，真要在Linux系统上把它跑起来，还是会遇到不少坑。官方文档虽然详细，但信息比较分散，新手容易找不到北。我自己折腾了好几天，把整个部署流程走通了，也总结了一些优化经验，今天就跟大家分享一下。

这篇文章会手把手带你完成Lite-Avatar在Linux下的完整部署，从环境准备到性能调优，每个步骤都会讲清楚。如果你对数字人开发感兴趣，或者想给自己的项目加个虚拟助手，跟着做一遍应该就能搞定。

1. 部署前的准备工作

在开始之前，得先搞清楚Lite-Avatar到底是个什么东西。简单说，它是个开源的数字人驱动引擎，属于OpenAvatarChat项目的一部分。OpenAvatarChat是个更大的框架，能把语音识别、大语言模型、语音合成这些模块组合起来，做成一个完整的对话数字人系统。

Lite-Avatar在里面负责的是最核心的部分——让虚拟形象动起来。你给它一段音频，它就能分析出音频里的语音特征，然后生成对应的面部动画，包括口型、表情这些。最厉害的是它真的很轻量，不需要高端显卡，普通CPU就能跑得挺流畅。

1.1 硬件和系统要求

先看看你的机器够不够格。虽然Lite-Avatar对硬件要求不高，但整个OpenAvatarChat系统还是有些基本要求的：

• 操作系统：我是在Ubuntu 22.04上测试的，理论上主流的Linux发行版都行，比如CentOS、Debian这些。Windows和macOS也能跑，但配置方法不太一样，今天主要讲Linux。
• Python版本：需要Python 3.10到3.11之间。官方推荐用3.11.7，我用3.11.11也跑通了。注意别用太老的版本，有些新特性不支持。
• 显卡：如果有NVIDIA显卡最好，CUDA版本要12.4以上。没有显卡也行，Lite-Avatar本身可以用CPU跑，但其他模块（比如语音识别）可能就需要用云端API了。
• 内存：至少8GB，建议16GB以上。模型加载和推理都比较吃内存。
• 存储空间：各种模型文件加起来大概要10-15GB，留够空间。

1.2 基础环境配置

开始之前，先把一些基础工具装好。打开终端，一条条执行：

# 更新系统包 sudo apt update sudo apt upgrade -y # 安装必要的开发工具 sudo apt install -y build-essential cmake git wget curl # 安装Python开发环境 sudo apt install -y python3-dev python3-pip python3-venv # 安装ffmpeg（处理音视频需要） sudo apt install -y ffmpeg # 安装Git LFS（大文件存储，下载模型必须） sudo apt install -y git-lfs git lfs install

如果你有NVIDIA显卡，还得确认一下CUDA环境。运行nvidia-smi看看驱动版本，然后去NVIDIA官网查查对应的CUDA版本支持情况。现在很多新项目都要求CUDA 12.x了，如果你的驱动太老，可能得更新一下。

2. 项目获取与依赖安装

环境准备好了，接下来把代码和模型弄下来。这个过程稍微有点繁琐，因为项目用了很多子模块，模型文件也很大，但一步步跟着做就行。

2.1 克隆主仓库

先从GitHub上把OpenAvatarChat项目拉下来：

# 克隆主仓库，加上--depth=1只拉最新提交，省时间省空间 git clone --depth=1 https://github.com/HumanAIGC-Engineering/OpenAvatarChat.git cd OpenAvatarChat

进到项目目录后，你会发现里面有很多子模块。这些子模块是项目依赖的其他开源库，比如Lite-Avatar算法本身、语音识别模型、WebRTC组件等等。得把它们都初始化一下：

# 初始化并更新所有子模块 git submodule update --init --recursive --depth 1

这个命令可能会跑一会儿，因为要下载不少东西。如果网络不太好，可能会失败或者特别慢。有个小技巧，可以修改一下Git的配置，用国内的镜像源：

# 设置Git代理（如果需要） git config --global http.proxy http://你的代理地址:端口 git config --global https.proxy https://你的代理地址:端口 # 或者用ssh方式克隆（如果https不行） # 先在GitHub上配置好SSH key，然后把仓库地址改成[e-mail]:HumanAIGC-Engineering/OpenAvatarChat.git

2.2 安装Python依赖

项目现在推荐用uv来管理Python环境，这是个新的包管理工具，比pip快不少。先安装uv：

# 用官方脚本安装uv curl -LsSf https://astral.sh/uv/install.sh | sh # 安装后重新加载shell配置 source ~/.bashrc # 或者 source ~/.zshrc，看你用的什么shell

装好uv后，创建虚拟环境并安装依赖。这里有个选择：你可以安装所有依赖，也可以只安装你需要的那个配置模式的依赖。为了省事，我建议先装全部：

# 创建虚拟环境（会自动选择合适Python版本） uv venv # 激活虚拟环境 source .venv/bin/activate # 安装所有依赖包 uv sync --all-packages

如果网络不好，uv下载包可能也会慢。可以试试设置镜像源：

# 设置uv使用国内镜像 export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --all-packages

全部依赖装完大概要几分钟，取决于你的网速。完成后，虚拟环境里就有所有需要的Python包了。

2.3 下载模型文件

这是最耗时的部分。Lite-Avatar需要一些预训练模型，包括数字人形象数据、语音识别模型等等。项目提供了下载脚本，但模型都挺大的，总共要10GB左右。

先下载Lite-Avatar需要的模型：

# 运行下载脚本 bash scripts/download_liteavatar_weights.sh

这个脚本会从ModelScope（魔塔社区）下载模型。ModelScope是阿里开源的模型社区，国内访问速度还不错。脚本会自动把模型放到resource/avatar/liteavatar目录下。

如果你还想用其他数字人方案，比如LAM（3D数字人），可以再下载对应的模型：

# 下载LAM需要的语音特征提取模型 git clone --depth 1 https://www.modelscope.cn/AI-ModelScope/wav2vec2-base-960h.git ./models/wav2vec2-base-960h # 下载LAM的表情驱动模型 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

注意，LAM的模型文件是个tar包，解压后应该得到一个pretrained_models文件夹。如果解压工具有问题，可以试试把文件后缀改成.tar.gz再用图形化工具解压。

3. 配置与运行

模型都下载好了，现在来配置和启动数字人。OpenAvatarChat支持好几种运行模式，你可以根据硬件条件和需求选择。

3.1 选择运行模式

项目提供了几个预设的配置文件，在config目录下：

• chat_with_minicpm.yaml：用MiniCPM-o本地大模型，要求最高，需要20GB以上显存
• chat_with_openai_compatible.yaml：用云端API+本地CosyVoice语音合成
• chat_with_openai_compatible_bailian_cosyvoice.yaml：语音和语言模型都用云端API，对硬件要求最低
• chat_with_openai_compatible_edge_tts.yaml：用微软Edge TTS，完全免费但效果稍差
• chat_with_lam.yaml：用LAM 3D数字人

对于大多数想快速体验的人来说，我推荐用chat_with_openai_compatible_bailian_cosyvoice.yaml这个配置。它把最耗资源的语音合成和语言模型都放到云端了，本地只需要跑轻量的语音识别和数字人生成，对显卡要求很低。

3.2 配置API密钥

选好配置后，需要设置API密钥。如果你用云端方案，得去申请一些服务的访问权限。

首先是阿里云百炼，这是阿里的大模型服务平台，有免费额度可以用：

1. 访问 https://bailian.console.aliyun.com
2. 注册登录后，在模型市场里找到qwen-plus和cosyvoice-v1这两个模型
3. 点击开通服务，系统会给你API密钥

拿到密钥后，复制一份配置文件并修改：

# 复制配置文件 cp config/chat_with_openai_compatible_bailian_cosyvoice.yaml config/my_config.yaml # 编辑配置文件 nano config/my_config.yaml

找到配置文件里的这些部分，填上你的API密钥：

LLMOpenAICompatible: model_name: "qwen-plus" api_key: "你的百炼API密钥" # 这里填sk-开头的那个字符串 CosyVoice: module: tts/bailian_tts/tts_handler_cosyvoice_bailian api_key: "你的百炼API密钥" # 同一个密钥就行

如果你不想用百炼，也可以用其他兼容OpenAI API的服务，比如OpenRouter上的免费模型。改一下配置就行：

LLMOpenAICompatible: model_name: "qwen2.5-vl-72b-instruct" api_url: "https://openrouter.ai/api/v1" api_key: "你的OpenRouter密钥"

3.3 首次运行测试

配置好了，激动人心的时刻到了——启动数字人！

# 确保在虚拟环境中 source .venv/bin/activate # 运行程序 uv run src/demo.py --config config/my_config.yaml

第一次运行会做很多初始化工作，比如加载模型、准备资源等等，可能要等一两分钟。如果一切顺利，你会看到类似这样的输出：

INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on https://0.0.0.0:8282 (Press CTRL+C to quit)

看到这个，就说明服务启动成功了。打开浏览器，访问 https://localhost:8282（注意是https），应该能看到数字人界面了。

第一次访问时，浏览器可能会提示证书不安全。这是因为项目用了自签名SSL证书，点“高级”->“继续前往”就行。WebRTC必须用HTTPS，所以这个证书是必须的。

4. 常见问题与解决

第一次运行很少能一帆风顺，下面是我遇到的一些典型问题和解决方法。

4.1 端口被占用

如果8282端口已经被其他程序用了，启动时会报错。可以改个端口：

# 修改配置文件中的端口 # 在my_config.yaml里找到service.port，改成其他值比如8283 service: port: 8283 # 或者启动时指定端口 uv run src/demo.py --config config/my_config.yaml --port 8283

4.2 证书问题

如果浏览器打不开，或者麦克风摄像头权限获取失败，很可能是SSL证书的问题。项目自带了一个自签名证书，但有时候浏览器不认。可以自己生成一个：

# 运行证书生成脚本 bash scripts/create_ssl_certs.sh # 脚本会在ssl_certs目录下生成localhost.crt和localhost.key # 确保配置文件指向这两个文件 service: cert_file: "ssl_certs/localhost.crt" cert_key: "ssl_certs/localhost.key"

如果你有域名和正规的SSL证书，也可以替换成自己的。

4.3 模型加载失败

如果启动时卡在模型加载阶段，可能是模型文件没下载完整，或者路径不对。检查一下：

# 检查Lite-Avatar模型 ls -lh resource/avatar/liteavatar/ # 应该能看到很多数字人形象的文件夹 # 检查语音识别模型 ls -lh models/iic/SenseVoiceSmall/ # 应该有model.pb等文件 # 如果文件不全，重新下载 bash scripts/download_liteavatar_weights.sh

有时候网络中断会导致下载不完整，删掉重新下就行。

4.4 显存不足

如果你用本地大模型方案，可能会遇到显存不够的问题。有几种解决办法：

1. 换用云端API方案：这是最简单的，对显存要求最低
2. 使用量化模型：MiniCPM-o有int4量化版本，显存占用少一半
3. 调整批处理大小：在配置文件里减小batch_size
4. 关闭视频输入：如果不需要摄像头，把enable_video_input设为false

5. 性能优化与调优

系统能跑起来只是第一步，要让数字人对话流畅自然，还得做些优化。

5.1 调整数字人参数

Lite-Avatar有几个关键参数可以调：

LiteAvatar: module: avatar/liteavatar/avatar_handler_liteavatar avatar_name: "20250408/sample_data" # 数字人形象，可以换其他 fps: 25 # 帧率，CPU跑可以降到20，GPU可以升到30 use_gpu: true # 是否用GPU，有显卡就开 enable_fast_mode: false # 低延迟模式，性能好可以开

• avatar_name：LiteAvatarGallery里有100多个预训练形象，可以换着试试。格式是日期/形象名，比如20250612/P1rcvIW8H6kvcYWNkEnBWPfg。
• fps：帧率越高动画越流畅，但对性能要求也越高。CPU上20-25fps就够用了，GPU可以开到30。
• enable_fast_mode：这个模式会减少一些预处理，能降低延迟，但如果硬件性能不够，开头可能会有卡顿。

5.2 语音识别优化

语音识别（ASR）的准确度和延迟直接影响体验。SenseVoice模型有几个参数可以调：

ASR_Funasr: model_name: "iic/SenseVoiceSmall" # 模型大小，还有Medium、Large版本 # 更大的模型更准但也更慢

如果你发现识别不准，可以试试这些方法：

1. 确保录音质量：用个好点的麦克风，环境安静些
2. 调整VAD参数：语音活动检测的阈值，可以微调speaking_threshold
3. 换用其他ASR模型：项目也支持其他FunASR模型

5.3 网络优化

如果是云端API方案，网络延迟很重要。可以测一下到API服务器的延迟：

# 测试到百炼API的延迟 ping dashscope.aliyuncs.com # 如果延迟高，可以考虑用其他地区的服务

有时候对话卡在“等待中”，可能是WebRTC的NAT穿透问题。如果是公网访问，需要配置TURN服务器：

# 安装coturn sudo apt install -y coturn # 运行安装脚本 chmod +x scripts/setup_coturn.sh ./scripts/setup_coturn.sh

然后在配置文件里加上TURN服务器配置：

RtcClient: turn_config: turn_provider: "turn_server" urls: ["turn:你的服务器IP:3478"] username: "你的用户名" credential: "你的密码"

5.4 内存和显存管理

长时间运行可能会内存泄漏，可以定时重启服务。写个简单的监控脚本：

#!/bin/bash # monitor.sh while true; do # 检查内存使用 memory_usage=$(free -m | awk 'NR==2{printf "%.2f", $3*100/$2}') # 如果内存使用超过80%，重启服务 if (( $(echo "$memory_usage > 80" | bc -l) )); then echo "内存使用过高($memory_usage%)，重启服务..." pkill -f "demo.py" sleep 5 uv run src/demo.py --config config/my_config.yaml & fi sleep 60 # 每分钟检查一次 done

6. 进阶使用技巧

基础功能跑通了，可以玩点更高级的。

6.1 使用自定义数字人形象

LiteAvatarGallery里的100个形象不够用？可以自己训练。不过训练模型比较复杂，有个取巧的办法：用MuseTalk的数字人。

MuseTalk是另一个开源项目，可以用一张照片生成会说话的视频。OpenAvatarChat也集成了它：

# 下载MuseTalk模型 bash scripts/download_musetalk_weights.sh # 修改配置文件，用MuseTalk替换LiteAvatar Avatar_MuseTalk: module: avatar/musetalk/avatar_handler_musetalk avatar_video_path: "你的视频路径.mp4" # 用这个视频作为数字人底版 fps: 20

MuseTalk对显存要求高一些，但效果更灵活，可以用任何视频作为数字人源。

6.2 多路并发支持

如果你想让多个用户同时和数字人对话，需要开启多session支持：

default: chat_engine: concurrent_limit: 3 # 最大并发数，根据硬件调整

注意，每路并发都会占用一份显存。LiteAvatar在GPU上每路大概占3GB，如果你的显卡是12GB，最多开4路。

6.3 集成到其他应用

OpenAvatarChat提供了API接口，可以集成到你自己的应用里。启动服务后，其实背后是个WebSocket服务，你可以用任何语言来调用。

简单的测试可以用curl：

# 获取服务状态 curl -k https://localhost:8282/health # 发送文本对话（如果开启了文本输入） curl -k -X POST https://localhost:8282/api/chat \ -H "Content-Type: application/json" \ -d '{"text": "你好", "session_id": "test"}'

更正式的集成可以参考项目源码里的client示例。

6.4 使用Docker部署

如果你不想折腾环境，可以用Docker。项目提供了Dockerfile和构建脚本：

# 构建镜像（CUDA 12.8版本） bash build_cuda128.sh # 运行容器 bash run_docker_cuda128.sh --config config/my_config.yaml

Docker方式更干净，依赖都打包在镜像里了，但镜像比较大，下载需要时间。

7. 总结

走完这一整套流程，你应该已经在Linux上成功部署了Lite-Avatar数字人系统。从环境准备到运行优化，每个步骤我都尽量讲得详细，特别是那些容易踩坑的地方。

实际用下来，Lite-Avatar的表现还是挺让人惊喜的。虽然只是个轻量级方案，但动画效果很自然，延迟控制得也不错。最重要的是它对硬件要求友好，不用高端显卡也能跑，这让个人开发者和小团队也能玩转数字人技术。

当然，开源项目总有些小毛病。文档虽然详细但比较分散，错误提示有时候不够明确，依赖管理也有点复杂。但考虑到这是免费的开源项目，而且更新很活跃，这些小问题都能接受。

如果你打算长期使用，我建议多关注项目的GitHub仓库，新版本会修复很多问题，也会增加新功能。社区也很活跃，遇到问题可以提issue，或者加他们的微信群交流。

数字人技术现在发展很快，像Lite-Avatar这样的轻量级方案会越来越普及。无论是做虚拟主播、智能客服，还是教育娱乐应用，都有很大的想象空间。希望这篇教程能帮你迈出第一步，后面怎么玩，就看你自己的创意了。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。