企业官网建设流程全解析

• 人工智能
• 大模型
• 媒体生成
• 多模态
• 视频
• 本地部署

本指南以仓库 INSTALL.md 为骨架，完整讲解 Wan2.1 的两种主流安装方式（pip 与 Poetry）、flash-attn 这类 CUDA 扩展依赖的编译问题处理方案，以及安装完成后如何通过generate.py、pytest与代码格式化工具验证环境是否可用。读完本文，你将能够在自己的 GPU 机器上从零搭建 Wan2.1 推理环境，并独立排查安装过程中最常见的报错。

一、安装前的环境准备

Wan2.1 是一个面向大规模视频生成的开源模型套件（Text-to-Video、Image-to-Video、First-Last-Frame-to-Video、Text-to-Image、VACE 等任务），其 Python 侧依赖由 pyproject.toml 统一声明。安装前请确认以下前提：

• Python 版本：requires-python = ">=3.10,<4.0"，即建议使用 Python 3.10、3.11 或 3.12（见 pyproject.toml）。
• PyTorch 版本：torch>=2.4.0，同时配套torchvision>=0.19.0。安装 PyTorch 时应选择与本地 CUDA 版本匹配的 wheel，可通过 PyTorch 官方 index 先行安装。
• GPU 与显存：不同规模模型对显存要求差异很大（T2V-1.3B 约 8.19 GB 显存即可运行，14B 模型建议多卡或开启 offload），详见下文「运行模型」一节。
• 获取代码：克隆本仓库（或下载源码压缩包）并进入项目根目录，后续所有安装与运行命令均在该目录下执行。

准备模型权重

安装完成只是第一步，运行推理还需要先下载对应任务的模型权重。README 中的模型清单如下（权重需存放为本地目录，供--ckpt_dir引用）：

可使用 huggingface-cli 下载（huggingface-cli属于 dev 依赖组，pip install .[dev]后即自带）：

huggingface-cli download Wan-AI/Wan2.1-T2V-14B --local-dir ./Wan2.1-T2V-14B

国内网络环境也可使用 modelscope-cli：

pip install modelscope modelscope download Wan-AI/Wan2.1-T2V-14B --local_dir ./Wan2.1-T2V-14B

二、方式一：使用 pip 安装

在仓库根目录执行：

pip install . pip install .[dev] # 同时安装开发工具（pytest、black、flake8、isort、mypy、huggingface-hub[cli]）

• pip install .会根据 pyproject.toml 的[project]段落安装名为wan的 Python 包（[tool.setuptools] packages = ["wan"]，即wan/目录下的全部模块，包括 wan/configs、wan/modules、wan/utils 与各任务推理入口 wan/text2video.py、wan/image2video.py 等），同时自动解析dependencies中声明的一级依赖。
• pip install .[dev]额外安装[project.optional-dependencies]的dev组，用于后续测试与代码格式化。

核心依赖清单（与 requirements.txt 完全一致）如下：

说明：若你更习惯传统方式，也可直接执行pip install -r requirements.txt，其依赖内容与 pyproject 中的dependencies保持一致，两者择一即可。

三、方式二：使用 Poetry 安装

如果你使用 Poetry 管理 Python 项目，INSTALL.md 推荐的方式是：

poetry install

前置条件是在系统中安装好 Poetry 并确保python3.10+可用。poetry install会依据 pyproject.toml 创建/复用虚拟环境并安装全部依赖（含wan包本体）。之后的运行统一通过poetry run前缀进入虚拟环境执行，例如：

poetry run python generate.py --task t2v-14B --size '1280x720' --ckpt_dir ./Wan2.1-T2V-14B --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

处理flash-attn安装问题

flash_attn属于需要现场编译 CUDA 扩展的包，在 Poetry 的构建隔离（PEP 517 build isolation）机制下，若编译环境缺失或工具链不匹配，常出现构建失败。INSTALL.md 给出两种修复方案。

方案 A：关闭构建隔离安装（推荐）

poetry run pip install --upgrade pip setuptools wheel poetry run pip install flash-attn --no-build-isolation poetry install

先升级构建工具，再用--no-build-isolation复用当前环境中已就绪的编译依赖完成 flash-attn 安装，最后再执行poetry install补齐其余依赖。由于flash_attn同时也被声明在 pyproject 的dependencies中，先单独装好它可避免后续poetry install再次触发源码构建。

方案 B：从 Git 源码安装（备选）

poetry run pip install git+https://github.com/Dao-AILab/flash-attention.git

直接从 flash-attention 的源码仓库安装最新提交，适合希望通过源码打补丁或需要特定分支的场景。

实战提示：无论哪种方式，编译 flash-attn 都要求机器具备与 PyTorch 匹配的 CUDA 工具链（nvcc 可用）。若反复失败，可先确认nvidia-smi与python -c "import torch; print(torch.version.cuda)"输出一致，再重试方案 A。

