使用 TensorFold 在 Apple Silicon 上生成 MiniMax H3 文生视频和图生视频片段

此项目的功能

此仓库为 Apple Silicon 上的 TensorFold 打包 MiniMax H3 视频模型。它将 TensorFold 的 H3 系列与 MLX int8 Metal 内核及 LightX2V Turbo 适配器结合，用于生成带同步立体声音频的视频。

该软件包支持文生视频，并从 1.1 版本起支持使用指定首帧的图生视频。在实测的配备 256 GB 内存的 Mac Studio M5 Ultra 上，使用 Turbo 适配器生成 5 秒、864x480 的视频片段约需 50 秒。在文档所述的基准条件下，生成 768x448 的视频片段约需 40 秒。

此仓库是开发渲染路径，而非服务器或产品。没有 tensorfold generate 命令；每次渲染都会通过随附脚本加载模型。

主要功能

• 文生视频：描述场景并生成包含视频和立体声音频的 MP4。
• 图生视频：提供首帧并描述接下来发生的事情。
• Turbo 生成：在文档所述的快速路径中，LightX2V 适配器将渲染减少为三次前向计算。
• MLX 和 int8 内核：在兼容的 M5 张量硬件上，选定的 Transformer 和解码器操作使用 int8 Metal 内核。
• 可复现的设置：安装程序固定 TensorFold、MLX、支持库、模型版本和适配器校验和。
• 可选的基础模型渲染：禁用适配器并使用约 20 个采样步，以获得更接近基础模型的渲染结果。

硬件和软件要求

公布的性能数据是在配备 256 GB 统一内存、运行 macOS 27.0.1 的 Mac Studio M5 Ultra 上测得的。项目说明至少需要 128 GB 内存，而适配器合并可能达到约 103 GB 的峰值内存。不使用适配器时，峰值内存约为 65 GB。

int8 内核需要 Metal 4 张量运算，因此所报告的加速效果适用于兼容的 M5 硬件。在不支持这些运算的系统上，H3 系列会以 bfloat16 运行，速度可能慢于 README 中介绍的 C 语言替代方案。

你还需要 Homebrew、Python 3.11、uv 和 FFmpeg。MiniMax H3 模型下载约为 144 GB，Turbo 适配器约为 1.96 GB。

安装项目

克隆仓库并安装所需的主机工具：

git clone https://github.com/drowzeys/keys-Mac-TensorFold-MiniMax-H3-MLX.git
cd keys-Mac-TensorFold-MiniMax-H3-MLX
brew install python@3.11 uv ffmpeg

运行一次性设置脚本：

bash oneshot-setup.sh

安装程序会在 ~/.local/opt/tensorfold-h3 创建隔离环境，并安装包含 H3 系列和固定依赖锁的 TensorFold 0.6.5。当 Docker 可用时，它可以从项目的 GHCR 预构建载体中获取经过校验和验证的 TensorFold 载荷；否则会从 Git 获取匹配的源代码提交。

设置过程还会克隆所需的 minimax-h3-mlx 版本，将 MiniMax H3 FL2VA 分区下载到 ~/h3-models/MiniMax-H3，下载 Turbo 适配器，并将测试片段渲染到 outputs/test.mp4。

如需检查现有安装而不重新安装，请运行：

bash oneshot-setup.sh --verify

如需跳过初始测试渲染，请使用：

bash oneshot-setup.sh --no-render

你可以通过 PREFIX 和 H3_MODEL_DIR 环境变量更改默认的安装位置和模型位置。

生成文生视频片段

使用带有提示词和输出文件名的 scripts/generate.sh：

bash scripts/generate.sh "A hummingbird hovering over red flowers, soft wing hum" out.mp4

默认路径使用已配置的 Turbo 适配器和仓库的默认生成设置。提示词既描述视觉场景，也可以在需要时描述目标音频。

如需生成确定性变体，请提供种子并选择受支持的画布：

WIDTH=768 HEIGHT=448 SEED=7 bash scripts/generate.sh "A quiet train crossing a snowy valley at dawn" out.mp4

你可以将提示词保存在文本文件中。在这种情况下，传入空提示词参数并设置 PROMPT_FILE：

PROMPT_FILE=prompts/black-mirror-scene.txt SEED=2077 bash scripts/generate.sh "" out.mp4

生成图生视频片段

将 FIRST_FRAME 设置为图像文件。该图像将作为首帧，而提示词用于说明随后发生的运动或事件：

FIRST_FRAME=photo.jpg WIDTH=1344 HEIGHT=768 bash scripts/generate.sh "She turns to the camera and smiles" out.mp4

