antirez/h3.c 源码：https://github.com/antirez/h3.c # h3-metal 面向 Apple Silicon 的 Native MiniMax-H3 推理。项目以一系列垂直切片的方式逐步构建：先确定主机/模型元数据，然后是可移植的 Metal 块级对齐、提示词编码、提示词到视频/音频、首帧/末帧条件控制，最后是有序引用。提示词到视频/音频、首帧/末帧条件控制以及有序的 Ref2VA 图像/视频/音频引用均已端到端可用。当前的工作是在 M3 Max 和 M5 Max 上逐步进行 H3 特有的 Metal 性能与内存优化。 ## 教程 ### 1. 构建并检查模型 以下示例假定 Hugging Face 快照位于 ./MiniMax-H3，并且 FFmpeg 和 FFprobe 已加入 PATH。 sh make -j8 mkdir -p outputs ./h3 --info -d ./MiniMax-H3 --info 检查模型布局并打印所选的 Metal 设备，无需映射所有权重或生成媒体。运行 ./h3 --help 查看完整 CLI 参考。 在不带 -p 的情况下，同一个二进制会启动 Iris 风格的交互式会话： sh ./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6 输入提示词即可生成带编号的视频。会话会在内存中保留精确的 BF16 提示词条件控制、已准备好的 DiT 和视频解码器，因此用另一个种子重复同一提示词时，无需重新加载和编码它们。常用命令包括 !status、!seed random、!seconds 2、!show、!save output.mp4 和 !cache。使用 !help 查看完整的简短列表。 首帧/末帧条件控制在会话中是持久的： text h3> !first opening.png h3> !last ending.png h3> 相机缓慢环绕主体移动。 使用 !first clear 或 !last clear 移除锚点。生成的视频会写入启动时打印的会话目录。 对于一般的 Ref2VA 条件图像，改用 !ref-image PATH。图像按顺序追加，并以 Picture 1、Picture 2 等形式暴露给模型；文件名对模型没有意义。 text h3> !ref-image person.png h3> 让图 1 中的人物对着镜头挥手。 !refs 列出当前顺序，!ref-remove N 移除一项，!refs clear 全部移除。Ref2VA 引用不能与 !first/!last 锚点混合使用。 ### 2. 制作第一个快速视频 从经过验证的均衡预设开始。它会以 24 fps 生成 22 帧（约 0.92 秒），在支持的图形终端中每次去噪转换后显示演变中的中间视频帧，并打印各阶段耗时： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." \ --width 512 --height 512 \ --frames 22 --steps 20 \ --layers 45 --reuse 2 \ --show \ -o outputs/fox-fast.mp4 这刻意不是最激进的配置： - --steps 20 执行默认的 20 次去噪传递。 - --reuse 2 只计算 11 个新的去噪速度，而不是全部 20 个，并外推跳过的转换。 - --layers 45 运行 50 个 transformer 块中的 45 个，同时减少时间和统一内存使用。 - --show 是可选的。它支持 Kitty/Ghostty 和 iTerm2/WezTerm/Konsole 图形协议。它会加载常驻预览 VAE，在每次 Euler 转换后显示一帧具有代表性的中间视频帧，然后显示所有最终帧。显示尺寸默认是 2 倍，这样图像在 macOS Retina 屏幕上具有预期的逻辑尺寸；在非 HiDPI 显示器上使用 --zoom 1。这会增加预览解码时间以及约 10 GiB 的临时模型驻留；不带 --show 的运行不变。 - --profile 是可选的，不会选择不同的生成路径。 首次进程调用还要付出模型加载和文件系统缓存成本。请使用重复运行来比较性能，并在机器预热时交替使用不同变体，因为此工作负载对热降频很敏感。 若要快速迭代，可直接请求四次去噪传递： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur." \ --width 512 --height 512 --frames 22 \ --steps 4 --layers 50 --reuse 1 \ --show \ -o outputs/fox-four-step.mp4 --steps N 始终表示恰好 N 次去噪传递。四到七次传递使用与低预算对比中胜出的相同调度；从 4 增加到 7 会逐步改善细节和运动。在如此小的预算下请保持 --reuse 1，这样每次请求的传递都会运行模型。--show 在每次传递后显示一帧预览。 评估了几种尾部加重的调度，因为大部分可见清理发生在长跑后期。它们保留了过少的早期构图更新，产生了编织纹理、弱运动或裁剪色彩。保留的模式使用带有单个终点的线性基础网格。在 512 方形、22 帧的狐狸测试中，所选的 4 步结果相对于 29 步参考的全视频 SSIM 为 0.556；独立的冲浪者测试为 0.547。四步去噪在 M5 Max 上约耗时 3.5 秒，而参考耗时 26.4 秒。 ### 3. 接近参考质量 评估质量时一次只改一个控制项。先恢复所有层，然后恢复所有去噪器评估，最后将默认的 20 步调度提高到更慢的 50 步参考： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." \ --width 512 --height 512 \ --frames 22 --steps 50 \ --layers 50 --reuse 1 \ -o outputs/fox-close.mp4 默认值是 --steps 20 --layers 50 --reuse 1；对于这条接近路径，请显式保留 --steps 50。它会执行 50 次完整的 50 块去噪器前向，比默认昂贵得多，但当快速模式改变主体、解剖结构、运动或构图时，它是正确的参考基准。 与 MLX 不保证数值像素一致，因为随机数和执行引擎不同；所描绘的内容和运动应该一致。 ### 4. 选择速度/质量预设 除非另有说明，这些控制项是独立的： | 控制项 | 慢速参考 | 默认 | 激进 | 主要影响 | |—|—:|—:|—:|—| | 去噪传递 | --steps 50 | --steps 20 | --steps 4..7 | 该数字始终表示实际去噪传递次数。 | | 整个去噪器复用 | --reuse 1 | --reuse 2 | --reuse 3 | 20 步时：20、11 或 8 次新的 DiT 评估。 | | 活跃 DiT 块 | --layers 50 | --layers 45 | --layers 40 | 更少的块减少计算量和常驻 transformer 权重。 | | 核心残差复用 | --core-reuse 1 | --core-reuse 4 | --core-reuse 6 | 每一步都刷新 patch/head 工作，但较不频繁地运行昂贵的核心。 | | Token 缩减 | 关闭 | 可选 | --token-reduction | 在中间块内配对水平视频 token；更快但可能改变构图。 | | 内部画布 | 输出尺寸 | 512 方形输出使用 384x384 | 320x320 | 以较小尺寸运行 DiT/VAE，然后使用 vImage 放大。 | 在 M5 上，--use-int8-row-fc2 每个 FC2 行使用一个激活缩放和单个全宽度 TensorOps 乘积。它是可选的，因为它不像分组 int8 那样在数值上保守。在互惠测试中，它将完整去噪器前向减少了约 2.6%。匹配的四步狐狸和冲浪者视频保持了相同的主体、场景和运动（全视频 SSIM 0.919 和 0.828）。在交互式会话中使用 !int8-row-fc2 on。 --reuse 和 --core-reuse 互斥。层稀疏化可以与两者中的任意一个组合。 若要在保持输出分辨率的同时让第一个命令更快，请添加 token 缩减： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A surfer riding inside a sharp blue ocean wave, one rider and one white board, realistic spray." \ --width 512 --height 512 --frames 22 --steps 20 \ --layers 45 --reuse 2 --token-reduction \ -o outputs/surfer-fast.mp4 在已验证的 512 方形形状下，token 缩减将 45 layers + reuse 2 去噪配置从 IT M5 Max 上的 16.69 秒降至 12.60 秒。独立的狐狸和冲浪者渲染保持一致，但构图可能与接近路径有更大差异。 对于激进的预览，在内部以 320 方形渲染并放大到请求的 512 方形输出： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A red fox walking through snow, realistic, tracking shot." \ --width 512 --height 512 \ --render-width 320 --render-height 320 \ --frames 22 --steps 20 --layers 40 --reuse 3 \ -o outputs/fox-aggressive.mp4 该组合在验证中产生了清晰可识别的 22 帧狐狸，但丢失了精细细节并可能改变取景。 不要同时在 --layers 40 和 --reuse 3 上添加 --token-reduction：该测试组合产生了颜色振铃、轮廓和重影肢体。 作为整体速度复用的替代方案，以下配置让依赖时间步长的 patch 和输出头在每次转换时都保持新鲜： sh ./h3 --profile \ -d ./MiniMax-H3 \ -p "A surfer riding a blue ocean wave." \ --width 512 --height 512 --frames 22 --steps 20 \ --layers 45 --core-reuse 4 \ -o outputs/surfer-core-reuse.mp4 仅将 --core-reuse 6 用作激进预览。不暴露 6 以上的值，因为验证中主体保真度下降。 ### 5. 选择分辨率和时长 宽度和高度必须分别是 32 的倍数、至少为 32，且它们的乘积不能超过 768 * 1344 像素。这些是机械限制，并非承诺每个小画布都有良好的模型质量。H3-Base 是 768p 模型。 | 画布 | 当前指导 | |—|—| | 512x512 | 最安全的开发尺寸；已用多个提示词反复验证。 | | 768x768 | 已验证的接近质量方形输出；成本显著更高。 | | 1344x768、768x1344 | 发布的 768p 级横屏/竖屏限制。 | | 1024x768、768x1024 | 有效的 4:3 和 3:4 768p 级画布。 | | 384x384 内部到 512x512 | 已验证的快速质量缩放点。 | | 320x320 内部到 512x512 | 已验证的激进缩放点。 | | 256x256 | 原生快速预览画布，带自动低分辨率 RoPE 适配。 | 对于快速的原生 256 方形预览： sh ./h3 -d ./MiniMax-H3 \ -p "A red fox walks through fresh snow in a pine forest." \ --width 256 --height 256 \ --frames 22 --steps 20 \ --layers 50 --reuse 1 \ -o outputs/fox-256.mp4 在 256 方形下，H3 只有 8x8 的有效空间 token 网格，因此精细细节和复杂构图的空间更小。H3 在恰好 256 方形时自动将空间 RoPE 坐标减半。这消除了长狐狸渲染中的重复晶格伪影，并在独立肖像上保持一致，且不增加 token 或运行时。使用 --use-reference-rope 恢复发布版/MLX 坐标以进行一致性检查。在此尺寸下保持 token 缩减关闭。 原生 128 方形仍不受支持：即使调整了 RoPE，其 4x4 token 网格也无法恢复可识别的主体。 --render-width 和 --render-height 必须同时设置，必须与输出具有相同的宽高比，且不能超过输出尺寸。模型和 VAE 使用内部尺寸；终端帧和编码视频保持请求的输出尺寸。 H3 输出 24 fps，并将帧请求向上对齐到 5 + 17*n： 使用 --seconds N 进行面向时长的请求，或使用 --frames N 直接控制帧数；两个选项互斥。支持小数秒。秒以 24 fps 转换，然后向上取整到下一个合法的 H3 时间形状，因此 --seconds 10 产生 243 帧（10.125 秒）。 | 帧数 | 大致视频时长 | |—:|—:| | 22 | 0.917 秒 | | 39 | 1.625 秒 | | 56 | 2.333 秒 | | 107 | 4.458 秒 | | 243 | 10.125 秒 | | 362 | 15.083 秒 | 短片适合开发。发布的工作流面向大约 4–15 秒的视频。诸如 --frames 23 的请求会向上取整到 39 帧，而不是产生任意的时间形状。 ### 6. 改进提示词 短提示词有效，但发布的系统期望类似于 Context-IR 的描述。请说明主体、动作、场景、相机、光照/风格以及期望的声音。例如： text 场景：一只红狐在黎明时分覆盖着雪松林中。 动作：狐狸稳定地从左向右走，并朝镜头看了一次。 相机：中高机位横向跟拍，50 mm 镜头，画面稳定。 外观：照片级真实毛皮，冷蓝色环境光，暖日出轮廓光。 音频：雪中轻柔脚步声，松枝间微风，无音乐。 当身份和对象数量重要时，请明确说明。 --seed N 控制原生随机流；默认为 42。比较选项时请使用相同的提示词、种子、分辨率、帧数和步数。 ### 7. 预览帧并诊断性能 - --show 在每次去噪转换后显示一帧代表性图像，然后是完成视频的所有帧。与 Iris 一样，它默认在 Retina 终端上以 2 倍显示尺寸显示；--zoom N 改变该因子，但不会缩放生成的视频或编码的终端图像。 - --frames-dir DIR 将最终回调帧写入 PPM 文件。中间的 --show 预览不会写入那里。 - -o '' 禁用 MP4 编码；当 FFmpeg 不可用时，将其与 --frames-dir 结合使用。 - --profile 报告各阶段墙钟时间、Metal 编码/等待时间、峰值活动张量存储、累计分配和调度计数。例如： sh ./h3 --profile -d ./MiniMax-H3 -p "A hummingbird hovering over red flowers." \ --width 512 --height 512 --frames 22 --steps 20 \ --layers 45 --reuse 2 --frames-dir outputs/hummingbird-frames \ -o '' ### 8. 添加图像、视频和音频引用 首帧/末帧锚点选择 FL2VA 路径： sh ./h3 -d ./MiniMax-H3 -p "The fox keeps walking through the snow." \ --width 512 --height 512 --frames 22 --steps 20 \ --layers 45 --reuse 2 \ --first-frame fox.png --last-frame fox-later.png \ -o outputs/fox-anchored.mp4 有序引用选择不同的 Ref2VA 检查点。请使用与媒体语义匹配的标志： sh # 一个图像引用。 ./h3 -d ./MiniMax-H3 -p "Use the animal and setting in the reference." \ --width 512 --height 512 --frames 22 --steps 20 \ --ref-image fox.png -o outputs/fox-reference.mp4 # 继续片段但忽略其配乐。 ./h3 -d ./MiniMax-H3 -p "Continue the motion in this clip." \ --width 512 --height 512 --frames 22 --steps 20 \ --ref-silent-video fox.mp4 -o outputs/fox-video-reference.mp4 # 保留片段内嵌音频。 ./h3 -d ./MiniMax-H3 -p "Continue this audiovisual scene." \ --width 512 --height 512 --frames 56 --steps 20 \ --ref-video fox-with-audio.mp4 -o outputs/fox-video-audio.mp4 # 显式替换视频的配乐。 ./h3 -d ./MiniMax-H3 -p "Continue the scene with the supplied music." \ --width 512 --height 512 --frames 56 --steps 20 \ --ref-video-audio silent-fox.mp4 replacement.wav \ -o outputs/fox-replaced-audio.mp4 # 有序图像加上独立音频引用。 ./h3 -d ./MiniMax-H3 -p "Use the animal and music from the references." \ --width 512 --height 512 --frames 56 --steps 20 \ --ref-image fox.png --ref-audio music.wav \ -o outputs/fox-image-audio.mp4 引用标志可以重复，且命令行顺序会被保留。独立音频必须伴随图像或视频引用。音频引用必须为 2–15 秒；最多接受三个音频输入，其总解码时长上限为 15 秒。 ## 测试与运行时要求 sh make test make parity make test 运行确定性主机套件，并且当被忽略的 MLX 固定数据安装到 misc/fixtures/ 下时，会在运行时编译 Metal 源码，并对照指定的 MLX 输出检查一个完整的玩具 H3 块。运行时编译是有意为之：它遵循 Iris 的做法，不要求 Xcode 的可选离线 Metal 工具链。测试涵盖两种