Heygem 数字人系统 Linux 环境依赖安装步骤

这个步骤会更新系统里所有的软件包到最新版本，确保系统安全稳定。

3.2 安装编译工具和基础库

Heygem 系统需要一些编译工具来构建 Python 包，还需要一些系统库来处理多媒体文件：

# Ubuntu/Debian 系统
sudo apt install -y build-essential cmake git wget curl
sudo apt install -y libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev
sudo apt install -y libffi-dev liblzma-dev libncursesw5-dev libgdbm-dev libnss3-dev
sudo apt install -y libssl-dev libffi-dev libxml2-dev libxslt1-dev libjpeg-dev
sudo apt install -y libpng-dev libtiff-dev libavcodec-dev libavformat-dev
sudo apt install -y libswscale-dev libv4l-dev libxvidcore-dev libx264-dev
sudo apt install -y libatlas-base-dev gfortran python3-dev python3-pip python3-venv

# CentOS/RHEL 系统
sudo yum groupinstall -y "Development Tools"
sudo yum install -y cmake git wget curl
sudo yum install -y openssl-devel bzip2-devel readline-devel sqlite-devel
sudo yum install -y libffi-devel xz-devel ncurses-devel gdbm-devel nss-devel
sudo yum install -y libxml2-devel libxslt-devel libjpeg-turbo-devel
sudo yum install -y libpng-devel libtiff-devel ffmpeg-devel
sudo yum install -y atlas-devel gcc-gfortran python3-devel python3-pip

这些包看起来很多，但它们各自有重要作用：

• build-essential / Development Tools：C/C++编译工具链
• cmake：项目构建工具
• libssl-dev / openssl-devel：加密通信支持
• libjpeg-dev / libjpeg-turbo-devel：图片处理支持
• ffmpeg-devel：视频处理支持
• python3-dev / python3-devel：Python 开发头文件

3.3 安装 FFmpeg（视频处理核心）

FFmpeg 是处理视频文件的核心工具，Heygem 系统依赖它来读取、处理和生成视频：

# Ubuntu/Debian 系统（方法一：从官方源安装）
sudo apt install -y ffmpeg
# 方法二：如果官方源版本太老，可以从 PPA 安装
sudo add-apt-repository ppa:jonathonf/ffmpeg-4 -y
sudo apt update
sudo apt install -y ffmpeg

# CentOS/RHEL 系统
sudo yum install -y epel-release
sudo rpm -v --import http://li.nux.ro/download/nux/RPM-GPG-KEY-nux.ro
sudo rpm -Uvh http://li.nux.ro/download/nux/dextop/el7/x86_64/nux-dextop-release-0-5.el7.nux.noarch.rpm
sudo yum install -y ffmpeg ffmpeg-devel

安装完成后，验证 FFmpeg 是否安装成功：

ffmpeg -version

你应该能看到 FFmpeg 的版本信息，如果显示'command not found'，说明安装失败了，需要检查上面的步骤。

4. Python 环境配置

Heygem 系统是用 Python 编写的，所以我们需要配置一个专门的 Python 环境。我推荐使用 Miniconda 来管理 Python 环境，这样不同项目的依赖不会互相冲突。

4.1 安装 Miniconda

Miniconda 是一个轻量级的 Python 环境管理工具，比完整的 Anaconda 更节省空间：

# 下载 Miniconda 安装脚本
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
# 运行安装脚本
bash miniconda.sh -b -p $HOME/miniconda
# 将 conda 添加到环境变量
echo 'export PATH="$HOME/miniconda/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 验证安装
conda --version

安装过程中，安装脚本会问你是否要初始化 conda，建议选择'yes'，这样每次打开终端 conda 都会自动激活。

4.2 创建专门的 Python 环境

我们不建议在系统 Python 中直接安装 Heygem 的依赖，而是创建一个独立的环境：

# 创建名为 heyge 的 Python 环境，使用 Python 3.9
conda create -n heyge python=3.9 -y
# 激活环境
conda activate heyge
# 验证 Python 版本
python --version

为什么选择 Python 3.9？因为很多深度学习库在 3.9 上最稳定。如果你要用其他版本，记得检查相关库的兼容性。

4.3 升级 pip 和设置镜像源

国内的网络环境访问 PyPI 可能比较慢，我们可以设置国内的镜像源来加速下载：

# 升级 pip 到最新版本
python -m pip install --upgrade pip
# 设置清华镜像源（国内用户推荐）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
# 也可以设置阿里云镜像源
# pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
# pip config set global.trusted-host mirrors.aliyun.com

设置镜像源后，pip 下载包的速度会快很多。

5. 深度学习框架安装

