认知神经科学研究报告【20260108】

文章目录

[Wan2.1-VACE-1.3B 本地部署与优化技术文档](#Wan2.1-VACE-1.3B 本地部署与优化技术文档)
- [1. 项目概述](#1. 项目概述)
- - [1.1 目标](#1.1 目标)
  - [1.2 模型信息](#1.2 模型信息)
- [2. 硬件与环境配置](#2. 硬件与环境配置)
- - [2.1 硬件规格](#2.1 硬件规格)
  - [2.2 环境搭建](#2.2 环境搭建)
  - [2.3 系统依赖](#2.3 系统依赖)
- [3. 代码修改与优化](#3. 代码修改与优化)
- - [3.1 核心问题与解决方案](#3.1 核心问题与解决方案)
  - [3.2 `attention.py` 修改（第1处）](#3.2 attention.py 修改（第1处）)
  - [3.3 `utils.py` 修改（第2处）](#3.3 utils.py 修改（第2处）)
- [4. 运行命令与参数调优](#4. 运行命令与参数调优)
- - [4.1 基础运行命令（测试用，9帧，20步）](#4.1 基础运行命令（测试用，9帧，20步）)
  - [4.2 参数说明](#4.2 参数说明)
  - [4.3 显存与参数关系](#4.3 显存与参数关系)
- [5. 常见问题与排查](#5. 常见问题与排查)
- - [5.1 显存不足 (OOM)](#5.1 显存不足 (OOM))
  - [5.2 `FLASH_ATTN_2_AVAILABLE` 断言失败](#5.2 FLASH_ATTN_2_AVAILABLE 断言失败)
  - [5.3 `cache_video failed, error: result type Float can't be cast to...`](#5.3 cache_video failed, error: result type Float can't be cast to...)
  - [5.4 `cache_video failed, error: 'NoneType' object is not iterable`](#5.4 cache_video failed, error: 'NoneType' object is not iterable)
  - [5.5 视频无法播放或模糊](#5.5 视频无法播放或模糊)
- [6. 性能基准](#6. 性能基准)
- - [6.1 V100 16GB 测试结果](#6.1 V100 16GB 测试结果)
  - [6.2 推荐配置](#6.2 推荐配置)
- [7. 未来优化方向](#7. 未来优化方向)
- - [7.1 硬件升级建议](#7.1 硬件升级建议)
  - [7.2 模型升级路径](#7.2 模型升级路径)
  - [7.3 功能扩展](#7.3 功能扩展)
- [8. 许可证与法律合规](#8. 许可证与法律合规)
- [9. 总结](#9. 总结)

Wan2.1-VACE-1.3B 本地部署与优化技术文档

版本：v1.0

日期：2026-06-29

硬件：NVIDIA Tesla V100-SXM2-16GB

操作系统 ：Ubuntu 22.04/24.04 (Linux)

Python环境：Conda + Python 3.10/3.12

1. 项目概述

1.1 目标

在单张 NVIDIA V100 16GB 显卡上成功部署并运行 Wan2.1-VACE-1.3B 模型，实现文本到视频（Text-to-Video）的生成，并支持视频编辑功能（VACE：Video Editing and Composition Engine）。

test_17f_25s

1.2 模型信息

项目	详情
模型名称	Wan-AI/Wan2.1-VACE-1.3B
参数量	13亿 (1.3B)
输入	文本提示词 (中文/英文)
输出分辨率	480P (832×480 或 480×832)
帧率	16 fps
开源协议	Apache-2.0（允许商业使用）

2. 硬件与环境配置

2.1 硬件规格

复制代码

GPU: Tesla V100-SXM2-16GB (Volta架构)
显存: 16384 MiB
CUDA Driver: 13.0
系统: Ubuntu Linux

2.2 环境搭建

Conda环境创建：

bash 复制代码

conda create -n wan2.1 python=3.10 -y
conda activate wan2.1

安装PyTorch（CUDA 11.8/12.1对应版本）：

bash 复制代码

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

克隆项目并安装依赖：

bash 复制代码

git clone https://github.com/Wan-AI/Wan2.1.git
cd Wan2.1
pip install -r requirements.txt

2.3 系统依赖

bash 复制代码

sudo apt update
sudo apt install ffmpeg -y   # 视频编码必需

3. 代码修改与优化

3.1 核心问题与解决方案

问题	原因	解决方案
FlashAttention不支持	V100 (Volta架构) 不支持FlashAttention-2	修改 `wan/modules/attention.py`，增加回退到PyTorch原生注意力机制
显存不足 (OOM)	模型加载后占用超过16GB	使用 `--offload_model True --t5_cpu` 卸载部分权重到CPU
视频保存类型错误	`cache_video` 期望Float但收到Byte，或形状不匹配	修改 `wan/utils/utils.py`，增强形状自动适配和类型转换
视频编码失败	`imageio` 缺少FFmpeg后端	安装 `ffmpeg` 和 `imageio-ffmpeg`（或直接使用 `torchvision.io.write_video`）

3.2 `attention.py` 修改（第1处）

文件路径 ：/home/x/pro/Wan2.1/wan/modules/attention.py

修改内容 ：在 flash_attention 函数开头添加回退逻辑

python 复制代码

def flash_attention(q, k, v, ...):
    # 检查是否可用 FlashAttention
    if not (FLASH_ATTN_2_AVAILABLE or FLASH_ATTN_3_AVAILABLE):
        # V100等旧卡回退到PyTorch原生实现
        if q_lens is not None or k_lens is not None:
            warnings.warn('FlashAttention not available, using PyTorch SDPA.')
        q = q.transpose(1, 2)  # [B, L, H, C] -> [B, H, L, C]
        k = k.transpose(1, 2)
        v = v.transpose(1, 2)
        out = torch.nn.functional.scaled_dot_product_attention(
            q, k, v, attn_mask=None, dropout_p=dropout_p, is_causal=causal
        )
        return out.transpose(1, 2).contiguous()
    # ... 原有FlashAttention代码

3.3 `utils.py` 修改（第2处）

文件路径 ：/home/x/pro/Wan2.1/wan/utils/utils.py

修改内容 ：增强 cache_video 函数，支持自动形状适配和正确的类型转换

python 复制代码

def cache_video(tensor, save_file=None, fps=30, suffix='.mp4', nrow=8,
                normalize=True, value_range=(-1, 1), retry=5):
    # ===== 新增：自动形状适配 =====
    if tensor.dim() == 4:
        # [C, T, H, W] 或 [T, H, W, C]
        if tensor.shape[0] in [1, 3, 4] and tensor.shape[0] != tensor.shape[-1]:
            tensor = tensor.unsqueeze(0)  # -> [1, C, T, H, W]
        else:
            tensor = tensor.permute(3, 0, 1, 2).unsqueeze(0)  # -> [1, C, T, H, W]
    elif tensor.dim() == 5:
        if tensor.shape[1] not in [1, 3, 4]:  # [B, T, H, W, C]
            tensor = tensor.permute(0, 4, 1, 2, 3)  # -> [B, C, T, H, W]
    else:
        raise ValueError(f"Unsupported tensor dimension: {tensor.dim()}")
    # ===== 原有处理逻辑 =====
    cache_file = save_file or osp.join('/tmp', rand_name(suffix=suffix))
    error = None
    for _ in range(retry):
        try:
            tensor = tensor.clamp(min(value_range), max(value_range))
            tensor = torch.stack([
                torchvision.utils.make_grid(u, nrow=nrow, normalize=normalize,
                                            value_range=value_range)
                for u in tensor.unbind(2)  # 在时间维度上拆分
            ], dim=1).permute(1, 2, 3, 0)
            # ===== 关键修复：正确的类型转换 =====
            tensor = (tensor * 255).to(torch.uint8).cpu().contiguous()
            # ===== 写入视频 =====
            writer = imageio.get_writer(cache_file, fps=fps,
                                        codec='libx264', quality=8)
            for frame in tensor.numpy():
                writer.append_data(frame)
            writer.close()
            return cache_file
        except Exception as e:
            error = e
            continue
    print(f'cache_video failed, error: {error}', flush=True)
    return None

4. 运行命令与参数调优

4.1 基础运行命令（测试用，9帧，20步）

bash 复制代码

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
python generate.py \
  --task vace-1.3B \
  --size 832*480 \
  --frame_num 9 \
  --sample_steps 20 \
  --ckpt_dir /home/x/pro/Wan2.1-VACE-1.3B \
  --prompt "一只猫在草地上奔跑" \
  --offload_model True \
  --t5_cpu \
  --save_file output.mp4

4.2 参数说明

参数	说明	推荐值
`--task`	任务类型	`vace-1.3B`（1.3B版本）
`--size`	输出分辨率	`832*480`（480P）
`--frame_num`	帧数（4n+1）	9（_{0.5秒），17（}1秒），33（~2秒）
`--sample_steps`	采样步数	20（快速测试），40-50（高质量）
`--ckpt_dir`	模型权重路径	本地绝对路径
`--prompt`	文本提示词	中文或英文
`--offload_model`	卸载模型到CPU	`True`（显著降低显存）
`--t5_cpu`	T5编码器在CPU运行	`True`（节省约1-2GB显存）
`--save_file`	输出文件名	如 `output.mp4`

4.3 显存与参数关系

配置	显存占用	生成时间	画质
9帧 + 20步	~9.1 GB	~2分钟	基础
9帧 + 40步	~10.5 GB	~4分钟	中等
17帧 + 40步	~12.5 GB	~8分钟	良好
33帧 + 40步	~14.5 GB	~15分钟	较好（接近极限）

5. 常见问题与排查

5.1 显存不足 (OOM)

现象：

复制代码

torch.OutOfMemoryError: CUDA out of memory

解决方案：

降低 --frame_num（如 17→9）
降低 --size（如 832480 → 704384）
确保已启用 --offload_model True --t5_cpu
使用 export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
检查是否有其他进程占用显存：nvidia-smi 并用 kill -9 PID 结束残留进程

5.2 `FLASH_ATTN_2_AVAILABLE` 断言失败

现象：

复制代码

AssertionError: FLASH_ATTN_2_AVAILABLE

原因：V100不支持FlashAttention-2

解决方案 ：修改 attention.py 添加回退逻辑（见3.2节）

5.3 `cache_video failed, error: result type Float can't be cast to...`

原因：视频数据为Float类型，编码器需要Byte类型

解决方案 ：修改 utils.py 中的 cache_video，使用 .to(torch.uint8).cpu().contiguous()（见3.3节）

5.4 `cache_video failed, error: 'NoneType' object is not iterable`

原因：cache_video 内部 tensor.unbind(2) 失败，因为输入形状不是 [B, C, T, H, W]

解决方案 ：修改 cache_video 增加自动形状适配（见3.3节）

5.5 视频无法播放或模糊

原因：采样步数太低（<30）或分辨率不匹配

解决方案：

增加 --sample_steps 到 40-50
确保 --size 为 832*480（VACE-1.3B原生分辨率）
优化提示词，加入"4K, 高分辨率, 细节丰富"等关键词

6. 性能基准

6.1 V100 16GB 测试结果

测试项	数值
模型加载时间（T5+VAE+DiT）	~60秒
生成9帧×20步耗时	~2分11秒
生成9帧×40步耗时	~4分20秒
峰值显存占用	~9.1-14.5 GB
CPU内存占用	~8-12 GB

6.2 推荐配置

平衡型（画质与速度）：

bash 复制代码

--frame_num 17 --sample_steps 40 --size 832*480

画质优先：

bash 复制代码

--frame_num 33 --sample_steps 50 --size 960*544

（需监控显存，可能触发OOM）

7. 未来优化方向

7.1 硬件升级建议

硬件	优势	适用场景
RTX 4090 24GB	性价比高，可跑14B版本（量化）	个人开发者
A100 40GB/80GB	企业级，原生支持FlashAttention	商业部署
双卡V100 16GB×2	利用现有资源，分布式推理	并行加速

7.2 模型升级路径

Wan2.1-VACE-14B：支持720P，画质显著提升，需≥24GB显存
HunyuanVideo：腾讯开源，13B参数，物理模拟更优
Wan2.1-T2V-14B：纯文本生成，不支持编辑

7.3 功能扩展

视频编辑 ：使用 --src_video 和 --src_mask 实现局部替换
多图参考 ：使用 --src_ref_images 实现角色一致性
首尾帧生成 ：使用 --first_frame 和 --last_frame

8. 许可证与法律合规

模型协议：Apache-2.0，允许商业使用
注意事项 ：
- 需保留原始版权声明（NOTICE文件）
- 生成内容需自行审核，避免侵权
- AI生成视频需添加显著标识（符合各国法规）

9. 总结

本技术文档记录了 Wan2.1-VACE-1.3B 在 NVIDIA V100 16GB 上的完整部署、调试、优化和运行流程。

核心要点：

硬件限制：V100不支持FlashAttention，需修改代码回退
显存瓶颈 ：通过 --offload_model 和 --t5_cpu 将占用控制在16GB以内
视频保存 ：修改 cache_video 实现自动形状适配和正确的类型转换
画质优化 ：提高 --sample_steps 至40-50，优化提示词

最终状态 ：成功生成并播放 output.mp4，验证了端到端流程的可行性。

文档维护 ：如有更新或遇到新问题，请参考官方GitHub仓库：

https://github.com/Wan-AI/Wan2.1

认知神经科学研究报告【20260108】

文章目录

Wan2.1-VACE-1.3B 本地部署与优化技术文档

1. 项目概述

1.1 目标

1.2 模型信息

2. 硬件与环境配置

2.1 硬件规格

2.2 环境搭建

2.3 系统依赖

3. 代码修改与优化

3.1 核心问题与解决方案

3.2 attention.py 修改（第1处）

3.3 utils.py 修改（第2处）

4. 运行命令与参数调优

4.1 基础运行命令（测试用，9帧，20步）

4.2 参数说明

4.3 显存与参数关系

5. 常见问题与排查

5.1 显存不足 (OOM)

5.2 FLASH_ATTN_2_AVAILABLE 断言失败

5.3 cache_video failed, error: result type Float can't be cast to...

5.4 cache_video failed, error: 'NoneType' object is not iterable

5.5 视频无法播放或模糊

6. 性能基准

6.1 V100 16GB 测试结果

6.2 推荐配置

7. 未来优化方向

7.1 硬件升级建议

7.2 模型升级路径

7.3 功能扩展

8. 许可证与法律合规

9. 总结

3.2 `attention.py` 修改（第1处）

3.3 `utils.py` 修改（第2处）

5.2 `FLASH_ATTN_2_AVAILABLE` 断言失败

5.3 `cache_video failed, error: result type Float can't be cast to...`

5.4 `cache_video failed, error: 'NoneType' object is not iterable`