---
title: Minimax-M3.1-flash
canonical_url: "https://www.modelscope.cn/studios/AMD_Dev/Minimax-M3.1-flash"
md_url: "https://www.modelscope.cn/studios/AMD_Dev/Minimax-M3.1-flash.md"
repository: AMD_Dev/Minimax-M3.1-flash
last_updated: 2026-11-09
sdk_type: docker
sdk_version: 5.49.1
downloads: 0
stars: 2
---

# Minimax-M3.1-flash

> Minimax-M3.1-flash - AMD_Dev 在 ModelScope 创建的在线 Demo。MiniMax-M3.1-Flash · ModelScope Docker 创空间（AMDDev/Minimax-M3.1-flash）

AMD_Dev/Minimax-M3.1-flash 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 docker 5.49.1 构建。

- **Repository**: AMD_Dev/Minimax-M3.1-flash
- **SDK**: docker
- **SDK version**: 5.49.1
- **Downloads**: 0
- **Stars**: 2
- **Last updated**: 2026-11-09

Source: https://www.modelscope.cn/studios/AMD_Dev/Minimax-M3.1-flash

---

# MiniMax-M3.1-Flash · ModelScope Docker 创空间（AMD_Dev/Minimax-M3.1-flash）

把 `MiniMax/MiniMax-M3.1-Flash` 部署成 ModelScope Docker 创空间：网页对话 + OpenAI 兼容 API，接入统一 LLM-Gateway
准入与 ADP 认证，试用额度和身份与其他创空间共用。应用层（`app.py`、`api.py`、准入、用量、页面、监控、自愈、构建链、
`verify.py --image`）来自 MiniCPM 创空间 `AMD_Dev/Minicpm-v47` 的 `db14c69`（GLM Model-API + patches/0001 + 0002），
只换了启动命令、运行参数和模型名称，按 `work record/modelscope/01-部署流程与新模型适配.md` 第 4–7 步落地；
SGLang 参数与运行补丁沿用 DO 集群 `minimax-m31-flash-serving` 上验证过的 `start_m31.sh` 配置。

**硬件：8 × AMD Instinct MI308X**（gfx942，每卡 80 CU，算力约 MI300X 的 26%）。本仓库**没有在 MI308X 上跑过**；
下文的性能数字全部来自 DO 上的 4 × MI300X，**不适用于 MI308X**。当前状态与验证记录见 `STATUS.md`。

## 硬约束：MI300X 不支持原生 FP4（MI308X 同为 gfx942）

- 路由专家的 NVFP4 只是存储格式。加载时 `compat/minimax-m31-sglang/m31_rocm_fixes.py`（SGLang 插件，与 DO 逐字节相同）
  把专家转成 block-FP8 [128,128] e4m3fnuz，交给 Triton fused MoE 执行。包里没有、也不尝试任何原生 FP4 路径。
- `M31_GFX942_EXPERTS=fp8` 是唯一允许的取值：profile、start 脚本、启动器、插件入口都拒绝其他取值；`verify.py` 扫描运行
  文件，不允许 FP4 / Marlin / `--quantization` 开关，并按 sha256 锁定插件。
- 稠密部分（MXFP8）由上游转成 block-FP8，投影用 aiter CK blockscale GEMM（`SGLANG_AITER_GFX942_BLOCKSCALE_USE_CK=1`）。

## 部署形态

```text
调用方 ─► ModelScope 边缘（鉴权；注入 X-ModelScope-Router-Id、X-Forwarded-For）
            │
            ▼
  :7860  app.py（单进程：Gradio 网页 + /v1 OpenAI 兼容接口 + /healthz /readyz）
            1. LLM-Gateway 准入 begin / first-output / finish（Router ID 的 HMAC 指纹；试用额度 / ADP）
            2. 长上下文按用户限流 long_context_throttle.py（输入 > 262144 token 才参与；网页与 /v1 共用一份状态）
            3. 实例选择 overflow_routing.py（在途请求最少的实例；连接失败换另一个；请求体原样转发）
            ├────────────────────────────┐
            ▼                            ▼
  127.0.0.1:8001 SGLang TP4       127.0.0.1:8002 SGLang TP4
  GPU 0-3（实例 0）                GPU 4-7（实例 1，晚 10 秒启动，--nccl-port 28002）
```

- engine.py 在 7860 进程里下载 / 校验权重、预检、拉起并监督两个实例、预热、自愈（与 MiniCPM 相同的机制）。
- 推理后端只监听本机，不配 SGLang `--api-key`（`SGLANG_API_KEY` 不设；start 脚本和 `verify.py` 发现它会拒绝）。
- 不用 sglang_router：它会把请求体反序列化重写（MiMo 在 DO 上实测音频请求 400），M3.1 依赖顶层 `thinking`、
  `reasoning_effort`、工具调用和图片 / 视频字段；应用层本来就逐请求做准入和限流，直接把原始请求体字节发给选中的实例。
