OpenMontage 如何在 NVIDIA GPU 上启用本地视频生成并选择匹配的 Wan、Hunyuan 模型

OpenMontage 如何在 NVIDIA GPU 上启用本地视频生成并选择匹配的 Wan、Hunyuan 模型

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

如果你有一块 NVIDIA 显卡，想让 OpenMontage 不调用任何云端 API 就能自己生成视频，需要完成三件事：装好 GPU 依赖栈、在.env里开启本地生成开关、按显存大小选一个能跑起来的 Wan 或 Hunyuan 模型。做完后，wan_video、hunyuan_video等本地工具会被注册进工具菜单，整个流程免费且离线。本文基于 docs/PROVIDERS.md 的 "Local Video Generation (GPU Required)" 一节、Makefile 和 README.md 整理。

前提条件

• 一块显存足够的 NVIDIA GPU（本地视频生成要求 CUDA 运行时，即 NVIDIA 卡；具体显存门槛见下面的选型表）。
• Python 3.10+。Makefile 的ensure-venv会检查解释器版本，缺失时提示安装uv或更高版本 Python 后重试。
• 项目已 clone 到本地并可以运行make。

第一步：安装 GPU 依赖栈

在项目根目录执行：

make install-gpu

这个目标由 Makefile 定义，实际做两件事：

1. pip install -r requirements-gpu.txt—— 安装 requirements-gpu.txt 中列出的torch>=2.0、torchaudio>=2.0、torchvision>=0.15；
2. pip install diffusers transformers accelerate—— 本地视频生成依赖的推理库。

如果没有make，也可以按 docs/PROVIDERS.md 给出的手动方式安装：

pip install diffusers transformers accelerate torch pillow requests

注意：requirements-gpu.txt文件头注明这些依赖是在requirements.txt基础之外追加安装的。如果还没跑过make setup，项目核心依赖（PyYAML、pydantic、fastapi 等）尚未安装，先执行make setup。

第二步：在 .env 中启用本地生成

make setup会从.env.example生成.env。在.env中加入两行：

# 1. 打开本地视频生成开关 VIDEO_GEN_LOCAL_ENABLED=true # 2. 按你的 GPU 显存选一个模型 VIDEO_GEN_LOCAL_MODEL=wan2.2-ti2v-5b

VIDEO_GEN_LOCAL_ENABLED接受true、1、yes（见 tools/video/_shared.py 中的判断逻辑）。VIDEO_GEN_LOCAL_MODEL决定加载哪个本地检查点，可选值及其显存要求来自 docs/PROVIDERS.md：

如何为 Wan 和 Hunyuan 做选型

按显存分档，Wan 与 Hunyuan 的选择逻辑是：

• 12GB 显存（如 3060 12G/4070 级别）：Wan 2.2 TI2V 5B 与 Hunyuan 1.5 都要求 12GB+。Wan 2.2 TI2V 5B 是文档标注的默认模型，一个检查点同时支持 text-to-video、image-to-video、video-to-video；Hunyuan 1.5 在 tools/video/_shared.py 的HUNYUAN_VARIANTS中标记t2v与i2v均为支持，默认输出 848x480。两者都能跑，文档没有在这两个之间做质量排序，可按自己偏好的模型系列选。
• 6GB 显存：只能选wan2.1-1.3b（或 CogVideo 2B）。注意 Wan 2.1 1.3B 官方没有 I2V 权重，docs/PROVIDERS.md明确 "Wan 2.1 never shipped 1.3B I2V weights"，它只适合文生视频。
• 24GB+ 显存：wan2.1-14b提供 Wan 2.1 系最高质量，支持 T2V/I2V/V2V/首尾帧插值等全部 Wan 操作，但速度标记为 Slow。
• 8–10GB 显存：标题场景之外的替代选项是ltx2-local（8GB+，最快）和cogvideo-5b（10GB+），但 CogVideo 只有文生视频，不支持图生视频。

一个容易混淆的点：本地 Hunyuan（hunyuan_video，模型值hunyuan-1.5，需要 GPU 且免费）与腾讯云 Hunyuan（hunyuan_cloud_video，需要TENCENT_TOKENHUB_API_KEY，按次付费）是两条互不相干的路径，环境变量也不同。本文只覆盖前者。

验证本地工具已生效

运行项目自带的 preflight 检查，它会调用工具注册表并打印当前环境可用/不可用的 provider 菜单：

make preflight

该命令在 Makefile 中定义为执行registry.discover()后输出registry.provider_menu()的 JSON。本地视频生成正确启用后，菜单中应出现wan_video、hunyuan_video、cogvideo_video、ltx_video_local这几个由VIDEO_GEN_LOCAL_ENABLED解锁的工具（见 docs/PROVIDERS.md 的 "Provider-to-Tool Mapping" 表中Local GPU一行）。

之后通过 AI 编码助手调用wan_video或hunyuan_video时，工具会按所选检查点的operations能力表拒绝它做不了的操作（例如用wan2.1-1.3b请求图生视频会被直接拒绝，而不是悄悄加载错误的 14B 检查点）。

NVIDIA 驱动版本不一致的处理

docs/PROVIDERS.md专门记录了一个 NVIDIA 特有的坑：如果已加载的 kernel 模块与用户态驱动库版本不一致，nvmlInit会失败，表现为：

• CUDA 计算本身仍然能跑，但 PyTorch 在组装 OOM 报告时会调用 NVML，导致真实的显存不足（OOM）以 internal assert 的形式爆出；
• int8/int4精度的 bitsandbytes 无法加载。

排查方法是对比两条命令的输出：

cat /proc/driver/nvidia/version nvidia-smi

如果两者显示的驱动版本不一致，文档给出的解决办法是重启机器。wan_video工具会检测这种状态并在结果中说明。

12GB 显卡的显存适配参数

如果你按文档实测遇到 12GB 卡上显存吃紧，wan_video提供两个都默认auto的参数：

• precision：auto/bf16/int8/int4；
• offload_mode：auto/model/sequential。

文档给出的 12GB 实测数据（来源：docs/PROVIDERS.md，属文档示例/实测值，不是固定预期）：bf16 的 5B transformer 常驻约 10GB，用offload_mode="model"时峰值达 10.85GB（仅 512x320）；换成offload_mode="sequential"（逐个子模块流式加载）后同一张卡峰值降到 1.97GB，可以舒服地渲染 704x480，代价是每个去噪步约 4s 的 PCIe 传输。在 12GB GPU 上auto会自动选择sequential。

已知限制

• 图生视频不是所有模型都支持：Wan 2.1 1.3B 没有 I2V 权重，CogVideo 仅文生视频。每个变体的真实能力列表在 tools/video/_shared.py 的operations字段，wan_video对不支持的操作会直接拒绝。
• TI2V 线的 720p 是 1280x704 而不是 1280x720：Wan 2.2 TI2V 的 VAE 空间压缩 16 倍、transformer 再 2 倍 patching，宽高必须是 32 的倍数，而 720 不是；其他线是 16 的倍数。帧数落在4k + 1。
• 长片段的漂移：Wan 大约按 5 秒一段训练，请求更长片段（duration_seconds）时工具会串联多段，每段以上一段末帧作为新帧 0。文档指出串联会漂移（对比度和色彩渐变），correct_drift默认开启用于校正；如需逐镜头控制可用segment_prompts。

完成以上步骤后，你的验证落点就是：make preflight菜单中出现本地视频工具，且wan_video/hunyuan_video能按所选检查点的operations正常执行请求。若某操作被拒，回查所选模型在operations列表里的能力，而不是怀疑开关没生效。

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage