🚀【超详细】基于 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
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
升级安装工具，防止后续编译或安装失败：
pip install --upgrade pip setuptools -i https://pypi.tuna.tsinghua.edu.cn/simple
🔥 三、安装 PyTorch 2.5.1（支持 CUDA 12.4）
✅ 官方推荐安装命令如下：
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 支持：
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
预期输出（只要 True 就代表 GPU 可以用了🔥）：
2.5.1
True
📁 五、安装项目依赖（requirements.txt）
⚠️ 注意：一定要先装好 PyTorch 再执行这步！
# 先补装一些构建时依赖，防止报错
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.11cu12→ CUDA 12.xtorch2.5→ PyTorch 2.5linux_x86_64→ 64 位 Linux
-
下载该
.whl文件并安装：pip install ./flash_attn-xxx.whl
方案二：临时切换为官方 PyPI 源安装（避免清华镜像导致源码安装）
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
执行：
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创建了这个镜像，后续可以直接用它启动容器，避免重复配置。
下面命令基于该镜像启动容器：
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
或者增加共享内存的启动命令（避免显存分配问题）：
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
🛠 八、容器内环境初始化及依赖安装示例
apt update
apt install python3-pip libgl1-mesa-glx -y
ln -s /usr/bin/pip3 /usr/bin/pippip 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 机器）
lspci | grep -i nvidia
🚀 十、示例命令：运行 Wan2.1 生成任务
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."
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 安装，避免源码编译坑。
)
