简介:本文面向想在自有 NVIDIA 设备上运行开源视频生成模型的开发者,给出 CogVideoX 本地部署的可执行流程。内容覆盖环境检查、版本匹配、模型校验、12GB 显存下的低显存推理、图生视频配置、可复现验收与排障命令,帮助读者少走弯路,稳定完成文生视频和图生视频。
本文目标不是泛泛介绍概念,而是给出一套可执行、可排障、可复用的本地部署流程。完成本教程后,你应能在带 NVIDIA 显卡的机器上完成以下任务:
验收标准可以很简单:
torch.use_deterministic_algorithms(True)。该设置可能降低速度,且部分算子可能不支持确定性模式。本地部署开源视频生成模型,适合以下场景:
但本地部署并不适合所有情况。以下情况反而更适合云端 API 或托管服务:
如果属于这些情况,可以先使用云端 API、托管式生成服务或商业模型,再根据实际成本、合规要求和生成频率决定是否本地化。
建议至少具备以下条件:
显存建议并不是绝对阈值,需要结合模型规格、分辨率、帧数和推理方式判断。可以用以下命令确认当前 GPU 显存:
nvidia-smi --query-gpu=name,memory.total,memory.used,memory.free --format=csv
如果希望观察推理过程中的显存变化,可以另开一个终端运行:
watch -n 1 nvidia-smi --query-gpu=name,memory.used,memory.total,utilization.gpu --format=csv
开始部署前,建议先运行以下命令,确认驱动、Python、PyTorch 和关键依赖状态。
nvidia-smipython --versionpip --versionpip show torch diffusers transformers accelerate
预期关注点:
nvidia-smi 能看到显卡型号、驱动版本和显存总量。python --version 输出 3.10.x。pip show torch 能看到 PyTorch 版本和 CUDA 版本。pip show diffusers 能看到 Diffusers 版本。下表以 CogVideoX 2B 级别模型、FP16、batch size=1、默认优化开启为前提,给出粗估区间。实际占用会受模型实现、优化选项、显存碎片和 PyTorch 版本影响。
测量口径建议如下:
enable_model_cpu_offload() 是否开启,vae.enable_tiling() 是否开启。batch size=1。torch.cuda.max_memory_allocated() 读取峰值显存。| 分辨率 | 帧数 | 采样步数 | 显存占用粗估 | 适用建议 |
|---|---|---|---|---|
| 480x480 | 17 到 33 | 20 | 5GB 到 8GB | 12GB 以下可尝试,需开启 CPU offload |
| 720x480 | 33 到 49 | 20 | 9GB 到 13GB | 12GB 显卡可低配运行 |
| 1280x720 | 49 | 20 以上 | 16GB 以上更稳 | 建议 24GB 显卡 |
| 长时长或多分辨率叠加 | 81 或更高 | 高 | 16GB 以上,24GB 更稳 | 本地低配不建议 |
12GB 显存的定位是“可运行、可调试、可短片段生成”,不适合一开始就挑战高分辨率长视频。16GB 内存的意义主要在于模型加载、CPU offload、数据预处理和操作系统缓存。
建议使用 Conda 或 venv 隔离项目环境,避免不同项目之间 PyTorch、Transformers、Diffusers 版本冲突。
以 Conda 为例:
conda create -n video-gen python=3.10 -yconda activate video-genpython --versionpip --version
预期输出:Python 3.10.x、pip 可用。若激活失败,重新执行 conda init 并重开终端。
视频生成模型通常基于 PyTorch 和 Diffusers 生态运行。关键是让显卡驱动、CUDA 运行时、PyTorch 版本和模型仓库依赖相互兼容。
先查看 NVIDIA 驱动:
nvidia-smi
如果驱动版本较新,可选择 CUDA 12.1 组合;如果驱动较旧,可选择 CUDA 11.8 组合。
推荐版本组合 A:CUDA 12.1
适用条件:
安装命令:
pip install torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu121pip install diffusers==0.31.0 transformers==4.44.2 accelerate==0.33.0 imageio imageio-ffmpeg av einops sentencepiece
推荐版本组合 B:CUDA 11.8
适用条件:
安装命令:
pip install torch==2.2.2 torchvision==0.17.2 --index-url https://download.pytorch.org/whl/cu118pip install diffusers==0.30.3 transformers==4.43.3 accelerate==0.32.1 imageio imageio-ffmpeg av einops sentencepiece
安装完成后,验证 GPU 是否可用:
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda); print(torch.cuda.get_device_name(0))"
预期输出应包含 PyTorch 版本、True、CUDA 版本和 GPU 型号。如果输出 False,说明 PyTorch 未正确调用 GPU,应优先检查驱动和 cu118/cu121 版本是否匹配。
本文以 Hugging Face 上的 CogVideoX 作为开源视频生成模型示例。模型仓库和代码仓库分别为:
THUDM/CogVideoX-2b2B 版本适合 12GB 左右显存进行低配尝试;5B 或更高质量版本对显存要求更高,建议 24GB 以上再考虑。
安装 Git LFS 后下载模型:
git lfs installhuggingface-cli download THUDM/CogVideoX-2b --local-dir ./models/CogVideoX-2b
如果网络受限,可以配置 Hugging Face 镜像或使用已下载的离线包。离线部署时,模型路径可以指向本地目录,不依赖公网。
为了降低模型文件被篡改或版本错配的风险,建议优先使用官方发布页提供的快照、提交号或镜像源。若仓库提供提交号,可以固定版本:
huggingface-cli download THUDM/CogVideoX-2b --revision <commit_or_tag> --local-dir ./models/CogVideoX-2b
下载后先做基础校验:
python -c "import json; data=json.load(open('./models/CogVideoX-2b/model_index.json')); print(data['_class_name'])"du -sh ./models/CogVideoX-2b
如果模型卡或发布页提供 SHA256 校验值,可以使用以下方式核对关键文件:
sha256sum ./models/CogVideoX-2b/model_index.jsonsha256sum ./models/CogVideoX-2b/unet/diffusion_pytorch_model.safetensors
如果是离线包,可要求供应商提供 SHA256SUMS.txt,并执行:
cd ./models/CogVideoX-2bsha256sum -c SHA256SUMS.txt
合规提示非常重要:
将下载的模型加载到本地后,可以写一个 Python 脚本完成文生视频。为避免不同 Diffusers 版本对 seed 参数支持不一致,建议显式创建 torch.Generator 并设置种子。
创建 run_video.py:
import torchfrom diffusers import CogVideoXPipelinefrom diffusers.utils import export_to_videomodel_path = "./models/CogVideoX-2b"pipe = CogVideoXPipeline.from_pretrained(model_path,torch_dtype=torch.float16)pipe.enable_model_cpu_offload()pipe.vae.enable_tiling()prompt = "一只猫在草地上奔跑,阳光明媚,电影质感"seed = 42generator = torch.Generator(device="cpu").manual_seed(seed)if torch.cuda.is_available():torch.cuda.reset_peak_memory_stats()video = pipe(prompt=prompt,height=480,width=720,num_frames=49,num_inference_steps=20,guidance_scale=6.0,generator=generator).frames[0]export_to_video(video, "output/result.mp4", fps=8)print("done: output/result.mp4")if torch.cuda.is_available():print("peak memory GiB:", torch.cuda.max_memory_allocated() / 1024 ** 3)
运行前创建输出目录:
mkdir -p outputpython run_video.py
如果显存足够,也可以改为直接加载到 GPU:
pipe = CogVideoXPipeline.from_pretrained(model_path,torch_dtype=torch.float16).to("cuda")
但 12GB 显存更建议使用 enable_model_cpu_offload(),它会在推理时按需把模型模块加载到 GPU,降低峰值占用。
如果显存仍然不足,可以尝试更激进的 sequential offload:
pipe.enable_sequential_cpu_offload()
注意:通常不要同时使用 to("cuda") 和 enable_sequential_cpu_offload()。二者应择一。
批量生成不同结果时,也需要为每个种子单独创建生成器:
for seed in [42, 43, 44, 45]:generator = torch.Generator(device="cpu").manual_seed(seed)video = pipe(prompt=prompt,height=480,width=720,num_frames=49,num_inference_steps=20,guidance_scale=6.0,generator=generator).frames[0]export_to_video(video, f"output/seed_{seed}.mp4", fps=8)
如果模型支持图生视频,可以使用参考图片驱动首帧或运动效果。这里需要特别注意:CogVideoXImageToVideoPipeline 使用的模型路径必须是支持图生视频的 CogVideoX 权重,不能默认认为任意 CogVideoX 权重都可以直接用于图生视频。
下载图生视频权重时,应将模型仓库替换为支持图生视频的 CogVideoX 权重。示例命令如下:
# MODEL_ID 必须替换为官方或可信来源中支持图生视频的 CogVideoX 权重huggingface-cli download YOUR_COGVIDEOX_I2V_MODEL_ID --local-dir ./models/CogVideoX-i2v
下载后可以检查模型配置文件,确认其类型是否与图生视频流水线匹配:
python -c "import json; data=json.load(open('./models/CogVideoX-i2v/model_index.json')); print(data['_class_name'])"
图生视频推理脚本示例:
import torchfrom diffusers import CogVideoXImageToVideoPipelinefrom diffusers.utils import export_to_video, load_image# 该路径必须指向支持图生视频的 CogVideoX 权重model_path = "./models/CogVideoX-i2v"pipe = CogVideoXImageToVideoPipeline.from_pretrained(model_path,torch_dtype=torch.float16)pipe.enable_model_cpu_offload()pipe.vae.enable_tiling()image = load_image("input.png").convert("RGB").resize((720, 480))seed = 42generator = torch.Generator(device="cpu").manual_seed(seed)video = pipe(prompt="让画面中的人物缓慢转头,镜头轻微推进",image=image,num_frames=49,num_inference_steps=20,guidance_scale=6.0,generator=generator).frames[0]export_to_video(video, "output/image_to_video.mp4", fps=8)print("done: output/image_to_video.mp4")
输入图片建议:
图生视频验收建议:
视频生成参数会直接影响耗时、显存和画面质量。初次部署不要直接拉满,应遵循“先跑通、再调优”的原则。
分辨率决定输出画面大小,也决定计算量和显存占用。低配环境建议从 480x480 或 720x480 开始。
帧数决定视频长度。fps 和帧数共同决定播放时长。如果 fps=8、num_frames=49,视频时长约为 6 秒。
帧数越多,显存和耗时越高。低配环境建议先使用 33 到 49 帧。长视频不要一次性生成,可以分段生成后再用视频编辑工具拼接。
采样步数表示扩散模型去噪迭代次数。步数越多,细节通常越丰富,但耗时越长。
固定种子可以让相同输入得到可复现结果,便于调参和对比。推荐使用 torch.Generator:
generator = torch.Generator(device="cpu").manual_seed(42)
然后将其传入推理调用:
video = pipe(prompt=prompt, generator=generator).frames[0]
引导系数控制画面与提示词的贴合程度。
常用优化项包括:
enable_model_cpu_offload():降低显存峰值,适合 12GB 显卡。enable_sequential_cpu_offload():进一步降低显存,但速度更慢。vae.enable_tiling():VAE 分块处理,降低高分辨率或长视频的峰值占用。生成完成后,建议按以下步骤验证。
ls -lh output/result.mp4
如果文件为 0 或只有几 KB,通常说明生成失败或视频编码异常。
如果安装了 FFmpeg:
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 output/result.mp4
预期输出应包含时长和文件大小。时长与帧数、fps 是否匹配,可以帮你判断生成是否完整。
使用本地播放器打开视频,观察:
使用相同提示词、相同生成器种子、相同分辨率、相同帧数和相同步数再次运行。如果两次结果高度接近,说明参数固定有效;如果结果差异很大,检查是否有随机种子、未固定帧数或模型版本变化。
建议运行命令时保留日志:
python run_video.py 2>&1 | tee run.log
如果出现 OOM、CUDA error、shape mismatch、tokenizer error 等关键字,应回到对应章节排查。
常见报错包括:
CUDA out of memoryOutOfMemoryErrorRuntimeError: CUDA error: out of memory排查顺序:
nvidia-smi 查看显存是否被其他进程占用。enable_model_cpu_offload()。vae.enable_tiling()。enable_sequential_cpu_offload()。显存监控命令:
watch -n 1 nvidia-smi --query-gpu=memory.used,memory.total,utilization.gpu --format=csv
常见报错包括:
CUDA error: no kernel image is availabletorch.cuda.is_available() 返回 Falselibcudnn.so 相关错误version mismatch排查命令:
nvidia-smipython -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda)"pip checkpip list | grep -E "torch|diffusers|transformers|accelerate"
处理建议:
torch.cuda.is_available() 为 False,重装对应 CUDA 版本的 PyTorch。pip check 报依赖冲突,建议在虚拟环境中锁定版本重装。排查步骤:
nvidia-smi 的 GPU 利用率。enable_sequential_cpu_offload(),该模式会降低显存但拖慢速度。GPU 利用率命令:
watch -n 1 nvidia-smi --query-gpu=utilization.gpu,memory.used,power.draw --format=csv
如果推理时 GPU 利用率很低,但 CPU 很高,可能是数据预处理、模型加载或磁盘 IO 成为瓶颈。可以先用小模型、小分辨率、低帧数验证链路。
可能原因:
调整建议:
常见原因:
建议:
建议量化以下指标:
time 命令或日志时间戳记录。nvidia-smi 或 torch.cuda.max_memory_allocated() 观察。示例命令:
/usr/bin/time -v python run_video.py
建议把常用命令封装成脚本:
bash start_env.shbash run_task.shbash check_gpu.sh
部署文档应包含:
如果需要在团队内部对外提供生成能力,可以在本地推理节点前增加:
本文围绕“本地部署开源 AI 视频生成模型”这一目标,给出了一套更具体、可验收、可排障的实操路径。核心结论包括:
torch.Generator,避免因 Diffusers 版本差异导致脚本不可用。下一步可以继续扩展: