aigc-apps/VideoX-Fun · 上手攻略

仓库：aigc-apps/VideoX-Fun
链接：https://github.com/aigc-apps/VideoX-Fun
分类：AI 视频生成 / Diffusion Transformer
作者：Tom
更新：2026-08-21

这是什么

VideoX-Fun 是阿里巴巴 PAI 团队开源的端到端 AI 视频生成流水线，基于 Diffusion Transformer（DiT）架构，支持文生视频（T2V）、图生视频（I2V）、视频生视频（V2V）、控制视频生成（ControlNet 类）以及 LoRA 微调训练。项目同时支持 CogVideoX-Fun 系列和 Wan2.1-Fun 系列模型，覆盖从 2B 到 14B 参数规模，号称"任意分辨率"生成（256×256 到 1024×1024，帧数最高 81 帧）。

核心特点： - 多模型支持：CogVideoX-Fun（2B/5B）、Wan2.1-Fun（1.3B/14B）、Wan2.2 系列 - 四种生成模式：T2V、I2V、V2V、控制视频生成（Canny/Pose/Depth/轨迹控制） - 多后端：原生 Python 脚本、ComfyUI 节点、阿里云 PAI-DSW 免费 GPU - 支持 Diffusers：CogVideoX-Fun Control 已合入 Hugging Face Diffusers 官方库

解决什么问题

AI 视频生成领域存在几个实际痛点：

痛点	VideoX-Fun 解法
不同模型要装不同的代码库，混用困难	统一流水线，切换模型只改文件夹名
开源模型显存门槛高（14B 模型 80GB VRAM）	提供三种 `gpu_memory_mode`：model_cpu_offload / qfloat8 量化 / sequential_cpu_offload
消费级显卡跑不动大模型	Wan2.1-Fun 1.3B 版本只需约 16GB VRAM，配合量化可更低
控制类视频（姿态/深度）需要自己接 ControlNet	内置 Control + Reference Image 模型，配置好权重路径直接运行
多 GPU 并行推理门槛高	xfuser 集成，8 卡并行只需配置 ulysses_degree + ring_degree 参数

快速安装

环境要求

组件	版本要求
Python	3.10 或 3.11
PyTorch	2.2.0（官方验证）
CUDA	11.8 或 12.1
cuDNN	8+
磁盘	≥ 60GB（存放权重）
GPU（推荐）	NVIDIA RTX 3060 12GB / RTX 3090 24GB / A100 40GB+

⚠️ 注意：官方仅验证了 torch 2.2.0，使用其他 PyTorch 版本可能出现不兼容问题。

方式一：Docker（最简，推荐）

# 拉取镜像（已包含 PyTorch + CUDA 环境）
docker pull mybigpai-public-registry.cn-beijing.cr.aliyuncs.com/easycv/torch_cuda:cogvideox_fun

# 运行容器（自动映射 7860 端口）
docker run -it -p 7860:7860 --network host \
  --gpus all --security-opt seccomp:unconfined \
  --shm-size 200g \
  mybigpai-public-registry.cn-beijing.cr.aliyuncs.com/easycv/torch_cuda:cogvideox_fun

# 在容器内 clone 代码
git clone https://github.com/aigc-apps/VideoX-Fun.git
cd VideoX-Fun

方式二：阿里云 PAI-DSW（免费 GPU）

# 阿里云有免费 GPU 时长（3 个月有效期，新用户申请一次）
# 访问：https://free.aliyun.com/ → PAI-DSW → 免费试用
# 预置镜像已包含环境，直接运行即可

方式三：从零源码安装

# 1. 克隆代码
git clone https://github.com/aigc-apps/VideoX-Fun.git
cd VideoX-Fun

# 2. 创建 conda 环境（推荐）
conda create -n videox-fun python=3.10 -y
conda activate videox-fun

# 3. 安装 PyTorch（CUDA 12.1 示例）
pip install torch==2.2.0 torchvision torchaudio \
  --index-url https://download.pytorch.org/whl/cu121

# 4. 安装依赖
pip install -r requirements.txt

# 5. 安装 xformers（加速 DiT 计算，可选但推荐）
pip install xformers==0.0.24  # 注意版本与 torch 2.2.0 匹配性

下载模型权重

# 创建权重目录
mkdir -p models/Diffusion_Transformer
mkdir -p models/Personalized_Model

# CogVideoX-Fun（以 V1.1-5B-InP 为例）
# HuggingFace：https://huggingface.co/alibaba-pai/CogVideoX-Fun-V1.1-5b-InP
# ModelScope：https://modelscope.cn/models/PAI/CogVideoX-Fun-V1.1-5b-InP

