企业官网建设流程全解析

h3.c多模态参考生成Ref2VA详解：图片、视频、音频参考一次讲透

【免费下载链接】h3.cMiniMax H3 inference engine for Mac computers项目地址: https://gitcode.com/gh_mirrors/h3/h3.c

h3.c 是一款面向 Mac（Apple Silicon）的 MiniMax H3 视频/音频生成原生推理引擎，其中的 Ref2VA（Reference-to-Video/Audio）参考生成能力允许你用图片、视频、音频作为"参考素材"来驱动生成，而不是仅靠文字描述。本文用通俗语言一次讲透：Ref2VA 是什么、五种参考入口怎么用、模型如何"读懂"你的参考，以及需要注意的限制。

什么是 Ref2VA：从"文字描述"到"照着参考生成"

普通的文生视频（T2VA）只靠提示词"想象"画面；而Ref2VA会先理解你给的参考素材——一张人物图、一段视频、一段音乐——再据此生成新的音视频内容。典型场景：

• 🖼️ 拿一张人物照片，生成"图里这个人向镜头挥手"的视频
• 🎬 给一段 3 秒的片段，让模型"续拍"后续画面
• 🎵 给一段音乐，生成画面与配乐同步的短视频

在 h3.c 中，Ref2VA 是一条独立于 T2VA 和 FL2VA（首尾帧锚定）的生成路径，使用专门的 Ref2VA 检查点与 DiT 变换器（见 h3.h 中的ref2va_transformer组件）。命令行中只要使用参考类参数，就会自动切换到这条路径。

五种参考入口：按"素材语义"选对参数

参考类参数定义在 main.c 的帮助文本中。选择原则很简单：素材里有什么内容，就用哪个旗标。

1. 图片参考：--ref-image

最基础的用法，追加一张有序的参考图：

./h3 -d ./MiniMax-H3 -p "使用参考图中的动物和场景。" \ --ref-image fox.png -o outputs/fox-reference.mp4

多张图片按命令行顺序排列，分别对应<Picture 1>、<Picture 2>……模型不关心文件名，只认顺序。

2. 视频参考：--ref-silent-video与--ref-video

• --ref-silent-video fox.mp4：只取画面、丢弃原视频的声音，适合"续拍画面但重新配声"
• --ref-video fox-with-audio.mp4：保留视频内嵌的音轨，画面和声音一起作为参考

3. 视频 + 显式替换音频：--ref-video-audio

想沿用视频画面、但换一首音乐？把视频和音频分开传：

./h3 ... --ref-video-audio silent-fox.mp4 replacement.wav

4. 独立音频参考：--ref-audio

单独追加一段音乐或音效参考，例如与图片组合：

./h3 ... --ref-image fox.png --ref-audio music.wav

⚠️ 注意：独立音频必须搭配图片或视频参考，不能单独使用（见 h3_multimodal.c 的校验逻辑）。

所有参考旗标都可以重复出现，命令行顺序会被完整保留并暴露给模型——排列顺序直接影响生成结果。

模型如何"读懂"参考：标签、顺序与时间戳

这是 Ref2VA 最有意思的部分，核心实现位于 h3_multimodal.c 的h3_multimodal_encode_ref2va_bf16：

几个关键点：

• 视频会被"切片"：视频参考以 2 帧为一块送入视觉编码器（Qwen 视觉塔），每块都带一个时间戳标签，让模型理解"第几秒发生了什么"（见 h3_multimodal.h 中的注释说明）
• 提示词写在最后：所有参考标签先排好队，你的文字提示词追加在末尾，用 "Picture 1 里的人" 这类措辞即可指代素材
• 图文统一编码：标签、视觉特征与提示词一起交给 Qwen 文本编码器，输出统一的 BF16 嵌入供 DiT 使用；音频则走 AudioVAE 后验均值路径，与视觉参考共享同一条旋转位置编码时间线（详见 README.md 的 "Checkpoint layout and media pipeline" 一节）

快速参考：使用限制一览

交互式会话中管理参考

不带-p参数启动 h3 可进入交互式会话，参考管理更方便（说明见 h3_cli.c）：

• !ref-image PATH— 追加一张有序参考图
• !refs— 列出当前参考顺序
• !ref-remove N— 删除第 N 条参考
• !refs clear— 清空全部参考

然后直接输入提示词（如 "让 Picture 1 中的人向镜头挥手"）即可生成。会话中的参考与首尾帧锚定同样是互斥的。

给想深入的同学：相关源码位置

• 参考呈现（标签/时间戳/位置编码）：h3_multimodal.c、接口定义 h3_multimodal.h
• CLI 参数解析：main.c
• 视频参考文本编码的真实权重一致性测试：tests/test_real_ref_video_text.c
• 完整教程与参数说明：README.md（"Add image, video, and audio references" 一节）

小结

Ref2VA 让 h3.c 从"文字生成"升级为"参考生成"：图片、视频、音频三种素材各有专属旗标，按顺序传入即可获得带编号标签的结构化参考；理解"顺序即语义、时间戳即位置"这两个概念，就能驾驭绝大多数参考生成场景。建议先从单张--ref-image开始，再逐步尝试视频续拍与音频替换，最后用--profile观察各阶段耗时。

【免费下载链接】h3.cMiniMax H3 inference engine for Mac computers项目地址: https://gitcode.com/gh_mirrors/h3/h3.c