奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

下载 MiniMax H3 权重时别下重了：`--include` 到底在挡什么

2026-08-09

第一次照着 MiniMax H3 的 README 拉权重，很容易犯一个不报错、但代价不小的错：跳过那一长串 --include，直接把整个仓库 clone 或者 download 下来，想着「反正都要用，一次拉全省事」。

这个判断在别的模型仓库上通常成立，在 H3 这里不成立。原因是仓库的组织方式跟大多数模型仓库不一样——它把原始 checkpoint 与 diffusers 格式并排托管在同一个仓库里。你不加限定条件，就是同时把两套东西都拖下来，而你实际用得上的只有其中一套。

下面按截至 2026-08-09 的官方仓库（MiniMax-AI/MiniMax-H3）README 与文件树，把这件事拆开讲。我们没有下载过权重、没有部署过、也没有发起过任何推理请求，以下全部是仓库口径。

仓库里并排放着的两套东西

先看第一套。README 给的单个 checkpoint 结构是这样的：

<TASK>/
├── model_index.json
├── processor/
├── tokenizer/
├── text_encoder/
├── transformer/
├── visual_vae/
└── audio_vae/

<TASK> 在仓库里落实为两个目录：FL2VA/ 与 Ref2VA/。这两个目录的结构完全对称，各自都是一个自包含的 Hugging Face 风格仓库，各含 transformer/config.json 与 model.safetensors.index.json、text_encoder/、tokenizer/、processor/、model_index.json，以及音视频两个 VAE 的目录——audio_vae/（里面有 dac_*.py 一组文件和 minimax_h3_audio_vae.py）、video_vae/（里面有 klvae.py、vae_vit.py、vae_cnn.py、parallel.py、attention.py、flash.py 等）。

这里先记一笔，验收的时候会用到：README 结构图里写的是 visual_vae/，而文件树里实际可见的目录名是 video_vae/。这是两处原文的差异，我们只如实记录这个观察，不去推断原因，也不建议你按哪一边去改本地目录名。

第二套是 diffusers 格式，它不在 FL2VA/ 或 Ref2VA/ 里面，而是直接摊在仓库根目录：transformer/、transformer_ref/、vae/、text_encoder/、tokenizer/、processor/、scheduler/scheduler_config.json、audio_scheduler/scheduler_config.json、audio_vae/config.json、model_index.json、modular_model_index.json。

所以根目录下的 text_encoder/、tokenizer/、processor/ 和 FL2VA/text_encoder/、FL2VA/tokenizer/、FL2VA/processor/ 是并存的两份，不是一份。理解这一点，--include 那串东西就不再是仪式感了。

顺带说清 model_index.json 的层级关系，这个也容易看岔：仓库根目录那个 model_index.json 是仓库级的公共入口，而按任务族的 diffusers 索引分别在 FL2VA/model_index.json 与 Ref2VA/model_index.json。README 的两条下载命令都单独把 model_index.json 列进 --include，就是为了保证这个入口文件一定会被带上。

两条官方命令，原样抄

README 里给的是这两条，照抄，别自己改写：

