MiniMax模型下载与安装详细教程

从官方地址核对到完整下载和首次运行

核对日期 2026年10月29日

MiniMax M3.1 Flash属于服务器部署示例。Flash不代表普通电脑能运行，先核对约252 GB的整仓下载量及官方硬件方案。M2.5等历史仓库也列入目录。

阅读顺序：先完成第1节选型与空间检查，再安装下载工具，下载并校验。只有确认满足运行条件后，才进入运行章节。

1 先选对模型

MiniMax M系列、Text、VL、Music等仓库任务不同。M3.1 Flash采用专门量化与稀疏注意力，不能仅用通用AutoModel代码推断已可运行。

容量按官方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。

Python Windows官方下载页

2. 每次复制一行命令，按回车，等待完成后再执行下一行。使用独立环境可减少与电脑上其他Python软件冲突。

py --version
py -3.12 -m venv "$env:USERPROFILE\hf-minimax-env"
& "$env:USERPROFILE\hf-minimax-env\Scripts\Activate.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。

Python macOS官方下载页

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:\Models\MiniMax-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库，并不足以运行这些原始权重。下面给出部署操作顺序与官方生成命令入口。

官方模型卡说明Transformers等集成仍在进行中，因此本教程采用官方推荐的专门推理引擎路线，不提供未经该模型卡确认的通用加载脚本。

服务器从安装到启动的操作顺序

1. 在Linux服务器确认GPU型号、数量与可用显存。NVIDIA运行nvidia-smi，AMD按ROCm文档检查设备。2. 按官方容器文档安装Docker及GPU容器运行支持。3. 完成第3节下载与第4节校验。4. 打开下方官方recipe，在Presets中选与你硬件相符的方案。5. 使用该页面生成的容器及启动命令；把模型路径映射到已下载目录，并保留方案的量化和并行参数。

官方引擎部署方案与命令生成器

Docker官方安装文档

NVIDIA容器工具官方安装文档

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 其他版本与图形界面路线

本次重点核对的仓库

打开 MiniMaxAI/MiniMax-M3.1-Flash

打开 MiniMaxAI/MiniMax-M2.5

每个重点仓库的所有文件路径、原始字节大小和API提供的LFS SHA256，均在精讲仓库文件大小与校验.csv和精讲仓库全部文件地址.txt中。不同仓库固定提交不同，不混用配置、分片与分词器。

如何查找社区量化版

Hugging Face量化版本检索

该链接是检索入口，不代表列表中的结果全部由原厂发布。核对发布者、原始base_model、转换工具、量化档位、更新时间与运行时支持。对比模型卡确认同一基础模型后，再选择适合设备的版本。社区量化版不是本教程原始权重的替代文件。

如使用LM Studio，先安装官方应用，在Discover粘贴确认过的GGUF仓库URL，下载一个适合设备的量化版本，再从聊天页加载。新架构尚未受支持时，应等待运行时适配或按原厂引擎部署文档操作。

LM Studio官方支持与要求

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可用Excel、Numbers或文本编辑器打开，用筛选查仓库ID和任务。TXT可用记事本打开，搜索精确模型名。全部文件直链依据官方API siblings字段枚举；非精讲仓库未逐一获取文件大小，不能据此估算全部仓库总容量。

下载命令.txt中的每一组是不同模型，只执行你选择的一组。没有要求一次下载整个系列。固定版本用于重现本清单，main会持续变化；以后想下载新版，先重新查看文件和容量。

附录 主示例全部文件直链

MiniMaxAI/MiniMax-M3.1-Flash 固定提交 262ae6830934f3512211081b8a3f16425b93a239。共72项。字节大小来自仓库API；单击下载入口获取文件，Word中也可按Ctrl并点击。完整URL已保存在同目录TXT与CSV。

来源与核对说明

仓库列表来自官方Models API，已按分页链接读取到底；文件列表来自其siblings字段。重点仓库另查询blobs=true取得字节和LFS校验元数据。元数据核对不等于实际下载权重或完成运行测试。本教程的运行脚本依据模型卡加载方式编写，未在本机实测这些模型。

官方发布账号 | 本系列仓库API | 主示例精确文件元数据 | 主示例固定模型卡 | Hub CLI官方说明 | Hub网络与环境变量 |