2026年4月

"Couldn't find ffmpeg or avconv - defaulting to ffmpeg, but may not work"

解决方法如下：

一、安装ffmpeg（已经安装可跳过）
安装ffmpeg
GitHub文档：https://github.com/BtbN/FFmpeg-Builds/releases/

环境变量配置
下载完压缩包之后，进行解压，将ffmpeg文件夹里的bin文件夹的路径复制一下。

==打开控制面板----系统和安全----系统----高级系统设置----环境变量----在系统变量里面找到Path，选中，点击编辑----新建----将复制的内容进行粘贴----确认。==
这样就完成了环境变量的配置。
检查配置是否成功
打开cmd，输入ffmpeg -version

硬件检查
首先执行：
nvidia-smi
注意看两处信息：

  • Driver Version：必须 ≥ 535（对应CUDA 12.1+）
  • CUDA Version：这是驱动支持的最大CUDA版本，不是你当前安装的版本

环境依赖
在安装 Wan2.2 之前，请确保系统满足以下依赖条件：

Python 版本：建议使用 Python 3.8 或更高版本。
PyTorch：必须安装 PyTorch 2.4.0 或更高版本，并支持 CUDA（推荐使用 CUDA 11.7 或更高版本）。
GPU 要求：
单 GPU 运行至少需要 80GB 显存。
多 GPU 运行支持 FSDP 和 DeepSpeed Ulysses 优化。

nvcc -V
确保输出中的版本号与PyTorch安装包一致。如果不符，去NVIDIA官网下载对应工具包，而不是只更新驱动。

经验提示：建议使用Docker镜像（如nvidia/cuda:12.4-devel-ubuntu22.04）来隔离环境，避免宿主机污染。

依赖包列表
以下是运行 Wan2.2 所需的核心依赖包（可通过 requirements.txt 安装）：
torch>=2.4.0
transformers>=4.30.0
diffusers>=0.20.0
flash_attn>=2.3.0
huggingface_hub
modelscope

安装步骤

  1. 克隆仓库
    首先，克隆 Wan2.2 的代码仓库到本地：
    git clone https://gitcode.com/hf_mirrors/Wan-AI/Wan2.2-I2V-A14B.git
    cd Wan2.2-I2V-A14B
  2. 安装依赖
    运行以下命令安装所有依赖包：
    pip install -r requirements.txt

如果 flash_attn 安装失败，可以先安装其他依赖，最后再单独安装 flash_attn：
pip install torch transformers diffusers huggingface_hub modelscope
pip install flash_attn

  1. 下载模型权重
    Wan2.2 提供了多种模型权重，用户可以根据需求选择下载。以下是两种下载方式：

使用 huggingface-cli 下载：
pip install "huggingface_hub[cli]"
huggingface-cli download Wan-AI/Wan2.2-I2V-A14B --local-dir ./Wan2.2-I2V-A14B

使用 modelscope-cli 下载：
pip install modelscope
modelscope download Wan-AI/Wan2.2-I2V-A14B --local_dir ./Wan2.2-I2V-A14B

  1. 验证安装
    完成安装后，可以通过以下命令验证环境是否配置成功：
    python -c "import torch; print(torch.__version__)"
    确保输出为 2.4.0 或更高版本。

通过以上步骤，用户可以顺利完成 Wan2.2 的环境配置，并开始使用其强大的视频生成功能。

Python环境：用Conda管理依赖，别让版本冲突毁掉一整天
虚拟环境不是可选项，而是必需品。尤其当你的服务器上还跑着Stable Diffusion或其他LLM服务时，Python依赖很容易“串门”。

创建专用环境：
conda create -n wan22-t2v-a14b python=3.10
conda activate wan22-t2v-a14b
为什么是Python 3.10？因为T5 tokenizer在3.11+存在序列化兼容问题，会导致加载失败。这不是官方文档会写的细节，但你在调试时一定会遇到。

接下来安装PyTorch——这里有个关键选择：
CUDA 12.1 用户
pip3 install torch==2.4.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

CUDA 12.2 或更高
pip3 install torch==2.4.0+cu122 torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu122

务必锁定2.4.0版本。新版本虽然性能更好，但Wan2.2的代码库尚未适配其新的分布式通信后端，可能导致FSDP初始化失败。

验证安装：
import torch
print(f"PyTorch: {torch.__version__}")
print(f"CUDA可用: {torch.cuda.is_available()}")
print(f"可见GPU: {torch.cuda.device_count()}")

如果输出中CUDA可用为False，请回头检查LD_LIBRARY_PATH是否包含CUDA路径：
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

模型下载与结构解析：不只是复制粘贴
使用ModelScope SDK下载模型：
modelscope download Wan-AI/Wan2.2-T2V-A14B --local_dir ./Wan2.2-T2V-A14B

这个过程通常需要半小时以上。你可以趁机看看模型内部结构：
./Wan2.2-T2V-A14B/
├── config.json # 模型架构定义
├── diffusion_pytorch_model-*.safetensors # DiT主干权重（分片存储）
├── text_encoder/ # T5-XXL 编码器
├── vae/ # 视频VAE解码器
├── tokenizer/ # 分词器配置
└── model_index.json # 组件映射表

重点留意.safetensors文件命名。有些镜像源会自动加上-bf16后缀，比如：
diffusion_pytorch_model-00001-of-00003-bf16.safetensors
但原始代码期望的是标准命名。如果不处理，会抛出FileNotFoundError。解决方法很简单：
for f in *.safetensors; do
mv "$f" "${f%-bf16.safetensors}.safetensors"
done
这条命令会批量去除-bf16后缀，避免后续加载失败。

推理策略：根据硬件灵活选择运行模式
单卡模式：实验调试的起点
如果你有一张A100或H100，可以直接运行基础命令：
python3 generate.py \
--task t2v-a14b \
--size 704*1280 \
--ckpt_dir ./Wan2.2-T2V-A14B \
--prompt "两只机械猫在赛博城市屋顶追逐打斗，霓虹灯光闪烁，雨夜氛围，电影质感"

注意分辨率格式：7041280代表竖屏短视频，适合抖音、快手等平台；若要横屏输出，改为1280704即可。

显存受限设备的“生存模式”
对于RTX 3090/4090用户，必须启用三项优化：

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

python3 generate.py \
--task t2v-a14b \
--size 704*1280 \
--ckpt_dir ./Wan2.2-T2V-A14B \
--offload_model True \
--t5_cpu \
--convert_model_dtype \
--prompt "一位舞者在极光下旋转，雪花飘落，慢动作镜头"

逐条解释：

  • --offload_model True：将部分Transformer层临时卸载到CPU，减少峰值显存占用
  • --t5_cpu：T5编码器本身就需要约18GB显存，强制其在CPU运行可节省大量资源
  • --convert_model_dtype：自动将FP32模型转为FP16/BF16，降低内存带宽压力
  • PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True：开启PyTorch 2.4的新特性，有效缓解显存碎片问题

实测效果：在RTX 4090上，关闭这些选项会立即触发OOM；开启后虽延长生成时间至近两分钟，但至少能跑通全流程。

多GPU分布式推理：通往高吞吐的关键路径
当你拥有4卡甚至8卡服务器时，就不能再用单进程模式了。否则不仅无法利用全部算力，还会因显存分布不均导致负载失衡。

使用torchrun启动FSDP（Fully Sharded Data Parallel）：

torchrun --nproc_per_node=8 generate.py \
--task t2v-a14b \
--size 1280*704 \
--ckpt_dir ./Wan2.2-T2V-A14B \
--dit_fsdp \
--t5_fsdp \
--ulysses_size 8 \
--prompt "太空舰队穿越虫洞，星云绚丽，粒子特效密集，科幻大片风格"

这里的--ulysses_size 8特别重要——它是DeepSpeed Ulysses张量并行机制，用于分割注意力头跨GPU计算。如果不加这一项，即使启用了FSDP，注意力层仍会在单卡上形成瓶颈。

性能对比（8×A100）：

  • 单卡顺序推理：~32秒/视频
  • 8卡FSDP + Ulysses：~9秒/视频（接近线性加速）

更重要的是，这种模式支持批量输入（batch inference），可显著提升API服务的QPS。

扩展应用：不只是“文生视频”
除了纯文本输入，Wan2.2还支持图生视频（Image-to-Video），这对产品演示、角色动画非常有用：

python3 generate.py \
--task t2v-a14b \
--size 704*1280 \
--ckpt_dir ./Wan2.2-T2V-A14B \
--image examples/i2v_input.jpg \
--prompt "让这个角色开始跳舞，背景逐渐变为舞台聚光灯"

模型会以输入图像为第一帧，结合文本描述生成后续动作序列。我们在某电商客户项目中用此功能制作商品展示动画，转化率提升了17%。

工程实践中的常见问题与应对策略
即使配置齐全，实际运行中仍可能遇到各种挑战：

  1. 显存溢出（CUDA Out of Memory）
    现象：模型加载时报错CUDA error: out of memory。
    原因：720P视频潜表示体积巨大，尤其在扩散步骤较多时中间缓存占用激增。
    解决方案：
  2. 启用FP16混合精度：torch.autocast("cuda")
  3. 使用梯度检查点：减少保存的中间激活值
  4. 分片加载模型权重：避免一次性载入全部参数

按显存容量分级应对：

显存 策略
<16GB 不推荐本地运行，建议调用云端API
16–24GB 启用--offload_model, --t5_cpu, --convert_model_dtype
24–48GB 可关闭卸载，仅保留dtype转换

48GB 全模型驻留GPU，最大化效率
额外技巧：降低帧数（默认16帧）或缩短上下文长度也能减负。