# Wan2.1-Fun 14B（以 V1.1 为例）
# HuggingFace：https://huggingface.co/alibaba-pai/Wan2.1-Fun-V1.1-14B-InP
# ModelScope：https://modelscope.cn/models/PAI/Wan2.1-Fun-V1.1-14B-InP

# 放置路径示例
# models/Diffusion_Transformer/CogVideoX-Fun-V1.1-5b-InP/
# models/Diffusion_Transformer/Wan2.1-Fun-14B-InP/

核心用法

1. 文生视频（T2V）

# 修改 examples/cogvideox_fun/predict_t2v.py 中的以下参数：
# prompt = "A young woman with blonde hair, wearing white clothes, twisting her body"
# neg_prompt = "blurry, low quality, distorted"
# guidance_scale = 7.5
# seed = 42

# 运行
python examples/cogvideox_fun/predict_t2v.py

# 输出路径：samples/cogvideox-fun-videos/

2. 图生视频（I2V）

# 修改 examples/cogvideox_fun/predict_i2v.py：
# validation_image_start = "input_image.png"   # 起始帧图片
# validation_image_end = "end_image.png"       # 结束帧图片
# prompt = "A person dancing"
# guidance_scale = 7.0
# seed = 123

python examples/cogvideox_fun/predict_i2v.py

# 输出路径：samples/cogvideox-fun-videos_i2v/

3. 视频生视频（V2V）

# 修改 examples/cogvideox_fun/predict_v2v.py：
# validation_video = "input_video.mp4"   # 参考视频
# validation_image_end = "end_image.png"  # 结束帧
# 可用 Demo 视频：
# https://pai-aigc-photog.oss-cn-hangzhou.aliyuncs.com/cogvideox_fun/asset/v1/play_guitar.mp4

python examples/cogvideox_fun/predict_v2v.py

# 输出路径：samples/cogvideox-fun-videos_v2v/

4. 控制视频生成（Canny / Pose / Depth）

# 控制视频需先提取控制条件（Canny 边缘、姿态、深度）
# 官方提供 Demo 控制视频：
# https://pai-aigc-photog.oss-cn-hangzhou.aliyuncs.com/cogvideox_fun/asset/v1.1/pose.mp4

# 修改 examples/cogvideox_fun/predict_v2v_control.py：
# control_video = "pose.mp4"
# validation_image_end = "end_image.png"
# prompt = "A woman dancing"

python examples/cogvideox_fun/predict_v2v_control.py

# 输出路径：samples/cogvideox-fun-videos_v2v_control/

5. 显存优化模式（消费级 GPU 关键）

在所有 predict_*.py 文件中修改 gpu_memory_mode 参数：

gpu_memory_mode = "model_cpu_offload"          # 平衡模式，~16GB VRAM 可跑 14B
# gpu_memory_mode = "model_cpu_offload_and_qfloat8"  # 更省显存，~12GB VRAM，略有质量损失
# gpu_memory_mode = "sequential_cpu_offload"          # 最省显存，~8GB VRAM，速度最慢

6. 多卡并行推理（8 卡为例）

# 安装并行推理依赖
pip install xfuser==0.4.2 yunchang==0.6.2 \
  -i https://mirrors.aliyun.com/pypi/simple/

# Wan2.1-Fun-14B（40 heads，ulysses_degree 须为 40 的因数）
# 8 卡：ulysses_degree=8, ring_degree=1
torchrun --nproc-per-node=8 examples/wan2.1_fun/predict_t2v.py \
  --ulysses_degree=8 --ring_degree=1

# Wan2.1-Fun-1.3B（12 heads，ulysses_degree 须为 12 的因数）
# 8 卡：ulysses_degree=4, ring_degree=2
torchrun --nproc-per-node=8 examples/wan2.1_fun/predict_t2v.py \
  --ulysses_degree=4 --ring_degree=2

⚠️ ulysses_degree * ring_degree 必须等于实际 GPU 数量，且 ulysses_degree 须为模型 head 数的因数。

7. ComfyUI 使用

# 将权重放入 ComfyUI 目录
# 路径：ComfyUI/models/Fun_Models/
# ├── CogVideoX-Fun-V1.1-2b-InP/
# ├── CogVideoX-Fun-V1.1-5b-InP/
# ├── Wan2.1-Fun-14B-InP/
# └── Wan2.1-Fun-1.3B-InP/

