手把手教你本地部署 HeyGem：离线生成数字人直播视频

复制代码

如果这篇文章对你有帮助，欢迎关注我的CSDN账号「来福猿」，
有问题可以在评论区留言，我会一一回复。

本地部署 HeyGem 的完整流程可以概括为八个步骤：先完成环境准备，再获取项目代码，依次安装后端依赖和前端页面，随后下载数字人相关模型，启动服务，创建数字人分身，最后离线生成直播口播视频。下面是完整流程图。

flowchart TD A[环境准备] --> B[获取代码] B --> C[安装后端依赖] C --> D[安装前端] D --> E[下载模型] E --> F[启动服务] F --> G[创建数字人] G --> H[生成视频]

各步骤要点如下：

**环境准备：**重点确认显卡显存、内存、硬盘空间，以及 Python、Node.js、Git 和 CUDA 等软件环境是否满足要求。
**获取代码：**推荐使用 Git 克隆官方仓库，或直接下载官方发布包并解压到本地目录。
**安装后端依赖：**建议先创建 Python 虚拟环境，再安装后端项目所需的依赖包。
**安装前端：**进入前端目录执行依赖安装和静态资源构建；若使用已构建好的发布包，可跳过此步骤。
**下载模型：**在联网环境下一次性下载声音、数字人形象和推理模型，并检查文件完整性。
**启动服务：**运行项目启动脚本，成功后通过本地地址访问 HeyGem 操作界面。
**创建数字人：**上传人物视频或图片，完成面部裁剪、音色选择和信息保存，生成可复用的数字人分身。
**生成视频：**选择数字人、音色、背景和口播脚本，设置画面与输出参数后离线合成直播视频。

1. 为什么选择本地部署 HeyGem

HeyGem 是一款面向数字人分身创建与视频生成的开源工具。把 HeyGem 部署到本地后，你可以不依赖云端接口，离线完成数字人形象克隆、脚本驱动和视频合成，特别适合对数据隐私、版权素材和网络稳定性有要求的直播、口播视频创作场景。

相比在线数字人平台，本地部署的核心优势在于：素材和生成结果都保留在自己的设备上，生成过程不受公网波动影响，并且可以反复调整脚本、音色和背景，直到输出满意为止。

2. 部署前需要准备什么

开始安装之前，建议先检查本机是否满足以下条件。不同版本的 HeyGem 对硬件要求会有所调整，具体以官方文档为准。

项目	最低建议	推荐配置
操作系统	Windows 10 / Ubuntu 20.04+	Windows 11 / Ubuntu 22.04
显卡	NVIDIA 8GB 显存	NVIDIA 12GB 显存以上
内存	16GB	32GB
硬盘空间	50GB 可用空间	100GB 以上，推荐 SSD
软件环境	Python 3.10、Node.js 18、Git	Python 3.10、Node.js 20、CUDA 12.x

还需要提前准备好 NVIDIA 显卡驱动、CUDA 工具包以及 Python、Node.js、Git 等基础环境。如果只是体验流程，也可以先使用官方提供的打包版本或 Docker 镜像，减少手动配置成本。

2.1 使用 Docker 快速体验

如果你只是先跑通流程，或不想在本机完整安装 Python、Node.js 和 CUDA 等环境，可以优先使用官方提供的 Docker 镜像。下面是一条常见的启动命令序列，涉及拉取镜像、运行容器、映射端口和挂载模型目录。

bash 复制代码

# 拉取 HeyGem 官方镜像
docker pull heygem/heygem:latest
创建本地模型目录，后续下载的模型文件会保存在这里
mkdir -p ./models
运行容器：映射 Web 端口，挂载模型和输出目录，并启用 GPU
docker run -d 

--name heygem 

--gpus all 

-p 7860:7860 

-v $(pwd)/models:/app/models 

-v $(pwd)/output:/app/output 

heygem/heygem:latest

