MiniMax-M3 vLLM-Ascend 补丁应用与运行手册

1. 简介

本目录提供 MiniMax-M3 在 Ascend NPU 上通过 vLLM-Ascend 部署和验证的交付说明。

本目录提供的交付物：

0001-vllm-ascend-MiniMax-M3.patch: MiniMax-M3 模型在 vllm-ascend 运行所需的模型适配、权重加载、量化权重支持、推理运行时兼容和相关 patch
model.safetensors.index.json: 当前 MiniMax-M3 MXFP8 权重缺少的权重分片索引文件

本次适配支持的主要特性：

支持图片输入能力，--limit-mm-per-prompt 建议使用 {"image":1}。
支持 MiniMax-M3 的 reasoning parser 和 tool-call parser：
- --reasoning-parser minimax_m3
- --tool-call-parser minimax_m3
支持 TP16 + EP 部署：
- --tensor-parallel-size 16
- --enable-expert-parallel
支持 prefix cache，默认开启：
支持 FULL_DECODE_ONLY 图捕获配置，推荐 capture size 为 [1,2,4,8]。
支持 W8A8 量化权重目录，vLLM-Ascend 会自动识别 quant_model_description.json。
支持 MXFP8 权重加载；当前 Ascend NPU 路径会在加载时将 MXFP8 权重反量化为 BF16，而不是直接使用原生 MXFP8 执行 kernel。

2026-06-16更新：

处理A2服务器TP8下模型输出乱码问题。

当前不包含的能力：

video：本交付 patch 不包含 video 适配，启动参数不要传 video:1。

2. 补丁应用

基础镜像：

quay.io/ascend/vllm-ascend:v0.20.2rc1

准备变量：

PATCH_DIR=/path/to/patches
VLLM_ASCEND_REPO=/vllm-workspace/vllm-ascend

应用 vllm-ascend 补丁：

cd "$VLLM_ASCEND_REPO"
git apply --check "$PATCH_DIR/0001-vllm-ascend-MiniMax-M3.patch"
git apply "$PATCH_DIR/0001-vllm-ascend-MiniMax-M3.patch"

确认补丁状态：

cd "$VLLM_ASCEND_REPO"
git status --short
python3 -m py_compile vllm_ascend/models/minimax_m3_vl.py

如需回退已应用补丁：

cd "$VLLM_ASCEND_REPO"
git apply -R --check "$PATCH_DIR/0001-vllm-ascend-MiniMax-M3.patch"
git apply -R "$PATCH_DIR/0001-vllm-ascend-MiniMax-M3.patch"

3. 服务启动

以下命令默认从 /workspace 目录启动，默认端口为 8000。

3.1 服务启动参数

常规功能验证启动命令：

cd /workspace

HCCL_OP_EXPANSION_MODE=AIV \
vllm serve /path/to/Minimax-M3 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --max-model-len 10240 \
  --tensor-parallel-size 16 \
  --enable-expert-parallel \
  --max-num-seqs 8 \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice \
  --tool-call-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1}' \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY","cudagraph_capture_sizes":[1,2,4,8]}' \
  --port 8000

4. 基本验证

4.1 服务就绪检查

curl -sS http://127.0.0.1:8000/v1/models

4.2 文本生成验证

curl -sS http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-m3",
    "messages": [
      {
        "role": "user",
        "content": "计算 123 + 273，只输出最终数字。"
      }
    ],
    "temperature": 0,
    "max_tokens": 64
  }'

预期输出包含：

4.3 多模态能力验证

图片能力只在启动时设置 --limit-mm-per-prompt '{"image":1}' 时可用。

curl -sS http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "minimax-m3",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "描述图片中的主要图形和颜色。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAzElEQVR4nO2YQQ7DIAzAxtT/f5keuI4QSoeFZF9JKqxAgJZa6+dkvvQEVlGARgEaBWiu7kgpL3z+/4fM8RVQgKa/B3bxc6/l9w4pELSJNpTRwJZQpsllYhiBfIseRgICswdMHL9b4NnxGGQd30a3CqzcTnq5VoBGARoFaLYKrLzPerlWYJJnRQiygArMOsTxzBLKOwwjC/h7fXg1ykyNfFK2+R38Jm4srgDbKI0CNArQKECjAI0CNArQKECjAI0CNArQKECjAI0CNArQ3PF3JIXlxSZKAAAAAElFTkSuQmCC"
            }
          }
        ]
      }
    ],
    "temperature": 0,
    "max_tokens": 128
  }'

预期返回为 HTTP 200，内容应能识别图片中的红色方块和蓝色圆形。

5. 注意事项

该补丁仅用于功能体验，不建议直接用于生产环境。
当前版本多模态功能未充分验证。