# 参考 ComfyUI 节点说明：
# https://github.com/aigc-apps/VideoX-Fun/blob/main/comfyui/README.md

典型适用场景

1. 短视频内容创作 输入一段文字描述或一张参考图，生成对应视频内容，适合 TikTok/小红书/抖音等平台的内容创作者。

2. 数字人/虚拟形象制作 结合 Wan2.1-Fun 的 Reference Image 功能，以一张照片驱动生成指定动作的视频，支撑虚拟主播、数字员工等场景。

3. 影视/广告概念预览 在正式制作前，用 ControlNet 类姿态/深度控制生成故事板视频，快速验证镜头和动作构思。

4. AI 视频研究复现 作为 CogVideoX/Wan2.1 的统一评测框架，研究者可快速替换不同模型权重，对比生成质量与速度。

5. LoRA 个性化训练 基于自己的素材训练 LoRA，实现特定风格或角色的视频生成，ComfyUI 节点也支持加载 LoRA。

坑与注意

坑点	说明	解决方案
权重下载慢/失败	HuggingFace/ModelScope 在国内访问不稳定	使用阿里云 ModelScope 或阿里云 DSW 预置镜像
显存爆掉（OOM）	14B 模型默认需要 80GB+ VRAM	切换到 `gpu_memory_mode=model_cpu_offload` 或 qfloat8
步数/帧数设置不合理导致生成异常	guidance_scale 过高或帧数超限	guidance_scale 建议 5-8，帧数不超过模型支持上限
PyTorch 版本不匹配	官方只用 2.2.0 验证	不要使用 2.3+ 或 2.1，等官方更新兼容性
多卡并行 head 数配置错误	ulysses_degree 不是 head 数因数时运行失败	14B 模头数 40，1.3B 模头数 12，先查 model config
输出视频画面闪烁/抖动严重	seed 未固定或 prompt 描述不稳定	固定 seed，增加 neg_prompt 中关于质量的负面描述
Docker 镜像拉取超时	阿里云北京区镜像，网络波动	尝试其他可用区或配置国内镜像加速

与同类对比

维度	VideoX-Fun	CogVideoX（官方）	Wan2.1（官方）	EasyAnimate
模型覆盖	CogVideoX + Wan2.1 双系列	仅 CogVideoX	仅 Wan2.1	仅自研
多分辨率	✅ 256-1024 任意	✅ 部分支持	✅ 部分支持	✅
I2V/V2V/Control	✅ 全支持	基础	基础	基础
LoRA 训练	✅ 支持	❌	❌	✅
ComfyUI 集成	✅ 官方节点	❌	❌	✅
显存优化	✅ 三档 CPU offload	❌	部分	❌
多卡并行	✅ xfuser	❌	❌	❌
中文文档	✅ 中文 README	英文	英文	中文
维护活跃度	2025-10 更新 Wan2.2	停更	停更	一般

结论：VideoX-Fun 是目前对 CogVideoX 和 Wan2.1 两个主流开源视频生成系列覆盖最完整的统一框架，特别适合需要混用多个模型、或在消费级 GPU 上运行大模型的研究者和创作者。

一句话推荐

如果你在找一款同时支持 CogVideoX 和 Wan2.1 双系列、带完整 ControlNet、显存优化和多卡并行的开源视频生成框架，VideoX-Fun 是目前最省心的选择。

最小可跑命令清单

# 硬件：NVIDIA GPU（建议 16GB+ VRAM）
# Python：3.10
# PyTorch：2.2.0（必须）
# CUDA：11.8 或 12.1

# ① 安装
git clone https://github.com/aigc-apps/VideoX-Fun.git
cd VideoX-Fun
pip install torch==2.2.0 --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt

# ② 下载权重（CogVideoX-Fun 5B，~20GB）
mkdir -p models/Diffusion_Transformer
# 从 https://huggingface.co/alibaba-pai/CogVideoX-Fun-V1.1-5b-InP 下载放入上述目录

# ③ 显存不足时，在 predict_t2v.py 中加一行
gpu_memory_mode = "model_cpu_offload"

# ④ 运行文生视频（50 步，81 帧，约需 16GB VRAM）
python examples/cogvideox_fun/predict_t2v.py
# 输出在 samples/cogvideox-fun-videos/

# ⑤ ComfyUI 方式（需额外配置权重路径）
# 参考：https://github.com/aigc-apps/VideoX-Fun/blob/main/comfyui/README.md

来源：VideoX-Fun GitHub · HuggingFace · ComfyUI Readme · Video Generation Comparison