• 人工智能
• 媒体生成
• 视频

Viggle-Animate 是一个基于 MiniMax-H3 的AI 视频角色替换模型：只要一段驱动视频加一张重绘帧，就能把视频里的人物换成你画出来的角色。整个推理只依赖一个入口脚本 inference/sample.py，本文逐一讲解它的全部14 个 CLI 命令行参数，包括--steps步数、--flow-shift、--offload显存优化、--audio口型同步等，帮助新手快速上手并调优角色替换效果。

sample.py 是什么：两条输入，一次渲染

理解参数之前，先理解这个工具的输入逻辑（源码见 inference/sample.py）：

• --cond：驱动视频，提供动作、机位、背景和光照；
• --ref：一张静态图（从视频中抽帧后用图像编辑器重绘），提供"新角色长什么样"；
• 其余所有参数都是围绕这两条输入做画质、速度、显存、音频的调节。

模型不加载任何文本编码器，文本条件来自仓库内置的固定嵌入（见 assets/fixed_prompt.txt 与 assets/fixed_embed_fwd_anyframe.pt），所以没有 prompt 参数——你不需要、也无法写提示词。

必填参数清单：跑通推理缺一不可

最小可用命令：

python inference/sample.py --model-dir ./MiniMax-H3 \ --cond driving.mp4 --ref character.png --out swapped.mp4

💡--model-dir指向的仓库只取其中约 11 GB 的 VAE 与调度器文件，完整的 269 GB 不必下载（README Quickstart 给出了精确的下载清单）。

模型路径参数：权重从哪来

本仓库只内置了两个组件，其余来自基础模型：

⚠️ 注意：LoRA 是叠在微调后的Transformer 上的增量，如果换成基础模型自带的transformer_ref，结果会直接变成噪声——这也是--transformer与--model-dir分工不同（一个读分片、一个读 LoRA）的原因。

帧数与画质参数：num-frames、steps、flow-shift

这是新手最常问的一组。默认值--num-frames 124 --steps 4 --flow-shift 3就是官方评测配置，一般无需改动：

一句话记忆：--steps 4 --flow-shift 3是蒸馏模型的黄金组合，不要"加步数换质量"。

分辨率参数：height、width、short-edge

三个参数都建议保持默认：输出尺寸会跟随驱动视频，且两个方向都需为 32 的倍数。显式传一个与素材方向不符的尺寸，模型会静默地输出一段转置视频。

offload 显存省显存：12 GB 也能渲染

显存参考（480×832、124 帧、bf16）：

• ≥ 96 GB 显卡：直接跑，峰值约 80.1 GiB；
• 80 GB 单卡：不够，加--offload再跑；
• 消费级卡（如 32 GB）：仓库本身未提供量化部署方案，但--offload是官方给出的低显存路径。

audio 参数：让嘴跟着真实声音动

默认情况下模型会生成自己的音轨，而固定提示词要求它保持静音——所以默认成片是"嘴在动但没声音"。

加上--audio后，指定文件的音频会被编码为"干净目标潜变量"并贯穿整个去噪过程，模型从"预测音频"变成"条件于音频"，口型就能对上真实人声：

python inference/sample.py --model-dir ./MiniMax-H3 \ --cond driving.mp4 --ref character.png \ --audio driving.mp4 --out swapped.mp4

• 通常是把驱动视频本身再传一次给--audio；
• 音频文件只要是 PyAV 能解码的格式即可，音轨时长不足会自动补静音；
• 这是纯推理期技巧，无需重训练。

完整参数速查表

快速验证环境：demo.sh 一键自检

examples/demo.sh 会用基础模型自带的演示片段裁剪出驱动视频，配合 examples/media/reference.png 跑一次完整替换，产物应与 examples/media/output.mp4 一致：

./examples/demo.sh /path/to/MiniMax-H3

• 结果变成源视频里的原主角→ LoRA 没加载上；
• 结果全是噪声→ 权重路径错了；
• 依赖环境见 requirements.txt：torch 2.9.1+ 指定 commit 的diffusers+av。

常见问题（FAQ）

Q：为什么没有--prompt参数？A：这是设计取舍。外观完全来自你重绘的参考帧，文本编码器根本不加载（固定嵌入见 assets/fixed_embed_fwd_anyframe.pt），所以"改提示词"这条路不存在——想换角色就去改--ref。

Q：--steps调到 12 画质会更好吗？A：不会。4 步是蒸馏学生模型的工作点，官方明确"更多步数不是单调更好，s4 不是劣化的 s12"，反而可能过度锐化。

Q：80 GB 显卡报显存不足？A：加--offload，常驻显存降到约 12 GB，速度会变慢但能跑完。

Q：成片为什么没有声音、嘴还在动？A：默认音轨是固定提示词要求的静音。给命令加上--audio driving.mp4即可让口型跟随真实语音。

小结

Viggle-Animate 的sample.py把角色替换压缩成了"两个必填输入 + 一组调优开关"：日常使用只需--cond、--ref、--out、--model-dir四个参数，其余参数在遇到显存不足（--offload）、无声口型（--audio）、想要更长片段（--num-frames）时再按需添加即可。参数改动记录详见 MODIFICATIONS.md，权重授权条款见 LICENSE。

• 人工智能
• 媒体生成
• 视频