✨通义万相 2.1（Wan2.1）环境搭建指南：基于 CUDA 12.4 + Python 3.11 + PyTorch 2.5.1 GPU加速实战

🚀【超详细】基于 CUDA 12.4 + Python 3.11 构建 Wan2.1 项目的集成推理环境（含 PyTorch 2.5.1 GPU 安装教程）

本文将一步一步带你搭建一个可用于构建和运行 Wan2.1 的深度学习环境 ，完全兼容 CUDA 12.4，并基于官方镜像 nvidia/cuda:12.4.0-devel-ubuntu22.04 和 Python 3.11。包括 PyTorch 安装、依赖处理、环境验证和常见问题解决，全程使用国内清华镜像加速。🚀

📦 基础环境说明

环境项	值
镜像	`nvidia/cuda:12.4.0-devel-ubuntu22.04`
Python	3.11（自定义安装）
包管理	`pip`（使用清华镜像）
加速工具包	`torch`, `flash-attn`, `packaging`, 等
用途	构建并运行 `Wan2.1` 模型项目（适配 GPU）

🔧 一、安装系统依赖 + Python 3.11

bash 复制代码

apt update && apt install -y \
    python3.11 python3.11-venv python3.11-dev python3-pip \
    build-essential cmake git curl wget

# 设置默认 python/pip（可选）
ln -sf /usr/bin/python3.11 /usr/bin/python
ln -sf /usr/bin/pip3 /usr/bin/pip

✅ 这样就完成了 Python 和基本构建工具的配置。

⬆️ 二、升级 pip 和 setuptools

升级安装工具，防止后续编译或安装失败：

bash 复制代码

pip install --upgrade pip setuptools -i https://pypi.tuna.tsinghua.edu.cn/simple

🔥 三、安装 PyTorch 2.5.1（支持 CUDA 12.4）

✅ 官方推荐安装命令如下：

bash 复制代码

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 \
  --index-url https://download.pytorch.org/whl/cu124 \
  --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

📌 解释：

--index-url: 从 PyTorch 官方 CUDA 12.4 仓库拉取核心库；
--extra-index-url: 其余依赖包走清华镜像，加速飞起🚄

✅ 四、验证 PyTorch 安装是否成功

执行下面命令确认版本 & GPU 支持：

bash 复制代码

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

预期输出（只要 True 就代表 GPU 可以用了🔥）：

复制代码

2.5.1
True

📁 五、安装项目依赖（requirements.txt）

⚠️ 注意：一定要先装好 PyTorch 再执行这步！

bash 复制代码

# 先补装一些构建时依赖，防止报错
pip install packaging -i https://pypi.tuna.tsinghua.edu.cn/simple

# 然后安装项目依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 六、关于 `flash_attn` 安装卡住问题详解（极其重要）

你可能遇到的问题是：

在执行 flash_attn 的 setup.py bdist_wheel 阶段时卡住，构建过程一直没有继续。

这通常是因为 FlashAttention 的源码编译依赖 CUDA 环境、编译器、内存资源 等多个条件，导致它在本地构建 .whl 时非常耗时甚至卡死。

🔍 可能的卡住原因

CUDA 环境不匹配或未安装

FlashAttention 强依赖 CUDA。若本地未正确配置 CUDA（或版本与 PyTorch 不匹配），编译时会卡住或失败。
没有 NVIDIA GPU 或未启用 GPU 驱动

无 GPU 的机器通常会直接卡死或失败。
内存/资源不足

编译 FlashAttention 需要大量 RAM 和 CPU 资源，资源不足时会卡住。
编译器问题（gcc 版本不兼容）

构建时使用 setuptools 和系统编译器，不兼容时可能无错误提示但构建失败。

✅ 推荐解决方案（优先级顺序）

方案一：手动安装预编译的 `.whl` 文件（强烈推荐）

访问预编译包页面：

https://github.com/Dao-AILab/flash-attention/releases
找到与你环境匹配的版本，例如：
复制代码
```
flash_attn-2.8.0.post2+cu12torch2.5cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
```
匹配内容包括：
- cp311 → Python 3.11
- cu12 → CUDA 12.x
- torch2.5 → PyTorch 2.5
- linux_x86_64 → 64 位 Linux
下载该 .whl 文件并安装：
bash 复制代码
```
pip install ./flash_attn-xxx.whl
```

方案二：临时切换为官方 PyPI 源安装（避免清华镜像导致源码安装）

bash 复制代码

pip install flash-attn --index-url https://pypi.org/simple

说明：清华镜像不缓存 GitHub 上的预编译 wheel，导致退回源码编译，容易卡住。

方案三：如果 FlashAttention 不是强依赖，尝试禁用或降级

如果某些包自动依赖 flash_attn，你也可以选择忽略或使用不依赖它的版本。

方案四（专业用户）：手动源码编译

确保满足：