容器启动后，用浏览器访问 http://127.0.0.1:7860 即可打开 HeyGem 操作界面。模型文件会落入宿主机的 models 目录，生成的视频默认保存到 output 目录，后续即使删除容器，这些本地文件也不会丢失。

Docker 与手动部署的适用场景差异

**Docker 部署：**依赖已经封装在镜像里，环境隔离好，适合快速体验、测试验证、多台机器保持一致的部署方式；缺点是镜像体积较大，GPU 相关的 Doker 配置需要额外确认，排查源码问题时不如手动部署直观。
**手动部署：**需要自行准备 Python、Node.js、CUDA 等环境，步骤更多，但适合需要阅读源码、二次开发、修改后端逻辑或精细控制依赖版本的场景。
**选择建议：**如果目标是快速跑通数字人生成流程，建议先走 Docker；如果后续要做深度定制、插件开发或生产环境精细调优，再切换到手动部署或基于 Docker 二次构建自己的镜像。

3. 获取 HeyGem 项目代码

推荐通过 Git 克隆官方仓库，保证代码完整且方便后续更新。克隆前请确认网络可以正常访问代码托管平台。

bash 复制代码

git clone https://github.com/HeyGem/HeyGem.git
cd HeyGem

如果你更习惯使用图形化方式，也可以直接下载官方发布的压缩包并解压到本地目录。后续命令都在项目根目录下执行。

4. 安装后端依赖

为了避免污染系统 Python 环境，建议先创建独立的虚拟环境。Windows 和 Linux 的激活命令略有区别。

bash 复制代码

# 创建虚拟环境
python -m venv venv
Windows 激活
venv\Scripts\activate
Linux / macOS 激活
source venv/bin/activate
安装后端依赖
pip install -r requirements.txt

如果安装过程中提示缺少编译工具或某个包版本冲突，可以根据报错信息调整 Python 版本，或使用官方推荐的依赖锁定文件。请优先以仓库 README 中的要求为准。

5. 安装前端页面

HeyGem 通常包含一个可视化操作界面。完成后端依赖安装后，还需要进入前端目录安装依赖并构建静态资源。

bash 复制代码

cd web
npm install
npm run build
cd ..

如果你下载的是已经构建好的发布包，可能不需要执行上面的前端构建步骤，直接运行启动脚本即可。

6. 下载数字人模型文件

首次使用前需要下载声音、数字人形象或推理模型。离线部署的关键在于：先在联网环境下把所有模型一次性下载完整，之后断网也能正常生成。

bash 复制代码

# 创建模型目录
mkdir -p models
按官方说明运行下载脚本，或手动下载模型文件并放入 models 目录
python scripts/download_models.py

下载完成后建议检查模型文件体积和目录结构是否完整，避免启动后因缺失检查点文件而报错。

7. 启动 HeyGem 服务

完成依赖和模型准备后，可以在项目根目录启动服务。启动成功后，终端会输出本地访问地址。

bash 复制代码

python app.py

看到类似 Running on http://127.0.0.1:7860 的提示后，用浏览器打开该地址即可进入 HeyGem 的操作界面。

8. 创建你的数字人分身

进入操作界面后，通常需要先完成角色创建。流程一般包括：

上传一段清晰、正面、光线充足的人物视频或图片；
根据提示裁剪出适合生成数字人的面部区域；
选择音色，可以上传自己的语音样本，也可以使用内置音色；
填写角色名称和基础信息，保存数字人资产。

创建过程可能持续几分钟到十几分钟，具体时间取决于显卡性能和素材时长。完成后，你的数字人分身会以本地文件形式保存，后续可以反复调用。

9. 离线生成数字人直播视频

数字人创建成功后，就可以在本地生成直播口播视频。你只需要准备一段台词或口播脚本，例如：

欢迎来到直播间，今天我们为大家带来一款适合家用场景的智能设备，接下来我会详细介绍它的功能和优惠信息。

在界面中选择对应的数字人、音色和背景，再把脚本粘贴到文本框中，设置画面比例、语速和输出目录，点击生成即可。整个过程可以不依赖公网，适合断网环境下的内容生产。