Heygem 系统底层使用了深度学习框架来处理视频生成任务。这部分安装比较复杂，但我会带你一步步完成。

5.1 安装 PyTorch

PyTorch 是当前最流行的深度学习框架之一。安装时要注意版本匹配：

# 首先查看 CUDA 版本（如果有 GPU 的话）
nvidia-smi | grep "CUDA Version"
# 根据你的 CUDA 版本选择安装命令
# 如果没有 GPU 或者 CUDA 版本未知，安装 CPU 版本
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 如果有 GPU 且 CUDA 版本是 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# 如果有 GPU 且 CUDA 版本是 12.1
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

安装完成后，验证 PyTorch 是否能正常使用：

# 创建一个 test_pytorch.py 文件
cat > test_pytorch.py << 'EOF'
import torch
print(f"PyTorch 版本：{torch.__version__}")
print(f"CUDA 是否可用：{torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU 设备数量：{torch.cuda.device_count()}")
    print(f"当前 GPU: {torch.cuda.current_device()}")
    print(f"GPU 名称：{torch.cuda.get_device_name(0)}")
EOF
# 运行测试
python test_pytorch.py

如果看到 CUDA 可用，说明 GPU 加速已经配置好了。如果不可用，但你有 GPU，可能需要检查 CUDA 驱动安装。

5.2 安装其他深度学习相关库

除了 PyTorch，Heygem 还需要一些其他库：

# 安装基础的科学计算库
pip install numpy scipy pandas matplotlib
# 安装图像处理库
pip install opencv-python opencv-python-headless pillow
# 安装音频处理库
pip install librosa soundfile pydub
# 安装视频处理库
pip install moviepy imageio imageio-ffmpeg
# 安装人脸检测和特征点库
pip install dlib face-alignment mediapipe

这里有个小技巧：opencv-python-headless 是不带 GUI 功能的 OpenCV 版本，适合在服务器上使用。如果你需要在本地显示图片，可以安装 opencv-python。

5.3 处理可能出现的安装问题

安装 dlib 时可能会遇到编译错误，因为它需要 CMake 和 C++ 编译器。如果安装失败，可以尝试：

# 先安装 CMake（如果还没安装的话）
conda install -c conda-forge cmake -y
# 然后安装 dlib
pip install dlib

如果还是失败，可以尝试从 conda 安装：

conda install -c conda-forge dlib -y

6. Heygem 系统特定依赖

现在我们来安装 Heygem 系统本身的依赖。这些包是系统运行所必需的。

6.1 安装 Web 框架和工具

Heygem 提供了一个 Web 界面，所以需要安装 Web 相关的库：

# 安装 Gradio - Web 界面框架
pip install gradio
# 安装 FastAPI 和 Uvicorn - 后端 API 服务
pip install fastapi uvicorn
# 安装其他 Web 相关工具
pip install aiofiles python-multipart httpx

Gradio 是一个专门为机器学习模型设计 Web 界面的库，它让创建交互式界面变得非常简单。

6.2 安装系统功能依赖

这些是 Heygem 系统核心功能所需的库：

# 安装异步任务处理
pip install celery redis
# 安装配置文件处理
pip install pyyaml toml
# 安装进度条显示
pip install tqdm rich
# 安装文件操作工具
pip install watchdog pathlib
# 安装日志和调试工具
pip install loguru ipython

6.3 安装可选但推荐的依赖

这些不是必须的，但能让系统运行得更好：

# 安装性能优化工具
pip install numba
# 安装数据验证库
pip install pydantic
# 安装类型提示支持
pip install typing-extensions
# 安装开发工具
pip install black flake8 isort pre-commit

7. 验证安装和常见问题解决

所有依赖都安装完成后，我们需要验证一下是否都安装成功了。

7.1 创建验证脚本

创建一个 Python 脚本来检查所有关键依赖：

# 创建 check_deps.py 文件
cat > check_deps.py << 'EOF'
import importlib
import sys
required_packages = [
    "torch", "numpy", "cv2", "gradio", "librosa", "moviepy", "dlib", "celery", "yaml", "tqdm", "PIL"
]
print("=" * 50)
print("依赖包检查结果")
print("=" * 50)
all_ok = True
for package in required_packages:
    try:
        # 特殊处理 OpenCV，它的导入名是 cv2
        if package == "cv2":
            import cv2
            version = cv2.__version__
        # 特殊处理 PIL
        elif package == "PIL":
            from PIL import Image
            version = Image.__version__
        # 特殊处理 yaml
        elif package == "yaml":
            import yaml
            version = yaml.__version__
        else:
            module = importlib.import_module(package)
            version = getattr(module, "__version__", "未知版本")
        print(f"✓ {package:20} 版本：{version}")
    except ImportError as e:
        print(f"✗ {package:20} 未安装或导入失败：{e}")
        all_ok = False
    except Exception as e:
        print(f"? {package:20} 检查时出错：{e}")
        all_ok = False
