MiniMax模型下载与安装详细教程
作者：互联网 时间： 2026-10-30 12:40:01
MiniMax M3.1 Flash属于服务器部署示例。Flash不代表普通电脑能运行，先核对约252 GB的整仓下载量及官方硬件方案。M2.5等历史仓库也列入目录。
阅读顺序：先完成第1节选型与空间检查，再安装下载工具，下载并校验。只有确认满足运行条件后，才进入运行章节。
1 先选对模型
MiniMax M系列、Text、VL、Music等仓库任务不同。M3.1 Flash采用专门量化与稀疏注意力，不能仅用通用AutoModel代码推断已可运行。
项目 | 本教程主示例 |
|---|---|
官方仓库ID | MiniMaxAI/MiniMax-M3.1-Flash |
固定提交 | 262ae6830934f3512211081b8a3f16425b93a239 |
整仓文件数 | 72项 |
整仓容量 | 252.446 GB 约235.11 GiB |
访问状态 | 公开 无访问审批标记 |
运行准备 | 官方方案分别涉及Blackwell四卡、Hopper八卡或MI355X四卡，不能按普通消费级显卡照搬。 |
容量按官方API的文件字节数相加，包含文档、配置及仓库内可能并存的其他权重格式；不是运行内存最低要求。GB按十进制，GiB按二进制换算。
下载目录建议至少预留334 GB可用空间。这是整仓大小加约30%和5 GB余量的建议，不含额外转换副本、框架环境、系统空间及其他缓存。
检查自己的电脑
Windows：按Win加I打开设置，进入系统中的系统信息查看内存；在任务管理器的性能页查看GPU及专用显存。macOS：打开苹果菜单中的关于本机，查看芯片与内存。内存和硬盘空间是两回事。
下载只依赖网络与磁盘；运行还需要内存、显存、对应架构和框架。FP16或BF16权重可用总参数量乘2字节估算基础权重占用，float32约乘4字节，实际还要加运行开销和上下文缓存。MoE不能仅按激活参数估算。
磁盘必须支持大文件。Windows通常用NTFS，Mac通常用APFS，跨系统外置盘可用exFAT。不要为了下载随意格式化已有资料的硬盘。FAT32无法保存超过4 GB的单个文件。
2 安装下载工具与准备账号
Windows 按顺序操作
1. 打开Python官方下载页，安装Python 3.12。若安装器显示Add python.exe to PATH，请勾选；安装结束后重新打开PowerShell。可在开始菜单搜索PowerShell。
2. 每次复制一行命令，按回车，等待完成后再执行下一行。使用独立环境可减少与电脑上其他Python软件冲突。
py --version py -3.12 -m venv "$env:USERPROFILEhf-minimax-env" & "$env:USERPROFILEhf-minimax-envScriptsActivate.ps1" python -m pip install --upgrade pip huggingface_hub hf --help
应看到Python版本、安装成功信息和hf帮助列表。若py -3.12找不到版本，确认安装了Python 3.12；若系统只有python可用，可将创建环境命令中的py -3.12替换为python。
如果PowerShell阻止激活脚本，可在本窗口执行下面一行后再激活；只影响当前窗口。关闭窗口后恢复原状态。
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
macOS 与 Linux 按顺序操作
macOS按Command加空格搜索终端；Linux打开终端。先安装Python 3.12并确认python3存在。Linux若缺少venv模块，按发行版官方说明安装python3-venv。
python3 --version python3 -m venv "$HOME/hf-minimax-env" source "$HOME/hf-minimax-env/bin/activate" python -m pip install --upgrade pip huggingface_hub hf --help
以后新开窗口时，Windows重新执行Activate.ps1那一行；macOS和Linux重新执行source那一行。不必每次重建环境。
需要审批时如何处理
1. 在Hugging Face注册并验证邮箱。2. 登录后打开目标模型主页。3. 如果页面要求接受许可证、填写用途或申请访问，按页面要求完成。4. 等页面确认获准，再创建具备该仓库读取权限的令牌。5. 回到终端执行下面命令，按提示粘贴令牌。粘贴时没有字符显示可能是正常的。
hf auth login hf auth whoami
公开仓库通常可先直接下载。令牌只填在工具提示中，不写进文档、截图或聊天消息。申请等待时间由发布方决定，登录成功不等于已获得仓库权限。
3 固定版本完整下载
本节下载主示例的全部文件。仓库ID由发布者名称、斜杠和模型名组成；revision是这次核对的固定提交。请不要自行把名称换成相似的社区仓库。
Windows 保存到D盘示例
先在此电脑中确认D盘存在且空间足够。没有D盘时，把下面的D:Models改为你实际的大容量磁盘路径。保留英文双引号，防止路径含空格时出错。
$repo = "MiniMaxAI/MiniMax-M3.1-Flash" $rev = "262ae6830934f3512211081b8a3f16425b93a239" $dest = "D:ModelsMiniMax-M3.1-Flash" New-Item -ItemType Directory -Force $dest hf download $repo --revision $rev --local-dir $dest --dry-run
上面的dry-run只查看待下载文件和预计下载量，不下载模型权重。若CLI不认识dry-run，先升级huggingface_hub。确认预计大小、目标磁盘和权限无误，再执行正式下载：
hf download $repo --revision $rev --local-dir $dest
macOS 与 Linux 保存到主目录示例
先确认主目录所在磁盘足够大。外置盘用户需替换dest为真实挂载路径；Mac常见路径以/Volumes/开头，Linux以实际挂载位置为准。
repo="MiniMaxAI/MiniMax-M3.1-Flash" rev="262ae6830934f3512211081b8a3f16425b93a239" dest="$HOME/Models/MiniMax-M3.1-Flash" mkdir -p "$dest" hf download "$repo" --revision "$rev" --local-dir "$dest" --dry-run hf download "$repo" --revision "$rev" --local-dir "$dest"
变量只在当前窗口有效。换窗口后先激活环境，再重新执行repo、rev和dest三行赋值。Word自动换行不代表命令结束，请按完整段落复制。
下载过程怎样判断
正常会出现文件进度与传输信息，完成后回到命令提示符。第一次连接和大分片可能等待较久。电脑保持供电，关闭自动睡眠，外置盘不要中途拔出。按Ctrl加C可停止，恢复时按第4节重试。
按固定有效速度粗算：10 MB每秒约7.01小时，50 MB每秒约1.40小时；实际还受网络、磁盘和服务器影响。网络套餐的Mbps与下载界面的MB每秒单位不同，需除以8再估算。
4 校验完整性与恢复下载
整仓下载应保留原始目录结构。所有safetensors分片、索引、配置和分词器文件都属于配套内容；不要把多个分片手工合成一个文件，也不要只留最大的一个分片。
本示例整仓共72项，其中名称以.safetensors结尾的文件49个。是否包含重复格式、视觉模块或额外目录，以附录实际文件名为准。
Windows 校验
hf cache verify $repo --revision $rev --local-dir $dest --fail-on-missing-files
macOS 与 Linux 校验
hf cache verify "$repo" --revision "$rev" --local-dir "$dest" --fail-on-missing-files
以校验摘要显示All checksums match且没有缺失文件为整仓完成标准。校验需要联网获取元数据，还会读取本地大文件；运行时间可能较长。只数文件个数不能代替校验。
中断以后怎么继续
重新打开终端并激活环境，恢复相同repo、rev和dest，重新执行第3节正式下载命令。工具会利用已经完成的文件和可用缓存继续。未完成片段能否直接续传取决于传输后端与缓存状态。保留目标目录内的.cache/huggingface及临时文件。
若校验明确指出一个文件损坏，可只重下那个文件。下面仅是按本仓库真实文件名写出的示例；先把文件名换成报错对应的项，再执行，避免重下正常大文件。
hf download MiniMaxAI/MiniMax-M3.1-Flash "dspark/model-dspark-00001.safetensors" --revision 262ae6830934f3512211081b8a3f16425b93a239 --local-dir "实际模型目录" --force-download
替换实际模型目录为第3节的dest路径。重下后再做整仓校验。不要为一个文件报错就删除整个下载目录。
用网页逐个下载
打开固定文件列表，在Files and versions中找到文件并点下载图标；也可用附录直链。浏览器若显示文本而不保存，使用另存为并保留原文件名。按子目录原样创建文件夹，例如original/下的文件不能放到根目录覆盖同名配置。大量分片优先用CLI。
直链形如/resolve/固定提交/文件路径。浏览器最终跳转到的存储地址可能带临时签名，会过期；分享资料时保留本教程提供的入口。受访问审批保护的文件，打开直链仍需权限。
5 下载后开始运行
本系列主示例需要服务器。先做硬件核对，再安装推理环境；在普通Windows或Mac笔记本上安装一个Python库，并不足以运行这些原始权重。下面给出部署操作顺序与官方生成命令入口。
检查项 | 本次官方方案要求 |
|---|---|
Blackwell路线 | GB200 GB300 B200或B300，TP4 |
Hopper路线 | H100或H200整机，TP8，使用对应FP8方案 |
AMD路线 | MI355X，ROCm 7.2及以上，TP4 |
关键参数 | block-size必须为128，其他量化与注意力参数按硬件方案选择 |
官方模型卡说明Transformers等集成仍在进行中，因此本教程采用官方推荐的专门推理引擎路线，不提供未经该模型卡确认的通用加载脚本。
服务器从安装到启动的操作顺序
1. 在Linux服务器确认GPU型号、数量与可用显存。NVIDIA运行nvidia-smi，AMD按ROCm文档检查设备。2. 按官方容器文档安装Docker及GPU容器运行支持。3. 完成第3节下载与第4节校验。4. 打开下方官方recipe，在Presets中选与你硬件相符的方案。5. 使用该页面生成的容器及启动命令；把模型路径映射到已下载目录，并保留方案的量化和并行参数。
6. 服务仅供本机验证时，把服务端口映射到127.0.0.1；不要直接对公网开放。7. 终端出现服务就绪信息后，新开终端做下面的检查。若服务使用其他端口，调整8000。
curl http://127.0.0.1:8000/v1/models
返回data数组且有模型ID，说明服务可访问，但还需要完成问答测试。把本教程附带的test_service.py放到客户端环境，安装requests后执行：
python -m pip install --upgrade requests python test_service.py --base-url http://127.0.0.1:8000
脚本自动读取服务返回的模型ID并发出一个短问题。看到answer下的有效回复才算首次问答完成；reasoning可能包含推理内容。长推理若耗尽输出额度，可增大脚本max_tokens后再试。服务停止时，在服务窗口按Ctrl加C。
这份资料已核对官方要求及入口，没有在你的电脑或服务器下载完整权重、安装推理环境或实测多卡服务。具体preset启动命令由官方页面按实际硬件生成；在硬件未知时不把某一条命令写成通用安装命令。
6 其他版本与图形界面路线
本次重点核对的仓库
仓库ID | 整仓容量 | 访问状态 |
|---|---|---|
MiniMaxAI/MiniMax-M3.1-Flash | 252.446 GB 约235.11 GiB | 公开 无访问审批标记 |
MiniMaxAI/MiniMax-M2.5 | 230.163 GB 约214.36 GiB | 公开 无访问审批标记 |
打开 MiniMaxAI/MiniMax-M3.1-Flash
每个重点仓库的所有文件路径、原始字节大小和API提供的LFS SHA256，均在精讲仓库文件大小与校验.csv和精讲仓库全部文件地址.txt中。不同仓库固定提交不同，不混用配置、分片与分词器。
如何查找社区量化版
该链接是检索入口，不代表列表中的结果全部由原厂发布。核对发布者、原始base_model、转换工具、量化档位、更新时间与运行时支持。对比模型卡确认同一基础模型后，再选择适合设备的版本。社区量化版不是本教程原始权重的替代文件。
如使用LM Studio，先安装官方应用，在Discover粘贴确认过的GGUF仓库URL，下载一个适合设备的量化版本，再从聊天页加载。新架构尚未受支持时，应等待运行时适配或按原厂引擎部署文档操作。
7 常见问题逐项排查
hf 找不到
确认当前窗口已激活hf-minimax-env，再运行python -m pip show huggingface_hub。若安装到了另一套Python，重新激活正确环境后安装。
401 或 403
检查是否登录正确账号、令牌是否有该仓库读取权限、网页是否已接受许可证并获准访问。公开元数据可见不代表受限权重可下载。
404 或 Revision not found
先核对完整仓库ID和固定提交，确认没有空格或多余标点。仓库可能重命名或被删除，回官方主页查询，不要凭相似名字猜地址。
下载超时或速度低
先用浏览器打开官方主页，再检查大文件下载是否也可连接。网络不稳定时保持同一路径和版本重试。出现Xet相关报错时查看官方环境变量说明，不关闭证书校验。
磁盘满了
按Ctrl加C停止，换到更大磁盘。复制完整模型目录及隐藏缓存后，更新dest路径并重新执行同版本命令。保留原目录直到新目录校验通过。
文件只有几KB
可能保存成网页、错误响应或Git LFS指针。与精讲仓库文件大小与校验.csv对比；使用hf download重新取得实际文件。
CUDA unavailable
当前PyTorch可能是CPU版，或驱动、显卡环境不可用。用PyTorch官方安装页的匹配命令；没有受支持的显卡时选择cpu。
CUDA out of memory 或系统内存不足
先退出其他程序，减小输入与输出长度。模型权重本身装不下时，换更小模型或经核对的量化版；仅缩短上下文不能消除权重占用。
KeyError 或模型架构不认识
检查依赖是否符合该仓库模型卡，区分旧自定义代码版与原生支持版。新模型可能需特定提交、专用镜像或尚未发布的运行时。
输出重复或没有最终回答
确认使用模型自己的聊天模板。推理模型可能先生成长推理；增加输出token上限，按模型卡调采样参数。小模型能力有限，先用短问题验证流程。
8 全部地址文件怎么使用
本系列按明确的官方发布账号与命名条件收录16个公开可枚举仓库。它是2026年10月29日的快照，不包含私有仓库、已删除仓库或全站社区微调、转换版本。清单收录不代表每项都适合聊天。
检索账号 MiniMaxAI；命名条件 仓库名不区分大小写包含 minimax。同名官方旧账号的历史地址可能发生跳转，以表中当前API返回的仓库ID为准。
文件 | 作用 |
|---|---|
官方仓库地址.csv | 全部仓库主页 文件页 固定提交 任务和访问状态 |
全部文件直链.csv | 全部已枚举仓库的逐文件固定版本与main下载入口 |
全部仓库下载命令.txt | 每个仓库可复制的预览与正式下载命令 |
精讲仓库文件大小与校验.csv | 重点仓库文件大小与API提供的LFS SHA256 |
精讲仓库全部文件地址.txt | 重点仓库每个文件的完整可复制URL |
CSV可用Excel、Numbers或文本编辑器打开，用筛选查仓库ID和任务。TXT可用记事本打开，搜索精确模型名。全部文件直链依据官方API siblings字段枚举；非精讲仓库未逐一获取文件大小，不能据此估算全部仓库总容量。
下载命令.txt中的每一组是不同模型，只执行你选择的一组。没有要求一次下载整个系列。固定版本用于重现本清单，main会持续变化；以后想下载新版，先重新查看文件和容量。
附录 主示例全部文件直链
MiniMaxAI/MiniMax-M3.1-Flash 固定提交 262ae6830934f3512211081b8a3f16425b93a239。共72项。字节大小来自仓库API；单击下载入口获取文件，Word中也可按Ctrl并点击。完整URL已保存在同目录TXT与CSV。
文件相对路径 | 字节大小 | 入口 |
|---|---|---|
.gitattributes | 1,585 | |
LICENSE | 3,363 | |
README.md | 23,757 | |
README_zh.md | 23,407 | |
added_tokens.json | 1,660 | |
chat_template.jinja | 11,633 | |
config.json | 9,122 | |
configuration_minimax_m3_vl.py | 4,356 | |
docs/FlagOS-Multi-Chip-Support-and-Downloads.md | 8,263 | |
dspark/config.json | 9,973 | |
dspark/model-dspark-00001.safetensors | 2,301,867,426 | |
dspark/model.safetensors.index.json | 11,432 | |
figures/logo.svg | 8,462 | |
generation_config.json | 150 | |
image_processor.py | 7,856 | |
merges.txt | 2,414,077 | |
model-00001-of-00048.safetensors | 10,213,649,632 | |
model-00002-of-00048.safetensors | 4,253,008,280 | |
model-00003-of-00048.safetensors | 4,253,008,280 | |
model-00004-of-00048.safetensors | 8,506,022,152 | |
model-00005-of-00048.safetensors | 8,506,022,152 | |
model-00006-of-00048.safetensors | 8,506,022,152 | |
model-00007-of-00048.safetensors | 8,506,022,152 | |
model-00008-of-00048.safetensors | 8,506,022,152 | |
model-00009-of-00048.safetensors | 8,506,023,712 | |
model-00010-of-00048.safetensors | 8,506,023,712 | |
model-00011-of-00048.safetensors | 8,506,023,712 | |
model-00012-of-00048.safetensors | 8,506,023,712 | |
model-00013-of-00048.safetensors | 4,721,760,520 | |
model-00014-of-00048.safetensors | 4,253,009,184 | |
model-00015-of-00048.safetensors | 4,253,009,184 | |
model-00016-of-00048.safetensors | 4,253,009,184 | |
model-00017-of-00048.safetensors | 4,253,009,184 | |
model-00018-of-00048.safetensors | 4,253,009,184 | |
model-00019-of-00048.safetensors | 4,253,009,184 | |
model-00020-of-00048.safetensors | 4,253,009,184 | |
model-00021-of-00048.safetensors | 4,253,009,184 | |
model-00022-of-00048.safetensors | 4,253,009,184 | |
model-00023-of-00048.safetensors | 4,253,009,184 | |
model-00024-of-00048.safetensors | 4,253,009,184 | |
model-00025-of-00048.safetensors | 4,253,009,184 | |
model-00026-of-00048.safetensors | 4,253,009,184 | |
model-00027-of-00048.safetensors | 4,253,009,184 | |
model-00028-of-00048.safetensors | 4,253,009,184 | |
model-00029-of-00048.safetensors | 4,253,009,184 | |
model-00030-of-00048.safetensors | 4,253,009,184 | |
model-00031-of-00048.safetensors | 4,253,009,184 | |
model-00032-of-00048.safetensors | 4,253,009,184 | |
model-00033-of-00048.safetensors | 4,253,009,184 | |
model-00034-of-00048.safetensors | 4,253,009,184 | |
model-00035-of-00048.safetensors | 4,253,009,184 | |
model-00036-of-00048.safetensors | 4,253,009,184 | |
model-00037-of-00048.safetensors | 4,253,009,184 | |
model-00038-of-00048.safetensors | 4,253,009,184 | |
model-00039-of-00048.safetensors | 4,253,009,184 | |
model-00040-of-00048.safetensors | 4,253,009,184 | |
model-00041-of-00048.safetensors | 4,253,009,184 | |
model-00042-of-00048.safetensors | 4,253,009,184 | |
model-00043-of-00048.safetensors | 4,253,009,184 | |
model-00044-of-00048.safetensors | 4,253,009,184 | |
model-00045-of-00048.safetensors | 4,253,009,184 | |
model-00046-of-00048.safetensors | 4,253,009,184 | |
model-00047-of-00048.safetensors | 4,253,009,184 | |
model-00048-of-00048.safetensors | 5,518,475,304 | |
model.safetensors.index.json | 10,864,357 | |
preprocessor_config.json | 772 | |
processing_minimax.py | 9,965 | |
special_tokens_map.json | 277 | |
tokenizer.json | 9,731,500 | |
tokenizer_config.json | 11,288 | |
video_processor.py | 7,318 | |
vocab.json | 4,705,413 |
来源与核对说明
仓库列表来自官方Models API，已按分页链接读取到底；文件列表来自其siblings字段。重点仓库另查询blobs=true取得字节和LFS校验元数据。元数据核对不等于实际下载权重或完成运行测试。本教程的运行脚本依据模型卡加载方式编写，未在本机实测这些模型。
官方发布账号 | 本系列仓库API | 主示例精确文件元数据 | 主示例固定模型卡 | Hub CLI官方说明 | Hub网络与环境变量 |