Python 3.10/3.11
CUDA 11.8/12.x
PyTorch 2.5 且 torch.cuda.is_available() 返回 True
安装 ninja、gcc、nvcc

执行：

bash 复制代码

git clone https://github.com/Dao-AILab/flash-attention.git
cd flash-attention
pip install packaging
python setup.py install

🐳 七、使用 Docker 启动 Wan2.1 环境（镜像标签：wan2.1:1.0）

说明：wan2.1:1.0 镜像是基于上文步骤搭建好的环境，通过 Docker 容器提交生成的新镜像。

也就是说，你先在基础镜像中完成所有环境配置后，执行 docker commit 创建了这个镜像，后续可以直接用它启动容器，避免重复配置。

下面命令基于该镜像启动容器：

bash 复制代码

docker run -it --name wan2.1 --runtime=nvidia --gpus all --network=host \
  -v /data02/YangXian/code/Wan2.1-main:/Wan2.1-main \
  -v /data01/YangXian/models/Wan-AI:/Wan-AI \
  -w /Wan2.1-main wan2.1:1.0 bash

或者增加共享内存的启动命令（避免显存分配问题）：

bash 复制代码

docker run -it --name wan2.1.1 --runtime=nvidia --gpus all --network=host --shm-size=50g \
  -v /data02/YangXian/code/Wan2.1-main:/Wan2.1-main \
  -v /data01/YangXian/models/Wan-AI:/Wan-AI \
  -w /Wan2.1-main wan2.1:1.0 bash

🛠 八、容器内环境初始化及依赖安装示例

bash 复制代码

apt update
apt install python3-pip libgl1-mesa-glx -y
ln -s /usr/bin/pip3 /usr/bin/pip

pip install --upgrade pip setuptools -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install packaging modelscope "xfuser>=0.4.1" -i https://pypi.tuna.tsinghua.edu.cn/simple

# PyTorch 安装（示例）
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124

# 安装项目依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

⚙️ 九、检测 GPU 设备（判断是否为 GPU 机器）

bash 复制代码

lspci | grep -i nvidia

🚀 十、示例命令：运行 Wan2.1 生成任务

bash 复制代码

CUDA_VISIBLE_DEVICES=4,5,6,7 python3 generate.py --task flf2v-14B --size 1280*720 --ckpt_dir /Wan-AI/Wan2___1-FLF2V-14B-720P --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

bash 复制代码

CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 torchrun --nproc_per_node=8 generate.py --offload_model True --task flf2v-14B --size 1280*720 --ckpt_dir /Wan-AI/Wan2___1-FLF2V-14B-720P --first_frame examples/flf2v_input_first_frame.png --last_frame examples/flf2v_input_last_frame.png --dit_fsdp --t5_fsdp --ulysses_size 8 --ring_size 1 --prompt "CG animation style, a smallchest. The background shows a blue sky with white clouds under bright sunshine. The camera follows the bird upward, capturing its flight and the vastness of the sky from a close-up, low-angle perspective."

✅ 最终总结

🚀 完成以上所有步骤，你的 Wan2.1 项目环境就搭建完成了，可以放心训练和测试了！

遇到 flash_attn 卡住问题，务必优先选择预编译 .whl 安装，避免源码编译坑。

✨通义万相 2.1（Wan2.1）环境搭建指南：基于 CUDA 12.4 + Python 3.11 + PyTorch 2.5.1 GPU加速实战

🚀【超详细】基于 CUDA 12.4 + Python 3.11 构建 Wan2.1 项目的集成推理环境（含 PyTorch 2.5.1 GPU 安装教程）

📦 基础环境说明

🔧 一、安装系统依赖 + Python 3.11

⬆️ 二、升级 pip 和 setuptools

🔥 三、安装 PyTorch 2.5.1（支持 CUDA 12.4）

✅ 官方推荐安装命令如下：

✅ 四、验证 PyTorch 安装是否成功

📁 五、安装项目依赖（requirements.txt）

⚠️ 六、关于 flash_attn 安装卡住问题详解（极其重要）

🔍 可能的卡住原因

✅ 推荐解决方案（优先级顺序）

方案一：手动安装预编译的 .whl 文件（强烈推荐）

方案二：临时切换为官方 PyPI 源安装（避免清华镜像导致源码安装）

方案三：如果 FlashAttention 不是强依赖，尝试禁用或降级

方案四（专业用户）：手动源码编译

🐳 七、使用 Docker 启动 Wan2.1 环境（镜像标签：wan2.1:1.0）

🛠 八、容器内环境初始化及依赖安装示例

⚙️ 九、检测 GPU 设备（判断是否为 GPU 机器）

🚀 十、示例命令：运行 Wan2.1 生成任务

✅ 最终总结

⚠️ 六、关于 `flash_attn` 安装卡住问题详解（极其重要）

方案一：手动安装预编译的 `.whl` 文件（强烈推荐）