Viggle-Animate sample.py参数全解：CLI命令行参考手册

人工智能媒体生成视频【免费下载链接】Viggle-Animate项目地址https://ai.gitcode.com/hf_mirrors/Viggle/Viggle-Animate点击查看免费下载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 参数——你不需要、也无法写提示词。必填参数清单跑通推理缺一不可参数作用说明--cond驱动视频保留动作与背景的源视频--ref参考帧图片重绘后的单帧决定新角色外观--out输出路径最终 mp4 保存位置--model-dir基础模型目录指向本地 MiniMax-H3 副本用于加载 VAE / 音频 VAE / 调度器最小可用命令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 给出了精确的下载清单。模型路径参数权重从哪来本仓库只内置了两个组件其余来自基础模型参数默认值说明--transformertransformer/33.1 B 全量微调 Transformer14 个分片约 62 GiB--loralora/pytorch_lora_weights.safetensorsDMD2 蒸馏增量把采样器压缩到 3 次前向--embedassets/fixed_embed_fwd_anyframe.pt冻结的 362×5120 文本嵌入替代文本编码器⚠️ 注意LoRA 是叠在微调后的Transformer 上的增量如果换成基础模型自带的transformer_ref结果会直接变成噪声——这也是--transformer与--model-dir分工不同一个读分片、一个读 LoRA的原因。帧数与画质参数num-frames、steps、flow-shift这是新手最常问的一组。默认值--num-frames 124 --steps 4 --flow-shift 3就是官方评测配置一般无需改动参数默认新手建议--num-frames12424 fps 下约 5.2 秒内部会自动对齐到 VAE 网格17n5--steps44 个 sigma 边界 3 次前向。蒸馏模型的工作点加大步数不是更平滑反而会过度锐化--flow-shift3.0基础模型默认是 12少步数学生模型必须配 3改大易翻车--seed42固定随机种子便于复现官方全部示例都用 42一句话记忆--steps 4 --flow-shift 3是蒸馏模型的黄金组合不要加步数换质量。分辨率参数height、width、short-edge参数默认说明--height跟随驱动视频不填最安全--width跟随驱动视频输出几何直接取自素材避免转置陷阱--short-edge驱动视频短边参考素材在画布上的布局尺寸模型就是按这个评测的三个参数都建议保持默认输出尺寸会跟随驱动视频且两个方向都需为 32 的倍数。显式传一个与素材方向不符的尺寸模型会静默地输出一段转置视频。offload 显存省显存12 GB 也能渲染参数类型效果--offload开关不取值把 Transformer 按每 5 个 block 一组从 CPU 流式搬到 GPU常驻显存从约 62 GB 降到约 12 GB代价是速度明显变慢显存参考480×832、124 帧、bf16≥ 96 GB 显卡直接跑峰值约 80.1 GiB80 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 能解码的格式即可音轨时长不足会自动补静音这是纯推理期技巧无需重训练。完整参数速查表参数必填默认值一句话说明--cond✅—驱动视频动作/机位/背景来源--ref✅—重绘参考帧新角色外观来源--out✅—输出 mp4 路径--model-dir✅—本地 MiniMax-H3 目录VAE/调度器--transformertransformer/微调 Transformer 分片目录--loralora/蒸馏 LoRA 增量目录--embedassets/fixed_embed_fwd_anyframe.pt固定文本嵌入--num-frames124帧数24 fps 下约 5.2 s--steps4蒸馏采样步数4 边界 3 前向--flow-shift3.0流调度 shift少步数模型用 3--height同素材输出高度32 的倍数--width同素材输出宽度32 的倍数--short-edge素材短边参考素材布局画布尺寸--offload关按 block 组流式上卡显存约 12 GB--audio无钉住真实音轨口型跟随语音--seed42随机种子快速验证环境demo.sh 一键自检examples/demo.sh 会用基础模型自带的演示片段裁剪出驱动视频配合 examples/media/reference.png 跑一次完整替换产物应与 examples/media/output.mp4 一致./examples/demo.sh /path/to/MiniMax-H3结果变成源视频里的原主角→ LoRA 没加载上结果全是噪声→ 权重路径错了依赖环境见 requirements.txttorch 2.9.1 指定 commit 的diffusersav。常见问题FAQQ为什么没有--prompt参数A这是设计取舍。外观完全来自你重绘的参考帧文本编码器根本不加载固定嵌入见 assets/fixed_embed_fwd_anyframe.pt所以改提示词这条路不存在——想换角色就去改--ref。Q--steps调到 12 画质会更好吗A不会。4 步是蒸馏学生模型的工作点官方明确更多步数不是单调更好s4 不是劣化的 s12反而可能过度锐化。Q80 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。赞分享人工智能媒体生成视频【免费下载链接】Viggle-Animate项目地址https://ai.gitcode.com/hf_mirrors/Viggle/Viggle-Animate点击查看免费下载相关推荐SWF逆向工程教学实验室基于JPEXS Free Flash Decompiler的完整课程设置SWF逆向工程教学实验室基于JPEXS Free Flash Decompiler的完整课程设置 JPEXS Free Flash Decompiler是一款逆向工程桌面应用开发工具Claude Code CLI 完全指南claude-howto 命令行参考手册Claude Code CLI 完全指南claude howto 命令行参考手册 Claude Code 的命令行接口CLI是与 Claude Code文档教程知识库AppImageLauncher命令行参数大全ail-cli完整参考AppImageLauncher命令行参数大全ail cli完整参考 引言解决AppImage集成痛点 你是否曾为AppImage文件的管理感到困扰手动创桌面应用CLI上一篇如何微调 regnety_040.ra3_in1k将 ImageNet 预训练权重迁移到你的图像数据集下一篇Ming-3.0-asr-tiny-bf16是如何从PyTorch转换为MLX的bf16精度与权重映射原理解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考