四、安装后验证：运行第一个视频生成任务

INSTALL.md 推荐的验证命令是：

poetry run python generate.py --task t2v-14B --size '1280x720' --ckpt_dir ./Wan2.1-T2V-14B --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

如果你用 pip 安装，去掉poetry run前缀直接执行：

python generate.py --task t2v-14B --size 1280*720 --ckpt_dir ./Wan2.1-T2V-14B --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

关键命令行参数解析

上述命令中涉及的参数以及 generate.py 中更多可用参数如下（对应_parse_args实现，见 generate.py）：

其中--task、--size的合法组合在运行时还会被二次校验：_validate_args会依据SUPPORTED_SIZES检查分辨率合法性，例如t2v-1.3B仅支持480*832与832*480，传其他尺寸会直接报错（见 generate.py 与 wan/configs/init.py）。

显存不足（OOM）时的标准解法

在消费级显卡上运行 14B 模型时，README 推荐的组合是同时开启模型 offload 与 T5 CPU 卸载：

python generate.py --task t2v-1.3B --size 832*480 --ckpt_dir ./Wan2.1-T2V-1.3B --offload_model True --t5_cpu --sample_shift 8 --sample_guide_scale 6 --prompt "Two anthropomorphic cats in comfy boxing gear and bright gloves fight intensely on a spotlighted stage."

经验参数：T2V-1.3B 建议设置--sample_guide_scale 6，--sample_shift可在 8～12 范围内根据生成效果调节。

输出结果说明

生成结束后，generate()会在主进程（rank 0）保存结果：图像任务输出.png，视频任务输出.mp4。视频写入由 wan/utils/utils.py 中的cache_video完成，使用imageio+libx264编码，帧率取配置中的sample_fps = 16（见 wan/configs/shared_config.py）。若未指定--save_file，文件名会自动拼接任务、尺寸、并行规模、提示词片段与时间戳（见 generate.py）。

安装验证通过后，如需运行 i2v、flf2v、VACE、t2i 等其他任务，可直接参考 README.md 的 Quickstart 章节，或使用仓库内置的 Gradio 界面（如 gradio/t2v_14B_singleGPU.py、gradio/i2v_14B_singleGPU.py、gradio/vace.py）。多卡场景则通过torchrun+ FSDP（--dit_fsdp --t5_fsdp）+ xDiT USP（--ulysses_size/--ring_size）加速，需额外安装xfuser>=0.4.1，具体命令同样见 README.md。

五、运行测试套件验证安装完整性

INSTALL.md 提供了两条验证命令：

pytest tests/

pytest属于 dev 依赖组，需先执行pip install .[dev]或poetry install（含 dev 组）方可使用。

仓库还提供了一套端到端的冒烟测试脚本 tests/test.sh，其用法记录在 tests/README.md 中：

bash ./test.sh <local model dir> <gpu number>

• 第一个参数指向存放模型的目录，要求其中已包含 Wan2.1-T2V-1.3B、Wan2.1-T2V-14B、Wan2.1-I2V-14B-480P、Wan2.1-I2V-14B-720P 等权重子目录；
• 第二个参数指定参与多卡测试的 GPU 数量。

脚本会依次执行 t2i-14B、t2v-1.3B、t2v-14B、i2v-14B（480P/720P）、vace-1.3B 的单卡与多卡推理，并覆盖local_qwen与dashscope两种 prompt 扩展路径（后者仅在设置了DASH_API_KEY环境变量时执行）。这是对安装结果最直接的端到端验证：只要所有任务跑通，说明依赖、权重与多卡环境均已就绪。

六、代码风格检查与格式化

INSTALL.md 给出的格式化命令为：

black . isort .

这两项工具同样来自 dev 依赖组。项目在 pyproject.toml 中预置了风格约束：

• [tool.black] line-length = 88；
• [tool.isort] profile = "black"，保证排序风格与 black 一致；
• [tool.mypy] strict = true，供静态类型检查使用。

另外，仓库根目录的 Makefile 提供了make format目标，其内部使用isort与yapf对generate.py、gradio/、wan/下的 Python 文件统一格式化。三种工具（black / isort / yapf）并存是该项目兼顾社区风格与自身规范的工程实践，日常开发以 INSTALL.md 推荐的black .+isort .为准即可。

七、常见问题速查

小结

从pip install .到poetry install，再到 flash-attn 的两种修复方案与generate.py推理验证，本文完整覆盖了 INSTALL.md 的全部安装流程，并补充了 pyproject.toml、generate.py、tests/test.sh 等源码级细节。完成上述步骤并跑通一次 t2v-14B 推理后，你的 Wan2.1 环境即已就绪，可以进一步尝试 i2v、flf2v、VACE 等更多任务，或在 gradio/ 目录下启动本地 Web 界面进行交互式生成。

• 人工智能
• 大模型
• 媒体生成
• 多模态
• 视频
• 本地部署