图像会被拉伸至所选画布大小，因此请选择宽高比匹配的尺寸，或在渲染前裁剪图像。README 推荐 16:9 使用 1344x768，9:16 使用 768x1344，方形内容使用 768x768。

MiniMax 风格的图生视频提示词可以明确指出首帧，例如：

For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced. The subject walks through the doorway and looks toward the window.

Turbo 适配器和 20 步基础路径均支持首帧生成。末帧和参考图像模式尚未接入此软件包。

控制帧数、分辨率和采样

帧数必须符合 17n + 5 的形式。README 列出的支持示例包括 56、73、90、124、192、243 和 362 帧。宽度和高度必须是 32 的倍数，已发布模型的限制是画布总尺寸最大为 768x1344 像素。

快速 Turbo 路径使用三次前向传播。要禁用适配器并使用 20 步渲染，请设置 ADAPTER=none 和 POINTS=21：

ADAPTER=none POINTS=21 bash scripts/generate.sh "A lantern glowing beside a forest path" base-model.mp4

README 将此设置描述为更接近基础模型；Turbo 可以快速生成清晰帧，但有时可能会重复人物。即使使用相同种子，两种模式也可能生成不同的构图。

了解速度取舍

最大的速度提升来自 Turbo 适配器的三次前向传播，而不是 20 次。对于受支持的 M5 张量硬件，int8 SwiGLU MLP、int8 QKV 运算、注意力输出和视频解码器内核还能带来额外提升。

在记录的 864x480 基准测试中，Turbo 路径的去噪耗时约 27.6 秒，总耗时约 50 秒，其中包括文本编码、加载与量化以及解码。同一对比中，20 步 TensorFold int8 渲染的总耗时约为 210 秒。

这些数据与硬件有关，不应视为普遍适用的结果。仓库还指出，注意力计算本身仍使用 MLX 缩放点积注意力，因为实测的 int8 闪存式替代方案并未带来有意义的速度优势。

高级设置和工作流技巧

使用预构建载体

安装程序可以使用 GHCR 载体，但该载体不是 Mac 运行时。Metal 不会在容器内运行；载体仅提供 TensorFold wheel、依赖锁定文件、生成脚本和校验和，用于原生安装。

docker pull ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1
docker run --rm -v "$PWD":/out ghcr.io/drowzeys/keys-mac-tensorfold-minimax-h3-mlx:1.1 cp -a /payload/. /out/payload/

要重新构建并推送载体，仓库提供了以下命令：

PUSH=1 bash scripts/build-carrier.sh

注意内存使用

模型加载和适配器合并都非常消耗内存。开始渲染前请关闭不必要的应用，尤其是在使用 Turbo 适配器时。仓库报告称，在其测量路径中，每次运行仅投影一次 AdaLN 表并释放权重，可节省约 24 GiB。

选择合适的图生视频画布

由于首张图像会被拉伸，而不会自动裁剪以保留原有构图，因此应根据目标宽高比准备源图像。这样可以避免生成竖屏、横屏或方形片段时出现不必要的变形。

谨慎使用替代适配器

加载器可以通过适配器路径读取 FastH3，并使用 POINTS=5，例如设置 ADAPTER=.../adapter_model.safetensors。README 报告称，该路径在 864x480 下进行了测试，测试提示词耗时 76 秒，生成结果比 Turbo 更繁杂。它发布时针对的是 1344x768，但项目中未对该分辨率进行测试。

正确解读质量对比

README 强调，质量并未得到全面评估。int8 路径可以保留 bfloat16 的构图，同时改变细节；三次前向传播的 Turbo 渲染结果也可能不同于 bfloat16 Turbo 渲染。因此，基准测试表比较的是实测速度和选定的静帧，并不保证运动或音频质量完全一致。

许可与项目状态

此软件包不包含模型权重。下载 MiniMax H3 前，请阅读 MiniMax H3 社区许可证，包括其中的地域限制。还应查看仓库的 致谢，并在适当情况下引用 MiniMax、TensorFold、MLX、H3、适配器及相关项目的原作者。

此处使用的 H3 系列被描述为上游拟议中的草案拉取请求，而不是已发布 TensorFold 版本的一部分。因此，为了复现该设置，固定文档中记录的修订版本非常重要。

结论

此仓库提供了一种专门的方法，可在兼容的 Apple Silicon Mac 上原生运行 MiniMax H3 视频生成。安装固定版本的环境并下载模型后，你可以渲染文生视频片段、制作首帧动画、在快速 Turbo 适配器和 20 步基础路径之间切换，并调整画布、帧数、种子和提示词设置。请预留充足的内存和存储空间，并将已公布的耗时视为指定 M5 系统上的测量结果，而非普遍适用的保证。