> For the complete documentation index, see [llms.txt](https://unsloth.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://unsloth.ai/docs/zh/mo-xing/minimax-m3.1-flash.md).

# MiniMax-M3.1-Flash：本地运行

使用 Unsloth Dynamic GGUFs 在本地运行 MiniMax-M3.1-Flash。

MiniMax-M3.1-Flash 是 MiniMax 推出的新款 **428B** MoE 多模态模型，拥有 23B 激活参数和 **1M 上下文**，专为编程和智能体应用打造。了解如何通过 [Unsloth GGUFs](https://huggingface.co/unsloth/MiniMax-M3.1-Flash-GGUF) 使用 Unsloth Desktop 或 llama.cpp 在本地运行。

我们的 129.4GB **1-bit** 达到了 **\~89.9% 的 top-1 准确率**；143.9GB **2-bit** 达到了 **91.5%**，而 249.4 GB 的 4-bit UD-Q4\_K\_XL 达到 98.0%。在编程任务上，Q2 达到 91.2%，Q4 达到 97.6%。我们对七个类别的量化性能进行加权评估： **七个类别**：编程、数学、聊天、工具、多语言、推理和智能体应用。感谢 MiniMax 在首日提供访问权限。

### ⚙️ 使用指南

MiniMax-M3.1-Flash 支持文本、图像和视频，并在所有层中加入稀疏注意力、用于注意力和路由专家的 QAT，以及 DSpark。

对于 2-bit UD-Q2\_K\_XL，建议预留 160GB 以上的 RAM + VRAM（或统一内存）；对于 4-bit UD-Q4\_K\_XL，建议预留 256GB 以上。这些规划估算基于 16K 文本上下文和一个并行槽位。

建议确保量化后的完整权重都能放入 RAM 和 VRAM，尽管每个 token 仅激活 23B 个参数。GPU 内存有限时，可使用 CPU 卸载。

#### MiniMax-M3.1-Flash 运行要求：

**表：硬件要求** （RAM + VRAM，或统一内存）。

| 1-bit  | 2-bit  | 3-bit      | 4-bit  | 8-bit（无损） |
| ------ | ------ | ---------- | ------ | --------- |
| 134 GB | 150 GB | 176–208 GB | 256 GB | 272 GB    |

规划估算基于 16K 文本上下文和一个槽位，并在权重之外预留约 20–32 GiB 供 KV 缓存、运行时和操作系统使用。内存目标以 GiB 为单位，通常以 GB 标示销售。更长的上下文、视觉功能和 DSpark 会需要更多内存。

对于 3-bit， `UD-IQ3_XXS`建议预留 176GB 以上； `UD-IQ3_S`建议预留 192GB 以上；或者对于 `UD-Q3_K_XL`建议预留 208GB 以上。8-bit 一栏指的是 `UD-Q8_K_XL`，这是此处列出的精度最高的 GGUF。

**权重大小：** 下方下载文件的大小以十进制 GB 为单位。建议从 16K 上下文开始，并在内存允许时逐步增加。

| 量化           | 下载大小（GB） | 权重大小（GiB） |
| ------------ | -------- | --------- |
| `UD-IQ1_M`   | 129.4 GB | 120.5 GiB |
| `UD-IQ2_XXS` | 134.9 GB | 125.7 GiB |
| `UD-Q2_K_XL` | 143.9 GB | 134.0 GiB |
| `UD-IQ3_XXS` | 160.0 GB | 149.1 GiB |
| `UD-IQ3_S`   | 175.5 GB | 163.4 GiB |
| `UD-Q3_K_XL` | 194.0 GB | 180.6 GiB |
| `UD-Q4_K_XL` | 249.4 GB | 232.3 GiB |
| `UD-Q8_K_XL` | 259.1 GB | 241.3 GiB |

### 推荐设置

使用 MiniMax 推荐的配置：

| 设置    | 值           |
| ----- | ----------- |
| 温度    | `1.0`       |
| Top-p | `0.95`      |
| Top-k | `0` （已禁用）   |
| Min-p | `0.0` （已禁用） |

#### 思考强度

该模板使用自适应思考。将 `reasoning_effort` 设置为 `low`, `medium`, `high`, `xhigh` 或 `max`。我们使用 `high`；思考强度与上下文和输出令牌限制相互独立。

```bash
--chat-template-kwargs '{"reasoning_effort":"high"}'
```

### 📊 量化分析

UD-Q8\_K\_XL 是从原始 safetensors 直接进行的无损转换。MiniMax 在 MoE 层使用 NVFP4，其余部分使用 MXFP8；我们将 UD-Q8\_K\_XL 保持为 NVFP4 + BF16。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FwPOGpnK3wxeulnC9lrJq%2Fminimax-kld.png?alt=media&amp;token=c7fb9b86-729f-45f1-827a-c8acee92d0a5" alt="MiniMax-M3.1-Flash GGUF KLD by file size across seven evaluation categories. Lower is better."><figcaption><p>按文件大小统计的平均 KLD。数值越低越好；纵轴采用对数刻度。</p></figcaption></figure>

我们在多个不同领域测试了制作的 MiniMax M3.1 Flash 量化版本，并与通用的 llama.cpp + imatrix 量化版本进行对比，以确保我们的量化算法不会针对某个特定领域过拟合。结果显示，Unsloth Dynamic v3 在所有领域都表现出色，令人惊喜。

我们还绘制了 Top-1% 图表，展示了即使在较低比特数下，UD3 仍能保持良好表现，优于使用 imatrix 的朴素 llama.cpp 布局。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FEGL7IdsBG2LJa8kp9krw%2Fsize_vs_top1_per_axis.png?alt=media&amp;token=1898d4b7-b4b4-46a7-b5e2-9a9a4915cdce" alt=""><figcaption></figcaption></figure>

**各量化方案的 Top-1 一致率：**

| 量化           | 文件大小     | 通用聊天 Top-1 | 数学 Top-1 |
| ------------ | -------- | ---------- | -------- |
| `UD-IQ1_M`   | 129.4 GB | 86.2%      | 94.9%    |
| `UD-IQ2_XXS` | 134.9 GB | 87.5%      | 95.3%    |
| `UD-Q2_K_XL` | 143.9 GB | 88.5%      | 95.7%    |
| `UD-IQ3_XXS` | 160.0 GB | 89.9%      | 96.3%    |
| `UD-IQ3_S`   | 175.5 GB | 91.2%      | 96.8%    |
| `UD-Q3_K_XL` | 194.0 GB | 92.6%      | 97.4%    |
| `UD-Q4_K_XL` | 249.4 GB | 97.3%      | 99.0%    |
| `UD-Q8_K_XL` | 259.1 GB | 97.8%      | 99.3%    |

在大小相当或更小的情况下，动态量化方案的 KLD 更低、一致率更高。 **UD-Q3\_K\_XL（194.0 GB）** 胜过通用方案 **IQ4\_XS（约 230 GB）** 在全部七个类别中的 Top-1 一致率表现。

**选择量化方案：** Q2 在 143.9 GB 的大小下，通用聊天和数学的一致率分别为 88.5% 和 95.7%。Q4 将这两项提升至 97.3% 和 99.0%，并将多语言一致率从 Q3 的 90.8% 提升至 97.6%。Q8 仅增加 9.7 GB，但保真度提升较小。

## 运行 MiniMax-M3.1-Flash 教程：

示例中我们使用 **UD-Q2\_K\_XL** 。在 Unsloth 中，图像输入和 DSpark 会自动启用。

### 🦥 Unsloth 指南

[Unsloth Desktop](https://unsloth.ai/docs/desktop) 是我们面向 macOS、Windows 和 Linux 的开源界面。可在同一个应用中下载 GGUF，并配置采样和 CPU/GPU 卸载。

{% stepper %}
{% step %}

### 安装 Unsloth

下载 [Unsloth Desktop](https://unsloth.ai/download) 适用于你的操作系统。请使用支持 MiniMax-M3.1 的构建版本，或使用下方的 llama.cpp PR。

<a href="https://unsloth.ai/download" class="button primary" data-icon="down-to-bracket">下载 Unsloth</a>
{% endstep %}

{% step %}

### 搜索并下载 MiniMax-M3.1-Flash

在 **Unsloth Chat** 或 **模型中心**中搜索 **MiniMax-M3.1-Flash** 并选择 [unsloth/MiniMax-M3.1-Flash-GGUF](https://huggingface.co/unsloth/MiniMax-M3.1-Flash-GGUF)。下载你需要的量化版本；我们使用 `UD-Q2_K_XL` （143.9 GB）。
{% endstep %}

{% step %}

### 运行 MiniMax-M3.1-Flash

使用推荐设置加载模型： **16K 上下文**, **一个并行槽位** 以及 `high` 推理强度。使用随附的聊天模板，并调整 CPU/GPU 卸载设置以适应你的内存。

更多信息请参阅 [Unsloth 推理指南](https://unsloth.ai/docs/zh/xin/studio/chat.md).
{% endstep %}

{% step %}

### 使用 Unsloth API 部署 MiniMax-M3.1-Flash

在兼容的运行时中，使用 `unsloth run` 以及以下 llama-server 选项来部署模型：

```bash
unsloth run --model unsloth/MiniMax-M3.1-Flash-GGUF:UD-Q2_K_XL \
    --temp 1.0 --top-p 0.95 --top-k 0 --min-p 0.0 \
    --chat-template-kwargs '{"reasoning_effort":"high"}' \
    --host 127.0.0.1 --port 8080
```

在以下地址聊天： `http://localhost:8080`；兼容 OpenAI 的 API 基础 URL 为 `http://localhost:8080/v1`.
{% endstep %}

{% step %}

### 连接你的工具

使用来自 `/v1/models`的模型 ID，将 API 客户端连接到此端点。保持服务器运行。
{% endstep %}
{% endstepper %}

### 🦙 在 llama.cpp 中运行 MiniMax-M3.1-Flash

{% stepper %}
{% step %}

### 构建支持 MiniMax-M3.1 的 llama.cpp

使用 Linux、WSL 或 macOS 上的 Bash，构建 [PR #31192](https://github.com/ggml-org/llama.cpp/pull/31192) 。

在 Ubuntu / WSL 上，安装构建依赖项：

```bash
sudo apt-get update
sudo apt-get install -y build-essential cmake git libssl-dev
```

对于 NVIDIA，请安装 [CUDA 工具包](https://developer.nvidia.com/cuda-downloads)。在 macOS 上，安装 Xcode 命令行工具和 CMake；使用 `-DGGML_CUDA=OFF` （默认启用 Metal）。使用 `OFF` 也可仅构建 CPU 版本。

```bash
git clone https://github.com/ggml-org/llama.cpp
git -C llama.cpp fetch origin pull/31192/head:minimax-m31
git -C llama.cpp checkout minimax-m31
cmake llama.cpp -B llama.cpp/build \
    -DCMAKE_BUILD_TYPE=Release \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --target llama-server
```

{% endstep %}

{% step %}

### 下载 GGUF

安装 Hugging Face CLI 并下载 **全部四个分片** 的 `UD-Q2_K_XL`:

```bash
pip install -U huggingface_hub
hf download unsloth/MiniMax-M3.1-Flash-GGUF \
    --local-dir unsloth/MiniMax-M3.1-Flash-GGUF \
    --include "UD-Q2_K_XL/*"
```

将所有分片放在一起，并将 `--model` 指向第一个分片；llama.cpp 会加载其余分片。若使用其他量化版本，请更改下载筛选条件和模型路径。
{% endstep %}

{% step %}

### 运行 MiniMax-M3.1-Flash

启动本地聊天服务器：

```bash
./llama.cpp/build/bin/llama-server \
    --model unsloth/MiniMax-M3.1-Flash-GGUF/UD-Q2_K_XL/MiniMax-M3.1-Flash-UD-Q2_K_XL-00001-of-00004.gguf \
    --temp 1.0 \
    --top-p 0.95 \
    --top-k 0 \
    --min-p 0.0 \
    --chat-template-kwargs '{"reasoning_effort":"high"}' \
    --host 127.0.0.1 --port 8080
```

{% endstep %}
{% endstepper %}

#### 图像输入

对于图像输入，请另外下载 `mmproj-BF16.gguf` 视觉投影器（约 1.74 GB）：

```bash
hf download unsloth/MiniMax-M3.1-Flash-GGUF \
    --local-dir unsloth/MiniMax-M3.1-Flash-GGUF \
    --include "mmproj-BF16.gguf"
```

添加此服务器选项，并为投影器和图像处理预留额外内存：

```bash
--mmproj unsloth/MiniMax-M3.1-Flash-GGUF/mmproj-BF16.gguf
```

### ⚡ DSpark - 推测解码

M3.1 以 [MTP](https://unsloth.ai/docs/zh/mo-xing/mtp.md) 取代了类似 EAGLE 的 **DSpark**：草稿模型提出候选词元，供主模型验证，从而可能加快解码速度。它需要匹配的 MiniMax-M3.1 草稿模型和额外内存。

[PR #31192](https://github.com/ggml-org/llama.cpp/pull/31192) 支持 DSpark；上面的命令使用普通解码。若有匹配的草稿模型，请添加以下选项，并将文件名替换为其本地路径：

```bash
--spec-type draft-dspark \
    -md MiniMax-M3.1-Flash-DSpark-BF16.gguf \
    --spec-draft-p-min 0
```

## 📊 基准测试

### GGUF KLD 与 Top-1% 基准测试

在七个类别中， **UD-Q2\_K\_XL 的 Top-1 一致率约为 85.3–95.7%**, **UD-Q4\_K\_XL 约为 97.3–99.0%**，而 **UD-Q8\_K\_XL 约为 97.8–99.3%**。Q4 比 Q8 少占用 9.7 GB，且一致率差距很小；Q8 的 KLD 在所有类别中也更低。

<figure><img src="https://2657992854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxhOjnexMCB3dmuQFQ2Zq%2Fuploads%2FLKBqgmIgiNf9wTXbGNsX%2Fminimax-top1.png?alt=media&amp;token=3a155732-d550-4397-86b2-c3d134e5912d" alt="MiniMax-M3.1-Flash GGUF top-1 agreement by file size across seven evaluation categories. Higher is better."><figcaption><p>七个类别中的 Top-1 词元一致率。数值越高越好；所报告数值为根据图表估算的近似读数。</p></figcaption></figure>

### 官方基准测试

[MiniMax 官方测试结果](https://huggingface.co/MiniMaxAI/MiniMax-M3.1-Flash) 如下所示。

| 基准测试                    | MiniMax-M3.1-Flash | DeepSeek-V4.1-Flash-1017 |
| ----------------------- | ------------------ | ------------------------ |
| Automation-Bench v1.0.6 | 62.8               | 60.5                     |
| Terminal Bench 4.0      | 38.1               | 42.3                     |
| DeepSWE v1.1            | 73.7               | 77.0                     |
| NL2Repo-Bench           | 61.2               | 68.2                     |
| BabyVision（使用工具）        | 91.0               | 92.5                     |
| HLE（不使用工具）†             | 43.4               | 42.6                     |
| OSWorld 2.0             | 61.7               | —                        |
| LOCA-Bench 256K         | 60.3               | —                        |

† HLE 使用纯文本子集。评测工具：Terminal Bench 使用 Codex 0.149.1；DeepSWE 使用 mini-SWE-agent 2.4.5；NL2Repo 使用 Claude Code 2.1.233。后两者使用 512K 上下文。得分取决于设置和推理力度；— 表示没有公布结果。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://unsloth.ai/docs/zh/mo-xing/minimax-m3.1-flash.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