- 两实例是一个整体：`/readyz` 要两个实例都存活、`/health` 正常、模型已列出且各自预热完成；任一实例退出或连续 3 次
  健康检查失败，engine 停掉两个一起重启（退避 15–300 秒）。`/healthz` 只看 7860 进程，从不调用模型。
- `M31_INSTANCES=1` 可改成单实例（GPU 0-3 → 127.0.0.1:8000，需要 4 卡），默认 2。分流（overflow）关闭。

## 运行补丁在每个 SGLang 进程里生效

`compat/minimax-m31-sglang/` 在 PYTHONPATH 首位，里面的 `m31_rocm_fixes-1.0.dist-info` 登记了 SGLang 通用插件入口点
`m31_gfx942_experts = m31_rocm_plugin:register`。SGLang 在启动器主进程、每个 scheduler 进程和 detokenizer 进程开头调用
`load_plugins()`，所以补丁在 spawn 出来的子进程里同样加载（DO 日志：每个实例 6 个进程各一条 `plugin registered`）。

`load_plugins()` 对插件抛出的 `Exception` 只记日志、继续启动，`m31_rocm_fixes.register()` 在非 gfx942 时也是直接返回。
`m31_rocm_plugin.register` 因此在 `register()` 之后逐项检查补丁标记（block-FP8 专家、ROCm 量化白名单、BCG 稀疏缓存、
多模态 eager），缺一项就 `SystemExit`：scheduler 退出后启动器 5 秒内报错退出，engine 按退避重启并在日志里留下原因。
启动日志里每个进程会有一行 `[m31_rocm_plugin] pid=… patches active: experts=block-FP8, rocm-quant-check,
bcg-safe-sparse-cache, bcg-mm-eager`。`m31_rocm_fixes.py`、`sitecustomize.py`、`selfcheck_media.py`、`METADATA` 与 DO
逐字节相同；入口点从 `m31_rocm_fixes:register` 改指向这个包装，是与 DO 唯一的有意差别。

## 创空间标识