如果熟悉命令行，也可以使用脚本方式生成：

bash 复制代码

python generate.py \
  --avatar models/avatar_demo.pt \
  --text "欢迎来到直播间，今天为大家介绍一款新产品" \
  --voice models/voice_demo.pt \
  --output output/live_demo.mp4

以上参数名称仅为示例，不同版本的 HeyGem 可能有所不同，请以官方文档或项目内帮助信息为准。

实战案例：带货口播脚本

下面以一款家用智能空气炸锅为例，展示完整的带货口播脚本。实际使用时，只需要把产品名称、核心卖点、价格和活动信息替换成你自己的商品。

1. 开场

欢迎新老朋友来到直播间，今天给大家带来一款真正能帮你省时间、少油烟的厨房好物。如果你平时没空做菜，又不想点外卖，这款智能空气炸锅一定不要错过。

**视频画面建议：**数字人正面半身出镜，微笑看向镜头，背景使用干净明亮的厨房或纯色背景；首屏可以叠加商品名称大字标题，快速点明直播主题。

2. 产品介绍

这款空气炸锅内置十二种智能菜单，一键就能完成烤鸡翅、炸薯条、烘蛋挞；它采用高速热风循环技术，不用大量食用油也能做出外酥里嫩的口感，而且内胆不粘、清洗特别方便。

**视频画面建议：**数字人口播过程中，画面右下角插入商品近景图或使用视频素材；讲到具体功能时，可以切换商品细节图，让观众清楚看到操作面板和成品效果。

3. 优惠说明

今天直播间下单，不需要大几百，也不用好几百，专属粉丝价只要一百九十九元。再额外赠送一份电子食谱和专用取架，数量有限，先到先得。

**视频画面建议：**商品图旁边出现价格标签、赠品图标和限时倒计时，强化促销氛围；数字人语速可以稍微放慢，让价格和赠品信息更容易被记住。

4. 引导下单

家人们，库存已经不多了，喜欢的直接点击下方购物袋下单。现在拍下，我们会优先安排发货，让你早一点用上这款省心又省力的厨房神器。

**视频画面建议：**数字人做一个自然的手势引导，画面底部显示"点击下单""立即购买"等行动提示，帮助用户快速完成转化。

生成参数推荐值

参数	推荐值	说明
画面比例	9:16 或 16:9	发布到抖音、快手等平台可选 9:16；视频号或横屏直播可选 16:9
分辨率	1920×1080（横屏）或 1080×1920（竖屏）	保证人物和商品细节清晰
帧率	30fps	画面流畅，文件体积适中
语速	1.0～1.1 倍	保持自然口播节奏，避免过快影响听感
时长	60～90 秒	符合短视频带货节奏，信息密度适中
背景	纯色或家居场景	减少背景干扰，突出数字人和商品
输出格式	MP4（H.264）	兼容性好，便于二次上传和平台分发

10. 常见问题与排错

**显存不足：**可以降低生成分辨率、减少视频时长，或关闭不必要的后台程序。部分版本支持半精度推理，能有效降低显存占用。
**CUDA 报错：**检查显卡驱动、CUDA 和 PyTorch 版本是否匹配，必要时重新安装对应版本的 PyTorch。
**端口被占用：**如果 7860 端口无法访问，可以在启动配置中指定其他端口，或先结束占用该端口的进程。
**模型加载失败：**确认模型文件已放入正确目录，并检查文件哈希或完整性，避免下载中断导致文件损坏。
**生成视频没有声音：**检查音色文件是否加载成功，并确认系统已安装正确的编解码组件。

11. 结语

本地部署 HeyGem 后，你可以把数字人内容生产完全放在自己的设备上，既能保护素材隐私，也能在断网环境中稳定输出直播口播视频。初次部署建议严格按照官方文档操作，先跑通最小流程，再逐步调整角色形象、音色和画面效果。

如果在部署中遇到新的问题，优先查看官方仓库的 Issues 和文档更新，通常能快速找到对应解决方案。