Debian 12 系统安装 HeyGem 数字人指南

Debian 12 系统安装 HeyGem 数字人指南

根据 Duix.Heygem 项目文档，以下是针对 Debian 12 的完整安装流程：

系统要求

1. 硬件：

• • NVIDIA GPU（RTX 4070S 已验证支持）
  • 32GB+ 内存
  • 100GB+ 可用磁盘空间

2. 软件：

• • Debian 12 (Bookworm)
  • NVIDIA 驱动 ≥515
  • Docker 20.10.24+

安装步骤

1. 安装 NVIDIA 驱动

# 启用非免费仓库
sudo sed -i 's/main/main contrib non-free/g' /etc/apt/sources.list

# 安装驱动
sudo apt update
sudo apt install nvidia-driver firmware-misc-nonfree
sudo reboot  # 重启生效

# 验证
nvidia-smi  # 应显示驱动版本和GPU信息

2. 安装 Docker 和 NVIDIA Container Toolkit

# 安装 Docker
sudo apt install docker.io docker-compose-plugin
sudo systemctl enable --now docker

# 安装 NVIDIA Container Toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/debian12/$(ARCH) /" | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 验证 GPU 支持
docker run --rm --gpus all nvidia/cuda:12.3.1-base nvidia-smi

3. 部署 HeyGem 服务端

# 克隆项目
git clone https://github.com/duixcom/Duix.Heygem.git
cd Duix.Heygem/deploy

# 拉取镜像（使用国内加速镜像）
docker pull crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/fun-asr:latest
docker pull crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/fish-speech-ziming:latest
docker pull crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/heygem.ai:latest

# 重命名镜像(对齐docker compose中的镜像名)
docker tag crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/fish-speech-ziming:latest guiji2025/fish-speech-ziming:latest
docker tag crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/fun-asr:latest guiji2025/fun-asr:latest
docker tag crpi-87t8jkvf79rj7hal.cn-huhehaote.personal.cr.aliyuncs.com/modelers_park/heygem.ai:latest guiji2025/heygem.ai:latest


# 创建数据目录
mkdir -p ~/heygem_data
sudo chmod -R 777 ~/heygem_data

# 修改 docker-compose 配置
nano docker-compose-linux.yml

修改内容：

volumes:
  - /home/$USER/heygem_data:/code/data  # 修改为你的路径

# 启动服务
docker compose -f docker-compose-linux.yml up -d

# 检查服务状态
docker ps  # 应显示3个运行中的容器

4. 安装客户端

# 安装依赖
sudo apt install libfuse2 libnss3 libgtk-3-0 libx11-xcb1

# 下载客户端（替换为最新版本）
cd ../build
wget https://github.com/duixcom/Duix.Heygem/releases/latest/download/HeyGem-linux.AppImage

# 赋予执行权限
chmod +x HeyGem-linux.AppImage

# 运行客户端（普通用户）
./HeyGem-linux.AppImage

# 如果使用 root 用户
./HeyGem-linux.AppImage --no-sandbox

故障排除

1. GPU 未被 Docker 识别

# 检查容器 GPU 访问
docker exec -it heygem-tts nvidia-smi

# 若失败，重建容器
docker compose -f docker-compose-linux.yml down
docker compose -f docker-compose-linux.yml up -d

2. 客户端启动失败

# 安装缺失依赖
sudo apt install --reinstall libxcb-xinerama0 libxkbcommon-x11-0

# 检查系统日志
journalctl -f  # 运行时查看日志

3. 视频生成卡顿优化

编辑 docker-compose-linux.yml：

environment:
  PRECISION: "fp16"  # 降低计算精度
  MAX_CONCURRENT_TASKS: 1  # 限制并行任务

关键注意事项

1. 路径设置：

• • 确保 ~/heygem_data 有足够空间（建议100GB+）
  • 在客户端设置中匹配相同路径

2. 权限问题：

# 定期修复权限
sudo chown -R $USER:$USER ~/heygem_data
sudo chmod -R 777 ~/heygem_data

3. 更新维护：

# 更新项目
cd Duix.Heygem
git pull
docker compose -f deploy/docker-compose-linux.yml down
docker compose -f deploy/docker-compose-linux.yml up -d --pull always

硬件限制提示：RTX 4070S 的12GB显存可能限制视频长度，建议生成≤2分钟视频

完整文档参考：Duix.Heygem官方GitHub