🚀【超詳細】基于 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 安裝，避免源碼編譯坑。
)
