> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# 在本地运行 MiniMax M3 — 务实路径（以及 M2）

> MiniMax M3 是一款拥有 1M 上下文、428B 开放权重的 MoE 模型；M2 系列则是拥有成熟社区 GGUF 的编程智能体系列。本文介绍哪些模型能在你的硬件上运行。

> [!NOTE]
>
> Last verified: 2026-10-14

MiniMax 发布面向智能体的开放权重模型。**MiniMax M3** 是当前旗舰——一款 **\~428B 混合专家（MoE）** 模型（每个 token 约 23B 活跃参数），拥有 **1M token 上下文**、原生多模态输入以及计算机使用/智能体工具调用能力。**M2 系列**（M2 → M2.5 → M2.7）是早期面向编程智能体的系列，约 \~230B；它更小、仅支持文本，并且——对于本地运行而言重要的是——拥有最成熟的社区量化生态系统。这些模型都不是单张消费级 GPU 能运行的，但 M2 系列 *确实* 可以在大内存 Mac 或工作站上运行。本页介绍哪些模型实际能在哪些硬件上运行，然后介绍如何使用 Tokios 为其提供私有端点。

## 你能在本地运行 MiniMax 吗？

MiniMax 在其官方仓库中仅发布 **safetensors**（BF16/F32）格式——没有官方的 GGUF、AWQ 或 MLX。所有量化版本均来自社区（Unsloth、bartowski 等）。这意味着：

| 模型 | 现实的本地配置 | 备注 |
| - | - | - |
| **M3**（\~428B / 23B 活跃） | 社区 GGUF 需要 128–270 GB RAM/VRAM，或用于 safetensors 的多 GPU 服务器 | 最重；见下文关于稀疏注意力的注意事项 |
| **M2.7 / M2.5**（\~229B / 10B 活跃） | **128 GB 统一内存 Mac**，或 1×16 GB GPU + \~96 GB 系统内存 | 约 \~15–25 tok/s 在 128 GB Mac 上使用 `UD-Q3/IQ4` 级量化 |
| **M2**（\~230B / 10B 活跃） | 与 M2.5/M2.7 同类 | 原始版本；大多数第三方工具引用此版本 |
| 单张消费级 GPU（8–24 GB） | 无法单独运行 | 即使是最小的可用量化版本也需 \~100 GB+ |

所以实际情况是：MiniMax 是**大内存**模型，而非笔记本 GPU 模型。如果你拥有 128 GB+ 统一内存 Mac 或拥有 128–512 GB RAM 的工作站，M2 系列可以通过社区 GGUF 运行。低于此配置，MiniMax 实际上就是一个 API/云端模型。

> [!WARNING]
>
> **MiniMax 稀疏注意力（MSA）尚未在 `llama.cpp` 中获得支持。** M3 主打的 1M 上下文和速度优势来自 MSA——但社区 GGUF 构建会回退到密集注意力，因此 *本地* 使用 `llama.cpp`/LM Studio 运行 M3 目前无法提供 M3 完整的长上下文行为。若要体验完整上下文下的真实 M3，请使用 vLLM/SGLang 运行 safetensors。

## "Ollama 上的 MiniMax"是云端，而非本地

`minimax-m3`、`minimax-m2.7`、`minimax-m2.5` 和 `minimax-m2` 均存在于 Ollama 库中——但每个都仅暴露 **`:cloud`** 标签。这些标签将请求代理到 MiniMax 的托管 API；权重不会下载到你的机器，因此没有本地内容供连接器指向。要在你控制的硬件上自托管 MiniMax，请使用下文中的社区 GGUF（`llama.cpp`/LM Studio）或 safetensors（vLLM/SGLang）——而不是 Ollama 的 `:cloud` 标签。

## 在你自己的硬件上运行

**Community GGUF — M2 line (big-RAM Mac/workstation)**