print("=" * 50)
if all_ok:
    print("所有依赖包检查通过！")
else:
    print("部分依赖包检查失败，请重新安装。")
sys.exit(1)
# 检查 CUDA 是否可用
try:
    import torch
    if torch.cuda.is_available():
        print(f"\nGPU 信息:")
        print(f"  设备数量：{torch.cuda.device_count()}")
        for i in range(torch.cuda.device_count()):
            print(f"  设备{i}: {torch.cuda.get_device_name(i)}")
    else:
        print("\n警告：CUDA 不可用，系统将使用 CPU 运行，速度会较慢。")
except:
    print("\n警告：无法检查 CUDA 状态")
EOF
# 运行检查脚本
python check_deps.py

如果所有依赖都显示为✓，说明安装成功了。如果有✗，需要根据提示重新安装对应的包。

7.2 常见问题及解决方法

在安装过程中，你可能会遇到一些问题。这里列出一些常见问题及其解决方法：

问题 1：pip 安装超时或失败

# 解决方法：增加超时时间，使用国内镜像源
pip install --default-timeout=1000 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple

问题 2：内存不足导致编译失败

# 解决方法：增加交换空间
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 永久生效
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

问题 3：权限问题

# 解决方法：使用虚拟环境，避免使用 sudo pip
# 如果必须使用系统 Python，可以尝试
pip install --user 包名

问题 4：特定包版本冲突

# 解决方法：先卸载冲突的包，然后重新安装
pip uninstall 包名 -y
pip install 包名==特定版本

7.3 环境备份和恢复

配置好的环境很宝贵，建议备份一下：

# 导出环境配置
pip freeze > requirements.txt
conda list --export > conda_packages.txt
# 备份 conda 环境
conda env export -n heyge > heyge_environment.yml
# 恢复环境时使用
conda env create -f heyge_environment.yml

8. 总结：从依赖安装到系统运行

8.1 安装过程回顾

我们一步步完成了 Heygem 数字人系统的所有依赖安装。回顾一下整个过程：

1. 系统准备：检查 Linux 版本，确保硬件资源足够
2. 基础依赖：安装编译工具、系统库和 FFmpeg
3. Python 环境：用 Miniconda 创建独立环境，配置镜像源
4. 深度学习框架：安装 PyTorch 和相关计算库
5. 系统特定依赖：安装 Web 界面和功能所需的 Python 包
6. 验证安装：检查所有依赖是否正常

这个过程看起来步骤不少，但每一步都有它的必要性。深度学习应用就是这样，它依赖很多底层的库和工具。

8.2 下一步：启动 Heygem 系统

依赖安装完成后，你就可以开始使用 Heygem 系统了。基本的启动步骤是：

# 1. 激活 conda 环境
conda activate heyge
# 2. 克隆或下载 Heygem 系统代码
git clone https://github.com/your-repo/heygem.git
cd heygem
# 3. 安装系统本身的依赖（如果有 requirements.txt）
pip install -r requirements.txt
# 4. 启动系统
bash start_app.sh

启动后，在浏览器中访问 http://localhost:7860 就能看到 Heygem 的 Web 界面了。

8.3 使用建议和优化

使用建议如下：

1. 首次运行较慢：第一次启动时，系统需要下载预训练模型，可能需要一些时间
2. GPU 加速：如果有 NVIDIA GPU，确保安装了正确的 CUDA 驱动和 PyTorch CUDA 版本
3. 内存管理：处理长视频时，注意监控内存使用情况
4. 批量处理：Heygem 支持批量处理，合理利用这个功能能提高效率
5. 定期更新：关注项目的更新，及时更新依赖包

8.4 遇到问题怎么办？

如果在使用过程中遇到问题，可以：

1. 查看日志：日志文件通常包含详细的错误信息
2. 检查依赖：用我们创建的验证脚本检查依赖是否完整
3. 搜索错误：把错误信息复制到搜索引擎，通常能找到解决方案
4. 社区求助：在相关技术社区提问，提供详细的错误信息和环境信息

依赖安装是使用任何 AI 系统的第一步，也是最容易出问题的一步。通过这篇指南，希望你能顺利跨过这个门槛，开始体验 Heygem 数字人视频生成的强大功能。

记住，技术问题的解决往往需要耐心和细心。一步步来，遇到问题不要慌，按照错误提示和这篇指南的步骤排查，大多数问题都能解决。