h3-metal: 面向 Apple Silicon 的原生 MiniMax-H3 推理引擎

h3-metal 为 Apple Silicon 提供原生的 MiniMax-H3 推理支持，实现了一系列优化的垂直切片，包括确定性的 host/model 元数据、可移植的 Metal block 对齐，以及对 prompt-to-video/audio、首/尾帧条件控制和有序引用的端到端支持。该项目专注于在 M3 Max 和 M5 Max 硬件上实现性能和内存效率的最大化。

高性能推理预设

用户可以通过几个独立的控制参数来平衡生成速度和输出质量。默认配置为 20 次去噪步数，包含 50 个 transformer blocks，且重用因子为 1。

速度与质量权衡

Control	Slow Reference	Default	Aggressive	Main Impact
Denoising Passes	`--steps 50`	`--steps 20`	`--steps 4..7`	总实际去噪步数。
Whole Denoiser Reuse	`--reuse 1`	`--reuse 2`	`--reuse 3`	减少新的 DiT 评估次数（例如，20 步 $\to$ 11 或 8 步）。
Active DiT Blocks	`--layers 50`	`--layers 45`	`--layers 40`	减少计算量和常驻的 transformer weights
Core Residual Reuse	`--core-reuse 1`	`--core-reuse 4`	`--core-reuse 6`	每步刷新 patch/head 工作，但减少昂贵的核心计算频率。
Token Reduction	Off	Optional	`--token-reduction`	在中间 blocks 中配对水平视频 tokens；速度更快，但可能影响构图。
Internal Canvas	Output Size	`384x384`	`320x320`	以较小的尺寸运行 DiT/VAE，然后通过 vImage 进行上采样。

性能基准测试

在 M5 Max 上，针对 512x512 像素、22 帧的测试，四步去噪耗时约 3.5 秒，而 29 步参考配置耗时 26.4 秒。在 512x512 画布上使用 token reduction 将去噪时间从 16.69 秒降低至 12.60 秒。

高级条件控制与媒体支持

h3-metal 支持多种条件控制路径，以实现超越简单文本提示词的视频生成控制。

帧锚定与引用

FL2VA Path: 使用 --first-frame 和 --last-frame 来锚定视频序列的开始和结束。
Ref2VA Path: 通过 --ref-image、--ref-silent-video 和 --ref-video 使用有序引用，以保持主体和场景的一致性。
Audio Integration: 支持通过 --ref-audio 进行独立音频引用，或在视频引用中嵌入音频。音频输入总时长限制在 15 秒以内，最多支持三个输入。

分辨率与时长

宽度和高度必须是 32 的倍数，最大乘积为 $768 \times 1344$ 像素。模型会将帧请求向上对齐到特定的时间维度形状 ($5 + 17n$)。例如，22 帧在 24 fps 下约产生 0.917 秒的视频，而 243 帧则产生 10.125 秒。

技术实现与 Metal 优化

h3-metal 引擎采用了多项深层优化，以减少 Apple Silicon 上的内存占用并提高吞吐量。

内存与权重管理

在 M5 级 GPU 上，transformer weights 直接从 safetensor shards 映射，以保持 37 GiB 的模型文件支持文件映射并可回收。Qwen 文本编码器采用流式处理方法，通过由 I/O 工作线程填充的未来层 buffer 环来使编码过程与 Metal 执行重叠。

Metal 4 与 TensorOps

M5 GPU 利用原生的 BF16 Metal 4/TensorOps 进行 DiT QKV 和 attention-output 投影。该实现使用紧凑的 Morton 调度来将 Q/K/V 直接路由到 head-major attention 输入，从而避免了三次 MPSGraph 输入转置。

Int8 量化

默认的 M5 路径使用带有动态激活量化和每输出通道权重缩放的原生 int8 MLP 引擎。这显著地将峰值张量存储从 36.4 GiB (BF16) 降低至 25.9 GiB。进一步的优化包括：

Quantized QKV: 将 M5 上的去噪时间从 25.80 秒降低至 19.32 秒。
Fused Kernels: 将 QKV 和 MLP 激活量化折叠进先前的 gated AdaLN kernel，从而在每 50 层的正向传播中减少了 99 次独立的量化器调度。

社区洞察与替代方案

用户之间的讨论突显了原生 Metal 实现与通用框架之间显著的性能差距。

"在我的 128GB M4 Max Mac Studio 上，使用 ComfyUI 中的 MiniMax H3 生成 15 秒 480p 视频需要一个半小时。"

用户指出，虽然高内存配置（如 128GB）是实现峰值性能的理想选择，但能够在 Mac 硬件上本地运行这些模型对于“本地优先”的工作流来说是一项重大进步，即使专门的 CUDA 硬件仍然更快。