在 128 GB+ 统一内存 Mac 或大内存工作站上，通过 `llama.cpp` 或 LM Studio 运行 M2.5/M2.7 社区 GGUF。从 Unsloth 或 bartowski 的量化版本开始，选择适合你组合内存的最大版本（`UD-Q3_K_XL` ≈ 101 GB，`UD-IQ4_XS` ≈ 108 GB；`Q8_0` ≈ 243 GB 需要 \~256 GB RAM）。然后 LM Studio 会在 `http://127.0.0.1:1234/v1` 上暴露兼容 OpenAI 的 API。

**vLLM / SGLang — M3 (multi-GPU server)**

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
vllm serve MiniMaxAI/MiniMax-M3 \
  --tensor-parallel-size 8 \
  --trust-remote-code
```

在多 GPU 机器上提供官方 safetensors，以获得 M3 真实的 1M 上下文行为（保留 MSA）。vLLM 会在 `http://127.0.0.1:8000/v1` 上暴露兼容 OpenAI 的 API。在提供服务前，请检查模型卡片以获取当前推荐的标志和工具调用解析器。

## 变体与规格

以下所有数值均来自 Hugging Face 上的 MiniMax 模型卡片和 MiniMax 的发布说明。M2、M2.1、M2.5 和 M2.7 在 MiniMax 自己的文档中标记为**已被取代**——M3 是当前版本。在标准化之前，请对照模型卡片进行验证。