# Original checkpoint, both task families (SGLang, vLLM):
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" "Ref2VA/*" --local-dir MiniMax-H3

# Or a single task family:
hf download MiniMaxAI/MiniMax-H3 --include "model_index.json" "FL2VA/*" --local-dir MiniMax-H3

逐段解释每个选项为什么在这：

  • hf 这个命令行工具由 huggingface_hub 提供，仓库 requirements.txt 对它的约束是 >=0.25.0。如果你敲 hf 提示找不到命令，先去看这个依赖装没装、版本够不够，而不是去怀疑网络。
  • --include 后面跟的是一组模式，作用是只下匹配到的路径。第一条给了三个模式，第二条给了两个。没被模式覆盖到的路径就不会进入下载队列——根目录那套 diffusers 格式的文件，正是被这里挡在外面的。
  • "model_index.json" 单独列出，对应上一节说的仓库级公共入口。
  • "FL2VA/*" 与 "Ref2VA/*" 是两个任务族。第二条命令演示的就是只要一个任务族的写法：只做首尾帧到视频这一族的人，只下 FL2VA/*，Ref2VA/* 那一整族根本不必拉。反过来只做多模态参考生视频的，同理。
  • --local-dir MiniMax-H3 指定落盘的本地目录。执行前先想清楚你在哪个盘、哪个目录下敲这条命令。

两条命令的注释里官方点名了适用对象：Original checkpoint, both task families (SGLang, vLLM)。也就是说，这两条是给要跑 SGLang 或 vLLM 的人用的。

重复下载的直接证据

「不加 --include 会重复下载」不是推测，文件树里有直接证据：tokenizer 相关的文件在两套格式里各出现一次，tokenizer.json 约 7.0 MB、vocab.json 约 2.8 MB、merges.txt 约 1.7 MB。你全量拉，这三个文件就是实打实地各拿两遍。

需要说明的是，我们没有整仓体积的事实，所以这篇不会给你「能省多少」之类的数字。上面这三个 MB 级数字是文件树里可见的，能说明「确实重复」这件事本身，不能拿去外推整体规模。真正的权重分片有多大，你自己执行下载时看进度条，比看任何二手数字都准。

diffusers 用户：一行都不用下

这是本篇最省事的一条结论。README 明写着：ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-H3") 会精确拉取它所需的组件，diffusers 用户不需要手动下载。

所以如果你的技术路线是 diffusers，上面两条 hf download 你一条都不用敲。手动下反而容易把目录结构摆错，再去跟按需拉取的缓存打架。

但 diffusers 这条路上有另一个坑，而且这个坑跟下载无关，是环境层面的。仓库 requirements.txt 对 diffusers 的约束是 >=0.32.2，官方注释里明确说：官方文档引用的是 diffusers 的 minimax-h3 分支，在它进 PyPI 之前，注释给的安装方式是

pip install "git+https://github.com/huggingface/diffusers.git@minimax-h3"

换句话说，直接 pip install diffusers 装 PyPI 上的版本，可能根本没有 H3 的模型类。这时候「按需拉取」当然也无从谈起。判断路径很清楚：先确认你的 diffusers 是从哪儿装的，再谈 pipeline 跑不跑得起来。requirements.txt 里还提到模型是作为 Hugging Face diffusers pipeline 发布、通过 trust_remote_code=True 使用的，官方建议 pin 一个已知可用的 diffusers 版本与一个带所需 CUDA / MPS wheel 的 torch 版本。

下完之后长什么样、怎么验收

只描述我们有依据的部分。命令跑完，--local-dir 指向的那个目录里，你应该能看到 model_index.json，以及你 --include 进来的一到两个任务族目录。逐项检查这几处：

  1. 根目录那套 diffusers 文件在不在。 如果你在本地看到了 modular_model_index.json、transformer_ref/、scheduler/scheduler_config.json、audio_scheduler/scheduler_config.json 这些，说明 --include 没生效，你把两套都拉下来了。这是本篇要挡的那个错误的最直接判据。
  2. 任务族目录是不是自包含的。 进 FL2VA/，model_index.json、transformer/config.json、model.safetensors.index.json、text_encoder/、tokenizer/、processor/ 这几项都应该在。这几项里少了任何一项，都说明你手上的这个任务族目录还不完整，先把下载补齐再往下走，别急着起服务。
  3. 打开 FL2VA/model_index.json 核几个字段。 里面 _class_name 是 MiniMaxH3Pipeline，_diffusers_version 是 0.32.2，text_encoder 指向 transformers 的 MiniMaxH3Qwen3VLHFEncoder，tokenizer 指向 Qwen2TokenizerFast。四项对得上，说明你拿到的确实是这个仓库的索引文件，没混进别处的同名文件。
  4. VAE 目录名对照着看。 前面提过 README 结构图写 visual_vae/、文件树里是 video_vae/。你本地看到 video_vae/ 时不用慌，也不要为了对齐 README 去手动重命名。

最容易出错的一步，是 --include 后面那几个模式的引号。这几个模式带 *，在 shell 里不加引号会被 shell 先展开一遍，展开结果跟你的当前目录有关，传给 hf 的就不是你写的那串了。官方命令里每个模式都是带双引号的，抄的时候连引号一起抄。

另外提一句 README 里一处看起来别扭、但确实原文如此的地方：下载命令把权重落到本地 MiniMax-H3 目录，而部署示例里 sglang serve 的 --model-path 写的是仓库 id MiniMaxAI/MiniMax-H3。两处原样如此，我们没有部署过，不替它圆场，也不建议你按自己的理解改——以官方部署文档为准。

什么情况不适用

  • 你跑 diffusers。 前面那节说过了，别手动下。
  • 你只想在 ComfyUI 里用 H3。 ComfyUI 侧走的是另一套量化权重（Comfy-Org/MiniMax-H3 的 pruned_int8_convrot / nvfp4_awq），MiniMax 官方仓库发布的是 BF16，这篇讲的下载命令跟 ComfyUI 那条路没关系。这两边的模型文件不要混着评估，我们也没有任何评测数据可以拿来比。
  • 你还没想好跑哪个框架。 README 推荐的框架有四个（SGLang、vLLM、diffusers、ComfyUI），下载范围是跟着框架走的。先定框架，再敲下载命令，顺序反了就只能重来。
  • 只做一件事却下了两族。 只做首尾帧/文生视频这一族的，第二条命令就够；两族都要的场景才用第一条。
  • 完全离线的机器。 「按需拉取」依赖能连上 Hub，纯内网环境下 diffusers 那条省事路径不成立，得另想搬运权重的办法——README 里我们没有看到对应的离线方案，别指望照抄。

最后重复一遍这篇的核心判断依据：这个仓库里并排放着两套格式，--include 不是可选的优化项，而是决定你拿到的是哪一套的开关。

延伸阅读

本文依据 MiniMax H3 官方仓库（github.com/MiniMax-AI/MiniMax-H3）的 README、 模型配置文件与官方 h3-prompt-writing skill 文档整理，核对日 2026-08-09。 本文内容为官方仓库口径，未在本机部署或调用过 H3。 模型、部署方式与许可条款以官方最新说明为准。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员