| 项 | 位置 | 值 |
| --- | --- | --- |
| 创空间 | — | [`AMD_Dev/Minimax-M3.1-flash`](https://www.modelscope.cn/studios/AMD_Dev/Minimax-M3.1-flash) |
| 创空间 slug | profile `STUDIO_SLUG` | `amd-dev-minimax-m3-1-flash`（创建后在页面 API 地址里核对） |
| Gateway 来源 ID | profile `SPACE_ADMISSION_ID` | `minimax-m31-flash`（Gateway 里显示为 `modelscope-space:minimax-m31-flash`） |
| 创空间名称 | profile `USAGE_ADMIN_STUDIO_OWNER` / `USAGE_ADMIN_STUDIO_NAME` | `AMD_Dev` / `Minimax-M3.1-flash` |
| git remote | `https://www.modelscope.cn/studios/AMD_Dev/Minimax-M3.1-flash.git`（不要把 Token 写进 URL） | — |

新的来源 ID **不需要在 Gateway 侧登记**：Gateway 只校验 `X-Space-Id` 的格式（`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`）
和共享密钥签名，第一次 begin 时自动出现 `modelscope-space:<id>` 来源。前提是本创空间的
`SPACE_ADMISSION_SHARED_SECRET`、`USAGE_IDENTITY_HMAC_KEY` 与 Gateway 及其他创空间完全相同。

## 创空间设置（环境变量与 Secret）

运行参数全部写在 `config/minimax-m31-flash-tp4x2.env.sh`，不要在创空间里覆盖。只需要配置（名字见 `.env.example`）：

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `SPACE_ADMISSION_BASE_URL` | 环境变量 | LLM-Gateway control-api 地址，与其他创空间相同；为空时所有生成请求返回 429 |
| `SPACE_ADMISSION_SHARED_SECRET` | Secret | 与 Gateway 相同，≥ 32 字节 |
| `USAGE_IDENTITY_HMAC_KEY` | Secret | 与 Gateway 及所有创空间完全相同，≥ 32 字节，永不轮换（也是长上下文限流的用户身份） |
| `USAGE_DASHBOARD_KEY` | Secret，可选 | 本地用量看板与日志下载 |
| `SGLANG_API_KEY`、`MODEL_ID`、`MODEL_API_KEY_*`、`OVERFLOW_*`、`THROTTLE_*` | **不要设** | 见 `.env.example` |

硬件 8 × MI308X；持久化盘 ≥ 320 GB（权重 252.4 GB + Triton / inductor 缓存 + 日志）。

## SGLang 启动参数（每个实例）

engine.py 为每个实例生成同一条命令（`verify.py` 构建期与 `expected-vllm-command.json` 逐字比对）：

```bash
python3 -u /workspace/Model_API-upload/compat/minimax-m31-sglang/launch_m31_sglang.py --profile p3-bs64-ctx1m-moetuned --port 8001 --nccl-port 28001
```

启动器按 `config/profiles.json` 展开成最终参数（与 DO `start_m31.sh` 同名配置档的最终生效值逐项一致）：

```text
--served-model-name=MiniMax-M3.1-Flash --trust-remote-code --tp-size=4
--attention-backend=triton --moe-runner-backend=triton --page-size=128
--context-length=1048576 --mem-fraction-static=0.85 --chunked-prefill-size=16384
--max-running-requests=64 --cuda-graph-max-bs-decode=64 --disable-custom-all-reduce
--cuda-graph-backend-prefill=breakable --cuda-graph-max-bs-prefill=4096
--reasoning-parser=minimax-m3 --tool-call-parser=minimax-m3 --tokenizer-worker-num=1
--kv-cache-dtype=bf16 --enable-cache-report
启动器追加：--model-path=$MODEL_DIR --chat-template=<补丁后的模板> --host=127.0.0.1 --port=<8001|8002>
环境变量：M31_GFX942_EXPERTS=fp8  SGLANG_AITER_GFX942_BLOCKSCALE_USE_CK=1  M31_BCG_SAFE_SPARSE_CACHE=1  M31_BCG_MM_EAGER=1
         SGLANG_MOE_CONFIG_DIR=/tmp/minimax-m31-flash/moe-configs（仅调优档）  USE_ROCM_AITER_ROPE_BACKEND=0
         SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION=false  HIP_VISIBLE_DEVICES=0,1,2,3 | 4,5,6,7
```

| 配置档 | 状态 | 并发 / decode graph | 上下文 | 与默认档的差别 |
| --- | --- | --- | --- | --- |
| `p3-bs64-ctx1m-moetuned` | 默认 | 64 / 64 | 1,048,576 | — |
| `p3-bs64-ctx1m` | 回退 | 64 / 64 | 1,048,576 | 不带 Triton MoE 调优表 |
| `p2-ck-bcg4096` | 回退 | 32 / 32 | 131,072 | bs32 + 128K，不带调优表 |

KV 缓存 BF16、`--mem-fraction-static=0.85`。DO 上还在验证的 FP8 KV、HiCache（每实例约 512 GiB 主机内存）、
mem-fraction 0.87 **没有**放进本仓库。换档要同时改 profile 的 `M31_PROFILE`、start 脚本的 `REQUIRED_PROFILE`、
`verify.py`，并重新生成命令记录和在 GPU 上验证。

## MI308X 与 MoE 调优表

- 显存**不按型号假设**：preflight 读每张卡的实际显存，低于 120 GiB 拒绝启动（每卡权重 101.40 GiB / 0.85，推算），
  低于 175 GiB 告警"1M 上下文的 KV 可能不够"（推算）。
- Triton MoE 调优表 `config/moe-tuning/E128-N768-AMD_Instinct_MI300X_VF-fp8_w8a8-block128x128.json` 是在 DO 的
  `AMD_Instinct_MI300X_VF` 上测的；SGLang 按设备名找表，MI308X 的设备名大概率不同，找不到就用默认 MoE 配置
  （性能相当于 `p3-bs64-ctx1m`）。engine 把实际设备名和表是否生效写进日志（`[MOE-TUNING] ...`）和
  `/healthz`、`/readyz` 的 `moe_tuning` 字段；`M31_MOE_TABLE_DEVICE_ALIAS=1` 才按本机名写一份（默认 0）。

## 权重

- ModelScope `MiniMax/MiniMax-M3.1-Flash`，固定 revision `23f72d4ad5bd6e5c3d10a23f0be71dd794f3fe42`；73 个文件、
  252,446,158,252 字节，逐文件 size + sha256 在 `deployment/model-api/model-files.json`。
- 首次部署按 revision 下载到 `/mnt/workspace/models/MiniMax-M3.1-Flash`，逐文件校验 sha256，不一致的文件改名隔离并拒绝
  启动；之后 profile 把 `MODEL_ID` 置空、只用本地权重；start 脚本每次比对文件长度和 safetensors 头。

## 长上下文按用户限流（应用层模块）

只对**输入 > 262144 token** 的生成请求（网页对话、`/v1/chat/completions`、`/v1/completions`、`/v1/responses`）按用户限流：

- 每用户同时最多 2 个、每分钟 4 个（令牌桶）；超出的在该用户的 FIFO 队列里排队，**不报错**。排队中断开立即出队；
  请求结束、出错、取消、断开都会归还并发槽。
- 用户身份与准入相同：`X-ModelScope-Router-Id` 的 HMAC 指纹。**不信任客户端的 `X-User-Id`**。准入关闭时退回
  `X-Forwarded-For` 从右数第 1 个地址，再退回对端地址。
- 计数：请求体字节数 + 8192 不超过阈值的请求不解析；更大的用模型自带 `tokenizer.json` 计数文本，`prompt` / `input_ids`
  是 token id 列表时按长度精确计数（不按字符估算；单测覆盖 524,288 个 id 与 200K 非流式不被误拒）。
- 状态在 7860 进程内存里，两个实例共用一份；网页（同步）和 `/v1`（异步）走同一个限流器。

## ModelScope 边缘约 120 秒断开非流式请求

DO 4 × MI300X 上 1M 输入的首 token 约 141 秒，MI308X 上会更长：

- `/v1` 非流式且输入 > 262144 token：直接返回 400 `long_context_requires_stream`，提示改用 `stream=true`。
- `/v1` 流式：先回 200 + SSE，排队期间和等首 token 期间每 15 秒发一行 SSE 注释（`: keep-alive`）。边缘是否把注释行
  算作活动**未在 ModelScope 上验证**。网页走 Gradio 队列 SSE（15 秒心跳）。

## 页面与接口

- 网页：文本、图片（每次 ≤ 4 张）、视频（每次 1 个）、文档（PDF / DOCX / 文本，≤ 5 个，抽成文本，最多 120 万字），
  思考开关（关闭 / 自适应 / 开启，对应 `thinking.type=disabled/adaptive/enabled`），工具调用走 API。
- API：`https://studio-amd-dev-minimax-m3-1-flash.api-inference.modelscope.net/v1`，`Authorization: Bearer <ModelScope Token>`。
  转发给 SGLang 的只有 `/v1/chat/completions`、`/v1/completions`、`/v1/responses`、`/v1/models`；其他 `/v1/*` 返回 404。
- 自检：`/healthz`、`/readyz`、`/v1/admission/identity`。

## 性能（DO 4 × MI300X 实测，不代表 MI308X）

DO 集群 4 × MI300X（304 CU）**单实例 TP4**、默认档，1K 入 / 200 出、流式、关思考：

| 并发 | 每请求输出 tok/s 均值 / P50 / P10 | ≥ 40 占比 | 输出总 tok/s | TTFT P50 (s) | TPOT 均值 (ms) |
| --- | --- | --- | --- | --- | --- |
| C1 | 79.9 / 80.0 / 79.9 | 100% | 78.3 | 0.05 | 12.6 |
| C32 | 51.5 / 51.7 / 48.5 | 100% | 1500.0 | 0.39 | 19.5 |
| C64 | 37.9 / 37.0 / 33.2 | 29% | 2083.3 | 0.80 | 26.8 |

- 1M 单请求：TTFT 约 141 秒（141.4 s），decode 48.9 tok/s；1M 随机词暗号 4/6；功能门禁 23/23。
- MI308X 每卡算力约为 MI300X 的 26%，调优表大概率不生效；两实例合计吞吐、MI308X 上的 1M TTFT 都还没有实测。

## 本地检查（不占 GPU、不下载权重）

```bash
cd /home/jixiong/Modelscope/minimax-m31-flash-modelscope-space
SCRIPTS="/home/jixiong/work record/modelscope/scripts"
python3 -S deployment/model-api/verify.py                       # 源码模式
python3 "$SCRIPTS/render_expected_command.py" --repo .
python3 "$SCRIPTS/modelscope_preflight.py" --repo .             # HEAD，FAIL 必须为 0
python3 -m unittest discover -s tests -t .                      # 需要 requirements.txt + tokenizers / httpx
```

## 推送（由用户在自己的终端执行）

Token 只在 `git push` 提示输入密码时输入，不写进 URL、文件或聊天；**不要 force push**。
`origin` 是 `AMD_Dev/Minimax-M3.1-flash`，其 master 已是 `4597f71`（2026-10-30 推送）；该创空间原为 Gradio SDK 单卡包，
本镜像要求创空间类型为 Docker、8 × MI308X、持久化盘 ≥ 320 GB，推送前后都要在设置页确认（见 `STATUS.md`）。

```bash
cd /home/jixiong/Modelscope/minimax-m31-flash-modelscope-space
git fetch origin
git status -sb                                  # 只能 ahead，不能 behind
git merge --ff-only origin/master               # 失败就停下
python3 "/home/jixiong/work record/modelscope/scripts/modelscope_preflight.py" --repo .
git -c credential.helper= push origin master    # 用户名 oauth2，密码粘贴 ModelScope Token
```

推送会触发 ModelScope 构建并重启服务；构建失败时线上旧版本不受影响。回滚用 `git revert <提交>` 后再推送，不要 force push。
权重目录与 JIT 缓存不受回滚影响。