| 属性 | MiniMax M3（当前） | MiniMax M2.7 | MiniMax M2（原始） |
| - | - | - | - |
| Hugging Face | [`MiniMaxAI/MiniMax-M3`](https://huggingface.co/MiniMaxAI/MiniMax-M3) | [`MiniMaxAI/MiniMax-M2.7`](https://huggingface.co/MiniMaxAI/MiniMax-M2.7) | [`MiniMaxAI/MiniMax-M2`](https://huggingface.co/MiniMaxAI/MiniMax-M2) |
| Ollama 标签 | `minimax-m3:cloud`（仅限云端） | `minimax-m2.7:cloud`（仅限云端） | `minimax-m2:cloud`（仅限云端） |
| 参数 | \~428B 总计 / **\~23B 活跃**（128 个专家，每 token 4 个 + 1 个共享） | \~229B 总计 / **\~10B 活跃** | \~230B 总计 / **\~10B 活跃**（256 个专家，每 token 8 个） |
| 上下文窗口 | 1,048,576 (1M) | \~200K (204,800) | \~196K (196,608) |
| 模态 | 文本 + 图像 + 视频；计算机使用 | 文本 | 文本 |
| 官方格式 | Safetensors (BF16/F32) — 仅限社区 GGUF | Safetensors — 仅限社区 GGUF | Safetensors — 仅限社区 GGUF |
| 许可证 | MiniMax Community License | Non-commercial (authorization for commercial) | MIT + attribution clause |
| 最佳用途 | 旗舰智能体 + 长上下文 + 多模态 | 编程智能体（已被取代） | 编程智能体系列的起源；社区工具最完善 |

来源：[`MiniMaxAI/MiniMax-M3`](https://huggingface.co/MiniMaxAI/MiniMax-M3)、[`MiniMaxAI/MiniMax-M2`](https://huggingface.co/MiniMaxAI/MiniMax-M2)、[MiniMax 发布说明](https://platform.minimax.io/docs/release-notes/models)、[ollama.com/library/minimax-m3](https://ollama.com/library/minimax-m3)。

> [!NOTE]
>
> **许可证因版本而异。** M2 是 MIT-with-attribution（宽松），M2.7 是**非商业**（商业使用需要书面授权），M3 使用 **MiniMax Community License**（低于收入阈值免费，需注明 "Built with MiniMax M3"）。在任何商业部署之前，请阅读特定模型卡片上的 `LICENSE`/`LICENSE-MODEL` 文件。

## 你应该运行哪个 MiniMax？

* **M3** 适合需要当前旗舰——长上下文、多模态、智能体——并且拥有多 GPU 服务器的情况（也可以接受在大内存机器上 `llama.cpp` 的稀疏注意力限制）。
* **M2 / M2.7** 适合拥有 128 GB 统一内存 Mac 或大内存工作站，并且想要一个可以通过成熟社区 GGUF *现在* 运行的编程智能体模型的情况。M2 拥有最成熟的第三方工具；M2.7 是较新的编程版本（非商业许可证）。

## 使用 Tokios 连接

一旦 MiniMax 在你自己的硬件上运行——LM Studio、`llama.cpp`、vLLM 或 SGLang 暴露兼容 OpenAI 的 `/v1`——配对 Tokios 连接器，以便你可以从 Claude Code、Cline 或任何其他兼容客户端通过 `https://api.tokios.com` 访问它，而不仅仅局限于那台机器。

**1. 配对 Tokios 连接器**

在 [tokios.com/console](https://tokios.com/console) 登录，打开 **Setup** 选项卡，并点击 **Start pairing** 获取一次性配对码（`TKS-XXXX-XXXX`）。在运行 MiniMax 的机器上安装并运行连接器：

```bash macOS theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX
```

```bash Linux theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX
```

然后 **approve** 该设备，在 **Setup** 或 **Connectors** 选项卡中操作。

**2. 将连接器指向你的运行时的 /v1 API**

LM Studio 提供 `http://127.0.0.1:1234/v1`；vLLM/SGLang 提供 `http://127.0.0.1:8000/v1`。将正确的那个设置为 `tokios-connector.json` 中的上游——参见 [连接器配置](https://docs.tokios.com/reference/connector-config.md)。

**3. 注册部署**

在 [Models](https://tokios.com/console/models) 选项卡中，注册模型并选择一个公共部署名称，例如 `minimax-tunnel`。客户端在 `model` 字段中发送的是这个名称——而不是上游模型 ID。

**4. 创建 API 密钥**

在 [Keys](https://tokios.com/console/keys) 选项卡中，点击 **Create key**。立即复制 `sk-tok-…` 密钥——它仅显示一次。

### 从任何地方调用

```bash curl (OpenAI-compatible) theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-tunnel",
    "stream": true,
    "messages": [{"role": "user", "content": "Refactor this module and run the tests."}]
  }'
```

```bash Claude Code (Anthropic-compatible) theme={"theme":{"light":"github-light","dark":"css-variables"}}
export ANTHROPIC_BASE_URL=https://api.tokios.com
export ANTHROPIC_API_KEY=sk-tok-YOUR_KEY
claude --model minimax-tunnel
```

> [!TIP]
>
> 其中 `model` 字段始终是你注册的**部署**名称（如上文的 `minimax-tunnel`），而不是上游模型 ID。有关完整的客户端设置，请参阅 [使用 Claude Code](https://docs.tokios.com/guides/claude-code.md) 和 [使用 Cline](https://docs.tokios.com/guides/cline.md)。

## 注意事项

* MiniMax 仅发布 **safetensors**——每个 GGUF/AWQ/MLX 构建都是社区制作的。在依赖某个版本之前，请检查量化作者。
* **Ollama 的 `minimax-*` 标签仅限 `:cloud` 使用**——它们在 MiniMax 的基础设施上运行，而不是你的。如果你想本地运行，请通过社区 GGUF 或 safetensors 自托管。
* **`llama.cpp` 尚不支持 MiniMax 稀疏注意力**，因此 M3 的本地 GGUF 运行会回退到密集注意力并失去 M3 完整的长上下文优势——请使用 vLLM/SGLang 获得真实体验。
* 这些是**大内存 MoE** 模型——即使每个 token 仅激活 \~10–23B 参数，所有参数也必须放入内存。请计划使用 128 GB+ 的机器，而不是单张消费级 GPU。

> **[快速入门](https://docs.tokios.com/quickstart.md)**
>
> 配对连接器并端到端注册你的第一个模型。

> **[在 Mac Studio 上运行模型](https://docs.tokios.com/use-cases/mac-studio.md)**
>
> 为什么大统一内存 Mac 是 M2 系列的天然家园。

> **[你的 GPU 能容纳多大模型？](https://docs.tokios.com/guides/model-fit.md)**
>
> 这些内存数字背后的尺寸计算。

> **[哪个任务适合哪个本地模型？](https://docs.tokios.com/guides/model-by-task.md)**
>
> 可以在你已拥有的硬件上运行的较轻量模型。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.