生产环境优先使用704x1280或1280x704，兼顾画质与效率。

  1. 生成结果不稳定
    现象：相同提示词多次生成结果差异大，动作跳跃或形变严重。
    建议做法：
  2. 固定随机种子（seed）确保一致性
  3. 添加风格锚点词，如“电影质感”、“慢动作”、“固定镜头”
  4. 在复杂指令中明确主谓宾结构，避免歧义
  5. 推理延迟过高
    现象：8秒视频生成耗时超过5分钟。
    优化方向：
  6. 升级到H100 GPU，利用FP8加速
  7. 启用torch.compile(model)编译模型图
  8. 减少扩散步数（从100步降至50步），换取速度提升
  9. 安全与合规风险
    由于模型具备强大生成能力，必须前置敏感内容过滤机制。建议在文本编码阶段引入关键词黑名单与语义检测模块，防止生成暴力、色情或政治相关内容。私有化部署时还需启用VPC隔离与操作日志审计。

应用前景：不止于“一键生成视频”
Wan2.2-T2V-A14B 的价值不仅在于技术先进性，更在于它正在重塑内容生产的底层逻辑。

在影视行业，导演可以用它快速生成动态分镜脚本，提前预览镜头语言；在数字营销领域，品牌方输入一句文案就能自动生成多个风格候选视频，大幅缩短创意迭代周期；在教育科普中，复杂的科学原理可以转化为直观动画，帮助学生理解抽象概念。

更重要的是，它可以与其他AIGC工具链无缝集成。比如：

  • 结合语音合成模型，自动为视频配上旁白；
  • 联动字幕生成系统，输出多语言版本；
  • 接入虚拟人驱动引擎，打造个性化IP形象。

未来，随着更高分辨率（1080P/4K）、更长时序（>30秒）版本的推出，这类模型有望成为元宇宙、游戏开发、虚拟偶像等新兴生态的核心生产力引擎。

对于开发者而言，现在正是掌握这一波技术红利的关键窗口期。与其等待“完美模型”的到来，不如先动手部署一个可用系统，在实践中理解延迟、显存、批处理之间的权衡。毕竟，真正的AI竞争力，从来不是某个单一模型，而是你能否把它变成稳定运转的生产力工具。

在conda环境创建时的yaml文件中，pip 下的 -e
git+https://github.com/huggingface/transformers.git@main#egg=transformers 命令表示从 Github 上获取 transformers 库的最新版本，并将其安装到当前环境中。具体含义如下：

-e：表示使用开发模式进行安装，将软件包安装为可编辑模式，以便在本地对其进行修改和调试。 git+https://github.com/huggingface/transformers.git@main：表示从 Github
上获取 transformers 库的最新版本，并且使用 Git 协议进行下载。
egg=transformers：表示将软件包命名为 "transformers"，以便在安装时能够识别它，并确保其与其他软件包不发生冲突。 通过执行此命令，可以在当前环境中安装并使用最新版本的
transformers 库。

按照上面的说法,所以我们第一步是clone项目:

git clone https://github.com/huggingface/transformers.git

进入 transformers 文件夹，并执行以下命令来安装 transformers 库：

pip install -e .

这将使用 pip 命令以可编辑模式进行安装，以便在本地对其进行修改和调试。

最后，验证 transformers 库是否已成功安装。可以在 Python 解释器中执行以下代码：

import transformers

print(transformers.__version__)

如果输出 transformers 库的版本号，则表示安装成功。

1、open-webui所需环境资源
python3.11+ 、 npm 、 node
2、文件下载地址
https://docs.openwebui.com/
官网介绍的是用docker 直接安装部署，可直接参考官网安装步骤进行安装即可。

在此提供本地直接安装部署 步骤

由于我们本机系统已经安装了python及其相关的pip服务，我们可以直接通过pip进行open-webui的安装具体安装方法如下：
3、安装
1） 切换镜像
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple
2）安装服务
pip install open-webui
3）服务启动
open-webui serve
注意：在服务启动过程中由于open-webui链接模型 源为hugging face ，一般网络环境在国内是禁止访问的，所以如果你想下载其他大模型可通过科学上网的方式链接以上模型源地址。
对于本地要部署deepseek 的同学来说，你可以通过ollama 直接下载大模型后，不需要关注其他链接报错问题，直接启动ollama 以及open-webui即可

出现端口占用修改端口 可以通过修改config.json的形式修改open-webui的端口 也可以在启动命令中直接修改
open-webui serve --port 9089
默认服务启动端口为8080端口

安装python第三方库的时候会提示报错缺少依赖库，报错如下：

ERROR: Could not find a version that satisfies the requirement 模块名 (from automat) (from versions: none)
ERROR: No matching distribution found for 模块名

ERROR: Could not find a version that satisfies the requirement triton (from versions: none)
ERROR: No matching distribution found for triton
没有具体提示的时候在官网下载最新安装即可
官网网址：https://pypi.org/

  1. 1
  2. 2