h3-metal：Apple Silicon 原生推理 MiniMax-H3

h3-metal 为 Apple Silicon 提供原生 MiniMax-H3 推理。该项目以一系列垂直切片的方式构建：先确定主机/模型元数据，然后是便携式 Metal 块对齐、提示编码、提示到视频/音频、首帧/末帧条件控制，最后是有序引用。提示到视频/音频、首帧/末帧条件控制以及有序的 Ref2VA 图像/视频/音频引用已端到端工作。当前工作是在 M3 Max 和 M5 Max 上针对 H3 特定的 Metal 性能和内存优化进行增量改进。## 教程 ## 1. 构建并检查模型 示例假设 Hugging Face 快照位于 ./MiniMax-H3，且 FFmpeg 和 FFprobe 在 PATH 中可用。``` make -j8 mkdir -p outputs ./h3 --info -d ./MiniMax-H3 ``` --info 检查模型布局并打印选定的 Metal 设备，而不映射所有权重或生成媒体。运行 ./h3 --help 查看完整的 CLI 参考。不带 -p 时，同一二进制文件会启动 Iris 风格的交互式会话：``` ./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6 ``` 输入提示词以生成带编号的视频。会话会将精确的 BF16 提示条件、准备好的 DiT 和视频解码器保留在内存中，因此使用另一个种子重复提示词可避免重新加载和编码它们。有用的命令包括 !status、!seed random、!seconds 2、!show、!save output.mp4 和 !cache。使用 !help 查看完整的简短列表。首帧/末帧条件控制在会话中是持久的：``` h3> !first opening.png h3> !last ending.png h3> 相机围绕主体缓慢移动。 ``` 使用 !first clear 或 !last clear 移除锚点。生成的视频写入启动时打印的会话目录。对于一般的 Ref2VA 条件图像，改用 !ref-image PATH。图像按顺序追加，并作为 、 等暴露给模型；文件名对模型没有意义。``` h3> !ref-image person.png h3> 让图 1 中的人物向镜头挥手。 ``` !refs 列出当前顺序，!ref-remove N 移除一个条目，!refs clear 移除所有条目。Ref2VA 引用不能与 !first/!last 锚点混合使用。## 2. 制作第一个快速视频 从经过验证的平衡预设开始。它会以 24 fps 生成 22 帧（约 0.92 秒），在支持的图形终端中每次去噪转换后显示演变的中间视频帧，并打印各阶段耗时： ``` ./h3 --profile \ -d ./MiniMax-H3 \ -p "一只红狐在松林中走过新雪。中景跟拍，自然的冬季光线，逼真的皮毛，轻柔的脚步声和风声。" \ --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 是可选的，不选择不同的生成路径。第一次进程调用还会产生模型加载和文件系统缓存成本。使用重复运行来比较性能，并在机器预热时交替使用变体，因为此工作负载对热节流敏感。对于非常短的迭代，直接请求四次去噪传递： ``` ./h3 --profile \ -d ./MiniMax-H3 \ -p "一只红狐在松林中走过新雪。中景跟拍，自然的冬季光线，逼真的皮毛。" \ --width 512 --height 512 --frames 22 \ --steps 4 --layers 50 --reuse 1 \ --show \ -o outputs/fox-four-step.mp4 ``` --steps N 始终表示恰好 N 次去噪传递。第4到第7遍使用与赢得低预算比较相同的调度；从4增加到7逐步改善细节和运动。在如此小的预算下保持--reuse 1，以便每个请求的遍数都运行模型。--show在每次遍后显示一个预览。评估了几种尾部重的调度，因为大多数可见的清理发生在长时间运行的后期。它们保留了太少的早期构图更新，并产生了编织纹理、弱运动或裁剪颜色。保留模式使用发布的线性基础网格，带有一个终点。在512方形、22帧狐狸测试中，选定的四遍结果相对于29遍参考的全视频SSIM为0.556；独立的冲浪者测试测得0.547。四遍去噪在M5 Max上大约需要3.5秒，而参考需要26.4秒。## 3. 向参考质量迈进 评估质量时一次更改一个控制。首先恢复所有层，然后进行所有去噪器评估，最后将默认的20遍调度提高到较慢的50遍参考：``` ./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-reduction | 在中间块内配对水平视频令牌；更快但可能改变构图。内部画布 | 输出尺寸 | 384x384用于512方形输出 | 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互斥。层稀疏化可以与任一组合。要使第一个命令更快同时保持输出分辨率，添加令牌减少：``` ./h3 --profile \ -d ./MiniMax-H3 \ -p "一个冲浪者在尖锐的蓝色海浪中冲浪，一个冲浪者和一块白色冲浪板，逼真的水花。" \ --width 512 --height 512 --frames 22 --steps 20 \ --layers 45 --reuse 2 --token-reduction \ -o outputs/surfer-fast.mp4 ```