跳转至

MiniMax-M3

1 简介

Note

本文档中提到的“PD 分离部署”仅作为示例/参考设计,用于演示以分离模式部署 Prefill 和 Decode 的基本流程。不建议在生产环境中使用。

对于客户侧的生产环境,推荐使用 MindIE Motor + vLLM-Ascend。

MiniMax-M3 是一个多模态大语言模型,支持文本、图像和视频输入。在昇腾上,它支持 A2/A3 上的 BF16 和 W8A8、Atlas 800I A3(W8A8)和 Ascend 950DT系列产品(MXFP8)上的 Prefill-Decode 分离、思考模式、推理解析、工具调用解析以及多模态输入。

本文档涵盖支持的特性、环境与模型准备、单节点部署、多节点部署、PD 分离、思考与解析器配置、功能验证、精度评估以及故障排查。

本文档基于 vLLM Ascend 主分支编写。该模型在此分支上受支持。

2 支持的特性

请参阅支持特性列表了解模型支持矩阵。

请参阅特性指南获取特性配置说明。

3 前提条件

3.1 模型权重

权重版本 硬件要求 下载链接 说明
MiniMax-M3 (BF16) 2 Atlas 800I A3 nodes (64GB × 16 per node) ModelScope /
MiniMax-M3-w8a8 (W8A8) 1 Atlas 800I A3 node (64GB × 16) or 1 Atlas 800 A2 node (64GB × 8) ModelScope /
MiniMax-M3-MXFP8 (MXFP8) 1 个 950DT 节点(96GB × 8) ModelScope 支持 W8A8C8 配置:C8 为动态 KV-cache 量化。在服务命令中设置 --kv-cache-dtype fp8 以启用 FP8 KV cache。
MiniMax-M3-EAGLE3-GQA / ModelScope 用于 EAGLE3 投机解码的草稿模型;使用分组查询注意力(GQA)。

建议将模型权重放置在共享缓存目录中。

记录下载的模型目录,以便在部署命令中使用。将 WEIGHT_PATH(或 PD 模板中的 MODEL_PATH)设置为目标权重目录,例如 /models/MiniMax-M3-w8a8;启用投机解码时,将 EAGLE3_WEIGHT_PATH 设置为下载的 EAGLE3 draft 目录。将下面的权重路径占位符替换为这些实际路径,并确保它们在容器内可访问。LOG_PATH 是可写的日志文件路径;单节点示例使用当前目录中的文件。

3.2 验证多节点通信(可选)

对于多节点部署,请按照验证多节点通信环境验证通信环境。

4 安装

4.1 Docker 镜像安装

您可以使用官方一体化 Docker 镜像。有关可用的镜像标签和已发布版本,请参考使用 Docker。

步骤 1: 下载最新的 Docker 镜像

docker pull quay.io/ascend/vllm-ascend:{tag}

步骤 2: 启动 Docker 容器

根据您的硬件平台选择 docker run 命令:

# Set the vLLM Ascend image name.
export IMAGE=quay.io/ascend/vllm-ascend:{tag}
export NAME=minimax-m3-dev

# Start the container with the variables defined above.
docker run --rm \
--name $NAME \
--net=host \
--shm-size=100g \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
--device /dev/davinci8 \
--device /dev/davinci9 \
--device /dev/davinci10 \
--device /dev/davinci11 \
--device /dev/davinci12 \
--device /dev/davinci13 \
--device /dev/davinci14 \
--device /dev/davinci15 \
--device /dev/davinci_manager \
--device /dev/devmm_svm \
--device /dev/hisi_hdc \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /root/.cache:/root/.cache \
-it $IMAGE bash
# Set the vLLM Ascend image name.
export IMAGE=quay.io/ascend/vllm-ascend:{tag}
export NAME=minimax-m3-dev

# 950DT products have 8 NPUs and use Device UB.
docker run --rm \
--name $NAME \
--net=host \
--privileged=true \
--shm-size=60g \
--device /dev/davinci_manager \
--device /dev/hisi_hdc \
--device /dev/ummu \
--device /dev/uburma \
--device /dev/davinci0 \
--device /dev/davinci1 \
--device /dev/davinci2 \
--device /dev/davinci3 \
--device /dev/davinci4 \
--device /dev/davinci5 \
--device /dev/davinci6 \
--device /dev/davinci7 \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
-v /usr/local/dcmi:/usr/local/dcmi \
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /etc/hixlep:/etc/hixlep \
-v /etc/hccn.conf:/etc/hccn.conf \
-v /var/log/npu/:/usr/slog \
-v /root/.cache:/root/.cache \
-it $IMAGE bash

请根据您的环境调整数据卷挂载(例如模型权重和数据集)。在 950DT 产品上,请勿添加主机上不存在的 Atlas A3 挂载,例如 /dev/devmm_svm。

在同一主机的另一个终端中,检查容器状态(如果你更改了 NAME,请替换 minimax-m3-dev):

docker ps --filter name=minimax-m3-dev

预期结果:容器列出且状态为 Up。在原始容器终端中,验证 vLLM Ascend 版本:

pip show vllm-ascend

预期结果:显示版本信息,与拉取的镜像版本一致。

5 在线服务部署

使用以下各节中的部署命令启动在线服务。选择适用于你的硬件平台和权重格式的标签页。

有关部署示例中使用的标准 vllm serve 参数的说明,请参考 vLLM Serving 参数文档。有关通过 --additional-config 传递的昇腾特定选项,请参考附加配置。有关昇腾特定的环境变量,请参考环境变量。

--speculative-config 示例使用单引号 JSON。'"${EAGLE3_WEIGHT_PATH}"' 片段会在该 JSON 中展开草稿权重路径。

5.1 单节点部署

单节点部署在同一节点内完成 Prefill 和 Decode。MiniMax-M3(BF16)模型可部署在 1 个 Atlas 800I A3(64GB × 16)上,但 A3 系列上的 BF16 推荐双节点部署;不建议单节点部署。MiniMax-M3-w8a8(W8A8)量化模型推荐单节点部署在 1 个 Atlas 800I A3(64GB × 16)或 1 个 Atlas 800 A2(64GB × 8)上。MiniMax-M3-MXFP8(MXFP8)量化模型可部署在 1 个 Ascend 950DT系列产品(96GB × 8)上。

Note

--quantization 参数仅量化权重需要,且必须与权重变体匹配:

  • BF16 权重(MiniMax-M3):不要添加 --quantization;模型将以浮点方式加载。
  • W8A8 权重(MiniMax-M3-w8a8,ModelSlim 格式):使用 --quantization ascend。vLLM Ascend 可以从检查点文件中自动检测到这一点,但为了清晰起见,建议显式指定。
  • MXFP8 权重(MiniMax-M3-MXFP8):使用 --quantization mxfp8。

添加错误的 --quantization 值(或对 BF16 权重添加该参数)会导致检查点被误读并加载失败。

WEIGHT_PATH="<MINIMAX_M3_BF16_PATH>"
LOG_PATH="./minimax-m3-bf16.log"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_OP_EXPANSION_MODE="AIV"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve "${WEIGHT_PATH}" \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --max-model-len 133000 \
  --tensor-parallel-size 8 \
  --data-parallel-size 2 \
  --enable-expert-parallel \
  --max-num-seqs 16 \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{
      "enable_cpu_binding": true,
      "enable_flashcomm1": true,
      "ascend_compilation_config": {
      "fuse_norm_quant": false
      },
      "multistream_overlap_shared_expert": true,
      "weight_nz_mode": 2
  }' > "${LOG_PATH}" 2>&1 &
WEIGHT_PATH="<MINIMAX_M3_W8A8_PATH>"
EAGLE3_WEIGHT_PATH="<MINIMAX_M3_EAGLE3_GQA_PATH>"
LOG_PATH="./minimax-m3-w8a8.log"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_OP_EXPANSION_MODE="AIV"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve "${WEIGHT_PATH}" \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --quantization ascend \
  --max-model-len 133000 \
  --tensor-parallel-size 4 \
  --data-parallel-size 4 \
  --api-server-count 1 \
  --max-num-batched-tokens 32768 \
  --long-prefill-token-threshold 4096 \
  --enable-expert-parallel \
  --max-num-seqs 32 \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
  --additional-config '{
      "enable_cpu_binding": true,
      "enable_flashcomm1": true,
      "ascend_compilation_config": {
        "fuse_norm_quant": false
          },
      "multistream_overlap_shared_expert": true,
      "enable_shared_expert_dp": true,
      "weight_nz_mode": 2
  }' > "${LOG_PATH}" 2>&1 &
WEIGHT_PATH="<MINIMAX_M3_MXFP8_PATH>"
EAGLE3_WEIGHT_PATH="<MINIMAX_M3_EAGLE3_GQA_PATH>"
LOG_PATH="./minimax-m3-mxfp8.log"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=512
export HCCL_OP_EXPANSION_MODE="AIV"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve "${WEIGHT_PATH}" \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --distributed-executor-backend mp \
  --tensor-parallel-size 4 \
  --data-parallel-size 2 \
  --enable-expert-parallel \
  --dtype bfloat16 \
  --quantization mxfp8 \
  --max-model-len 133000 \
  --max-num-batched-tokens 16384 \
  --kv-cache-dtype fp8 \
  --max-num-seqs 500 \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --async-scheduling \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --gpu-memory-utilization 0.92 \
  --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_qknorm_rope":false,"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3, "kv_cache_dtype":"bfloat16"}' \
  --safetensors-load-strategy prefetch > "${LOG_PATH}" 2>&1 &

注意:在上述脚本中,max-num-seqs 限制一次迭代中调度的序列数量。请根据预期的输入/输出长度和请求并发数调整此限制,并在每次更改后测量吞吐量和延迟。仅当额外的序列能够容纳在可用的 KV cache 中时才增大该值;更高的限制并不保证更高的吞吐量,反而可能增加延迟或 KV cache 抢占。

文本请求不需要 --limit-mm-per-prompt,但省略此标志并不会禁用多模态支持或其内存规划。对于禁用多模态输入的纯文本服务,请使用 --language-model-only,如第 5.5 节所述。对于多模态部署,请根据实际请求形态配置限制。例如,对于双图像请求使用 --limit-mm-per-prompt '{"image":2,"video":0}',对于单视频请求使用 --limit-mm-per-prompt '{"image":0,"video":1}'。

5.2 多节点部署

在昇腾 A2 服务器上部署 BF16 模型至少需要两个节点。不建议在 A3 服务器上进行未启用 prefill–decode 分离的多节点部署。请根据实际环境更新 WEIGHT_PATH、EAGLE3_WEIGHT_PATH、LOG_PATH、local_ip、node0_ip 和 NETWORK_INTERFACE。将 NETWORK_INTERFACE 设置为本地通信网卡名称(例如 eth0);HCCL 和 Gloo 会直接使用该值。

在节点 0 上运行以下命令:

local_ip="${NODE0_IP}"
node0_ip="${NODE0_IP}"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_IF_IP=$local_ip
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export GLOO_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --max-model-len 133000 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --max-num-seqs 32 \
  --data-parallel-size 4 \
  --data-parallel-size-local 2 \
  --data-parallel-start-rank 0 \
  --data-parallel-address $node0_ip \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{"enable_cpu_binding":true, "ascend_compilation_config":{"fuse_norm_quant":false}, "enable_shared_expert_dp":true,"multistream_overlap_shared_expert": true, "weight_nz_mode": 2,"enable_flashcomm1":true}' > ${LOG_PATH} 2>&1 &

在节点 1 上运行以下命令:

local_ip="${NODE1_IP}"
node0_ip="${NODE0_IP}"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_IF_IP=$local_ip
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export GLOO_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --headless \
  --max-model-len 133000 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --max-num-seqs 32 \
  --data-parallel-size 4 \
  --data-parallel-size-local 2 \
  --data-parallel-start-rank 2 \
  --data-parallel-address $node0_ip \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{"enable_cpu_binding":true, "ascend_compilation_config":{"fuse_norm_quant":false}, "enable_shared_expert_dp":true,"multistream_overlap_shared_expert": true, "weight_nz_mode": 2,"enable_flashcomm1":true}' > ${LOG_PATH} 2>&1 &

在节点 0 上运行以下命令:

local_ip="${NODE0_IP}"
node0_ip="${NODE0_IP}"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_IF_IP=$local_ip
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export GLOO_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --quantization ascend \
  --max-model-len 133000 \
  --tensor-parallel-size 4 \
  --enable-expert-parallel \
  --max-num-seqs 32 \
  --data-parallel-size 8 \
  --data-parallel-size-local 4 \
  --data-parallel-start-rank 0 \
  --data-parallel-address $node0_ip \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{"enable_cpu_binding":true, "ascend_compilation_config":{"fuse_norm_quant":false}, "enable_shared_expert_dp":true,"multistream_overlap_shared_expert": true, "weight_nz_mode": 2,"enable_flashcomm1":true}' > ${LOG_PATH} 2>&1 &

在节点 1 上运行以下命令:

local_ip="${NODE1_IP}"
node0_ip="${NODE0_IP}"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_IF_IP=$local_ip
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export GLOO_SOCKET_IFNAME="${NETWORK_INTERFACE}"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --host 0.0.0.0 \
  --port 11223 \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --quantization ascend \
  --headless \
  --max-model-len 133000 \
  --tensor-parallel-size 4 \
  --enable-expert-parallel \
  --max-num-seqs 32 \
  --data-parallel-size 8 \
  --data-parallel-size-local 4 \
  --data-parallel-start-rank 4 \
  --data-parallel-address $node0_ip \
  --distributed_executor_backend "mp" \
  --gpu-memory-utilization 0.92 \
  --reasoning-parser minimax_m3 \
  --limit-mm-per-prompt '{"image":1,"video":0}' \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{"enable_cpu_binding":true, "ascend_compilation_config":{"fuse_norm_quant":false}, "enable_shared_expert_dp":true,"multistream_overlap_shared_expert": true, "weight_nz_mode": 2,"enable_flashcomm1":true}' > ${LOG_PATH} 2>&1 &

先启动两个节点,再等待初始化完成,并检查每个节点上由 LOG_PATH 配置的日志文件是否有错误。节点 1 使用 --headless,不暴露 HTTP API。节点 0 日志中出现 Application startup complete 后,在节点 0 容器内运行以下检查:

curl --noproxy '*' -fsS -i http://127.0.0.1:11223/health
curl --noproxy '*' -fsS http://127.0.0.1:11223/v1/models

预期结果:/health 返回 HTTP 200,且 /v1/models 列出 minimax-m3。如果启动失败或任一检查失败,请先检查两个节点的日志,再发送推理请求。

5.3 低于 1M Token 上下文部署

以下 PD 示例涵盖低于 1M token 的上下文,并使用 --max-model-len 133000。可选择普通 PD 或添加具有相同服务拓扑的 KV cache 池。关于单独的 1M 上下文配置,请参见第 5.4 节。

5.3.1 Prefill-Decode 分离部署

本节将 MiniMax-M3 PD 分离部署为 1P1D:在 Atlas 800I A3 上跨三个节点(一个 Prefill 节点和两个 Decode 节点);在 950DT 上运行于两个节点,下面的 950DT 示例还描述了将相同的 1P1D 部署扩展到三个节点。此处 1P1D 表示一个 Prefill 服务组和一个 Decode 服务组。Decode 组可跨两台机器,同时仍为一个全局 DP 组。

PD 分离将 Prefill 和 Decode 分离到不同的服务组中。Prefill 节点处理大型提示块,Decode 节点负责 token 生成,代理在两者之间转发请求。使用 Mooncake 进行 KV 缓存传输。通用 PD 分离工作流程请参考 Mooncake。

启动模式为:在每个节点上准备 launch_online_dp.py 和特定角色的 run_dp_template.sh,然后在每个引擎打印 Application startup complete 后启动负载均衡代理。下面的启动器在仓库示例的基础上扩展了 --pp-size:在 A3 上,Prefill 使用 DP=1、TP=4 和流水线并行(PP=4),将 60 个 transformer 层按 16,15,15,14 拆分;而 950DT 产品的 MXFP8 启动在两个角色上均使用 PP=1 和 DP=2。每个 DP rank 占用 tp_size * pp_size 个 NPU。

常见问题提示: 对于 KV 传输超时或 Mooncake 连接错误等 PD 分离问题,请参考公共 FAQ。对于 MiniMax 特有问题,请参考第 10 章 FAQ。

开始之前,请在每个节点上准备脚本 launch_online_dp.py:

import argparse
import multiprocessing
import os
import subprocess
import sys


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--dp-size",
        type=int,
        required=True,
        help="Data parallel size."
    )
    parser.add_argument(
        "--tp-size",
        type=int,
        default=1,
        help="Tensor parallel size."
    )
    parser.add_argument(
        "--pp-size",
        type=int,
        default=1,
        help="Pipeline parallel size."
    )
    parser.add_argument(
        "--dp-size-local",
        type=int,
        default=-1,
        help="Local data parallel size."
    )
    parser.add_argument(
        "--dp-rank-start",
        type=int,
        default=0,
        help="Starting rank for data parallel."
    )
    parser.add_argument(
        "--dp-address",
        type=str,
        required=True,
        help="IP address for data parallel master node."
    )
    parser.add_argument(
        "--dp-rpc-port",
        type=str,
        default="12321",
        help="Port for data parallel master node."
    )
    parser.add_argument(
        "--vllm-start-port",
        type=int,
        default=8000,
        help="Starting port for the engine."
    )
    return parser.parse_args()


args = parse_args()
dp_size = args.dp_size
tp_size = args.tp_size
pp_size = args.pp_size
dp_size_local = args.dp_size_local
if dp_size_local == -1:
    dp_size_local = dp_size
dp_rank_start = args.dp_rank_start
dp_address = args.dp_address
dp_rpc_port = args.dp_rpc_port
vllm_start_port = args.vllm_start_port
gpus_per_dp_rank = tp_size * pp_size


def run_command(visible_devices, dp_rank, vllm_engine_port):
    env = os.environ.copy()
    env.update(
        VISIBLE_DEVICES=visible_devices,
        SERVICE_PORT=str(vllm_engine_port),
        DP_SIZE=str(dp_size),
        DP_RANK=str(dp_rank),
        DP_ADDRESS=dp_address,
        DP_RPC_PORT=dp_rpc_port,
        TP_SIZE=str(tp_size),
        PP_SIZE=str(pp_size),
    )
    subprocess.run(["bash", "./run_dp_template.sh"], env=env, check=True)


if __name__ == "__main__":
    template_path = "./run_dp_template.sh"
    if not os.path.exists(template_path):
        print(f"Template file {template_path} does not exist.")
        sys.exit(1)

    processes = []
    for i in range(dp_size_local):
        dp_rank = dp_rank_start + i
        vllm_engine_port = vllm_start_port + i
        visible_devices = ",".join(
            str(x) for x in range(i * gpus_per_dp_rank, (i + 1) * gpus_per_dp_rank)
        )
        process = multiprocessing.Process(
            target=run_command,
            args=(visible_devices, dp_rank, vllm_engine_port),
        )
        processes.append(process)
        process.start()

    for process in processes:
        process.join()

模板使用命名环境变量而非位置 shell 参数。请替换每个模板中的 <...> IP、网卡和权重路径占位符,或在启动前在 shell 中导出这些变量。下面的数值默认值描述单个引擎;launch_online_dp.py 在启动所有本地引擎时会覆盖每个 rank 的值。您无需为每个 rank 计算不同的端口或设备列表。使用启动器时,请编辑节点特定启动块中的 export DP_SIZE=...、export TP_SIZE=...、export PP_SIZE=... 及其他值;这些值优先于模板中的 ${VARIABLE:-default} 值。

变量 含义 设置方式
LOCAL_IP 当前节点的通信 IP 在每个节点上分别填写 <CURRENT_NODE_IP>。
NIC_NAME 与 LOCAL_IP 关联的网卡 填写 <CURRENT_NODE_NIC>。
MODEL_PATH / EAGLE3_WEIGHT_PATH 目标 / 草稿权重目录 在每个节点上使用相同的挂载路径。
DP_SIZE / TP_SIZE / PP_SIZE 全局 DP 大小 / 单个 rank 内的 TP 和 PP 大小 数值在下面的每个启动命令中导出。
LOCAL_DP_SIZE 当前节点上的引擎数量 作为 --dp-size-local 传递给启动器。
DP_RANK_START 此节点上的第一个全局 DP rank 作为 --dp-rank-start 传递;两个 Decode 节点之间不同。
DP_ADDRESS 此角色的 DP 协调器 IP P 使用 Prefill 的 IP;每个 D 节点使用第一个 Decode 节点的 IP。
DP_RPC_PORT DP 协调器端口 同一角色中的所有节点使用相同的值。
SERVICE_PORT 启动 shell 中的第一个本地 API 端口 启动器为每个引擎加上本地 rank 索引。
DP_RANK 引擎的全局 DP rank 启动器设置 DP_RANK_START + local_rank。
VISIBLE_DEVICES 单个引擎的 NPU ID 启动器为每个本地 rank 分配 TP_SIZE × PP_SIZE 个连续 ID。

显式指定 --data-parallel-rank 可启用外部 DP 负载均衡,vLLM 要求此时 DP_SIZE > 1。下面的模板根据实际的 DP_SIZE 构建 DP_RANK_ARGS:DP1 时省略 rank 参数,DP 大于 1 时传入启动器分配的 rank。请保留 DP_RANK 供各 rank 的连接器端口使用,DP1 时也是如此。

将 Prefill 模板保存为 P 节点上的 run_dp_template.sh,并将 Decode 模板以该名称保存到每个 D 节点上。从包含匹配模板的目录运行启动器。如果使用共享文件系统,请将 P 和 D 模板放在不同目录中。更改 TP/DP/PP 还需要更新两个角色的 --kv-transfer-config 中匹配的 prefill 和 decode 布局。

以下数值与第 5.3.1 节和第 5.3.2 节中的配置相匹配。P/D 节点数指机器数量;DP_SIZE 是该角色的全局 rank 数量。

章节 / 平台 角色 / 节点 DP_SIZE TP_SIZE PP_SIZE LOCAL_DP_SIZE DP_RANK_START 首个 SERVICE_PORT
5.3.1 A3,三节点 P 1 4 4 1 0 31050
5.3.1 A3,三节点 第一个 D 8 4 1 4 0 31260
5.3.1 A3,三节点 第二个 D 8 4 1 4 4 31260
5.3.1 950DT,两节点 P 2 4 1 2 0 31050
5.3.1 950DT,两节点 D 2 4 1 2 0 31060
5.3.1 950DT,三节点 P 2 4 1 2 0 31050
5.3.1 950DT,三节点 第一个 D 4 4 1 2 0 31060
5.3.1 950DT,三节点 第二个 D 4 4 1 2 2 31062
5.3.2 A3,三节点 P 1 4 4 1 0 31050
5.3.2 A3,三节点 第一个 D 8 4 1 4 0 31260
5.3.2 A3,三节点 第二个 D 8 4 1 4 4 31260
5.3.2 950DT,两节点 P 2 4 1 2 0 31050
5.3.2 950DT,两节点 D 2 4 1 2 0 31060

Prefill-Decode 分离部署可在 3 台 Atlas 800I A3(64GB × 24)上部署 MiniMax-M3-w8a8(W8A8),并搭配 MiniMax-M3-EAGLE3-GQA。

1. Prefill 节点

unset http_proxy https_proxy ftp_proxy

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-1}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-4}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-$LOCAL_IP}"
export DP_RPC_PORT=${DP_RPC_PORT:-6884}
export SERVICE_PORT=${SERVICE_PORT:-31050}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"

export VLLM_PP_LAYER_PARTITION="16,15,15,14"
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=1024
export HCCL_IF_IP=$LOCAL_IP
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
# If Mooncake is installed in a non-standard path, set this before startup.
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME=$NIC_NAME
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

# For better prefill performance, keep max_num_batched_tokens at 8192 for input
# lengths >= 8192 tokens; for shorter inputs, set it to the input token length.
vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enforce-eager \
    --distributed-executor-backend mp \
    --served-model-name minimax-m3 \
    --enable-expert-parallel \
    --seed 1024 \
    --max-model-len 133000 \
    --max-num-seqs 32 \
    --max-num-batched-tokens 8192 \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --trust-remote-code \
    --quantization ascend \
    --gpu-memory-utilization 0.92 \
    --limit-mm-per-prompt '{"image":1,"video":0}' \
    --reasoning-parser minimax_m3 \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"weight_nz_mode":2,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MooncakeConnectorV1",
        "kv_role":"kv_producer",
        "kv_port":"36000",
        "kv_connector_extra_config":{
            "use_ascend_direct":true,
            "prefill":{"dp_size":1,"tp_size":4,"pp_size":4,"pp_layer_partition":"16,15,15,14"},
            "decode":{"dp_size":8,"tp_size":4,"pp_size":1}
        }
    }'

2. Decode 节点

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-8}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-<DECODE_COORDINATOR_IP>}"
export DP_RPC_PORT=${DP_RPC_PORT:-31422}
export SERVICE_PORT=${SERVICE_PORT:-31260}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=2048
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
# If Mooncake is installed in a non-standard path, set this before startup.
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME=$NIC_NAME
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enable-expert-parallel \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --seed 1024 \
    --served-model-name minimax-m3 \
    --reasoning-parser minimax_m3 \
    --distributed-executor-backend mp \
    --max-model-len 133000 \
    --max-num-batched-tokens 32768 \
    --trust-remote-code \
    --quantization ascend \
    --max-num-seqs 128 \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --gpu-memory-utilization 0.92 \
    --limit-mm-per-prompt '{"image":1,"video":0}' \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"weight_nz_mode":2,"enable_shared_expert_dp":true,"enable_fused_mc2":0,"enable_flashcomm1":true}' \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MooncakeConnectorV1",
        "kv_buffer_device":"npu",
        "kv_role":"kv_consumer",
        "kv_port":"36100",
        "kv_connector_extra_config":{
            "use_ascend_direct":true,
            "prefill":{"dp_size":1,"tp_size":4,"pp_size":4,"pp_layer_partition":"16,15,15,14"},
            "decode":{"dp_size":8,"tp_size":4,"pp_size":1}
        }
    }'

对于短输入负载,请参考第 9.2 节调整 --max-num-batched-tokens。 准备完成后,在每个节点上使用以下命令启动服务:

1. Prefill 节点

export PREFILL_IP="<PREFILL_NODE_IP>"
export LOCAL_IP="$PREFILL_IP"
export DP_SIZE=1
export TP_SIZE=4
export PP_SIZE=4
export LOCAL_DP_SIZE=1
export DP_RANK_START=0
export DP_ADDRESS="$PREFILL_IP"
export DP_RPC_PORT=6884
export SERVICE_PORT=31050

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

这会在端口 31050 上启动一个 Prefill API 服务器。等待其打印 Application startup complete。

2. 第一个 Decode 节点(DECODE0_IP,全局 rank 0–3)

export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export LOCAL_IP="$DECODE0_IP"
export DP_SIZE=8
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=4
export DP_RANK_START=0
export DP_ADDRESS="$DECODE0_IP"
export DP_RPC_PORT=31422
export SERVICE_PORT=31260

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

3. 第二个 Decode 节点(DECODE1_IP,全局 rank 4–7)

export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export DECODE1_IP="<SECOND_DECODE_NODE_IP>"
export LOCAL_IP="$DECODE1_IP"
export DP_SIZE=8
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=4
export DP_RANK_START=4
export DP_ADDRESS="$DECODE0_IP"
export DP_RPC_PORT=31422
export SERVICE_PORT=31260

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

请分别为每个节点在 Decode 模板中设置 LOCAL_IP 和 NIC_NAME。两个 Decode 节点均使用 DECODE0_IP 作为 DP 协调器地址。每个节点对外暴露 API 端口 31260 至 31263;请等待全部八个 DP rank 打印 Application startup complete。

要设置请求转发,请在一台能够访问所有 Prefill 和 Decode API 端口的节点上运行以下脚本。代理程序可在仓库的 examples 目录中获取:load_balance_proxy_server_example.py。对于 A3 1P1D,代理会将请求转发到一个 Prefill 节点以及跨三个节点的八个 DP rank。

export PREFILL_IP="<PREFILL_NODE_IP>"
export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export DECODE1_IP="<SECOND_DECODE_NODE_IP>"

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY

python load_balance_proxy_server_example.py \
--port 8009 \
--host $PREFILL_IP \
--prefiller-hosts \
    $PREFILL_IP \
--prefiller-ports \
    31050 \
--decoder-hosts \
    $DECODE0_IP $DECODE0_IP $DECODE0_IP $DECODE0_IP \
    $DECODE1_IP $DECODE1_IP $DECODE1_IP $DECODE1_IP \
--decoder-ports \
    31260 31261 31262 31263 31260 31261 31262 31263

随后可通过 <proxy_ip>:8009 访问服务。对于 PD 分离,请在第 7 节中使用此代理端点。

如需使用 MindIE PyMotor 替代示例代理,请按照使用 MindIE-Motor 部署 vLLM Ascend操作,并注册相同的 1 个 Prefill 和 8 个 Decode 端点。将基准测试请求发送到 Motor 推理端点。更换请求路由器无需更改上述 P/D 并行规格或调度器限制。

Prefill-Decode 分离部署可在两台 950DT 节点(96GB × 8,1P1D)上部署 MiniMax-M3-MXFP8,并搭配 MiniMax-M3-EAGLE3-GQA,且可扩展至三节点同时保持 1P1D(一个 Prefill 服务组和一个 Decode 服务组;见下文)。在 SuperPod 系统(UB 网络)上,请按下文模板导出 ASCEND_LOCAL_COMM_RES='{"version":"1.3"}';挂载 /etc/hixlep/ 则适用于通过 RoCE 连接的 950DT。示例中显式启用了 Model Runner V2。

将 PREFILL_IP 和 DECODE_IP 设置为 Prefill 和 Decode 的通信 IP。对于三节点变体,还需设置 DECODE0_IP 和 DECODE1_IP。请在每个节点的模板中分别设置 LOCAL_IP 和 NIC_NAME。

1. Prefill 节点

unset ftp_proxy https_proxy http_proxy all_proxy
unset FTP_PROXY HTTPS_PROXY HTTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_MXFP8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-2}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-$LOCAL_IP}"
export DP_RPC_PORT=${DP_RPC_PORT:-6884}
export SERVICE_PORT=${SERVICE_PORT:-31050}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

# SuperPod (UB fabric): Mooncake auto-negotiates local endpoints. On RoCE-attached
# 950DT products, mount /etc/hixlep and use ascend_local_comm_res_path instead.
export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/lib64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH
export GLOO_SOCKET_IFNAME=$NIC_NAME
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --served-model-name minimax-m3 \
    --trust-remote-code \
    --dtype bfloat16 \
    --max-num-seqs 128 \
    --max-num-batched-tokens 32768 \
    --max-model-len 133000 \
    --enable-expert-parallel \
    --quantization mxfp8 \
    --gpu-memory-utilization 0.92 \
    --distributed-executor-backend mp \
    --kv-cache-dtype fp8 \
    --reasoning-parser minimax_m3 \
    --safetensors-load-strategy prefetch \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3, "kv_cache_dtype":"bfloat16"}' \
    --enforce-eager \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_qknorm_rope":true,"fuse_norm_quant":true},"multistream_overlap_shared_expert":true,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MooncakeConnectorV1",
        "kv_role":"kv_producer",
        "kv_port":"30000",
        "kv_connector_extra_config":{
            "use_ascend_direct":true,
            "prefill":{"dp_size":2,"tp_size":4,"pp_size":1},
            "decode":{"dp_size":2,"tp_size":4,"pp_size":1}
        }
    }'

2. Decode 节点

unset ftp_proxy https_proxy http_proxy all_proxy
unset FTP_PROXY HTTPS_PROXY HTTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_MXFP8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-2}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-<DECODE_COORDINATOR_IP>}"
export DP_RPC_PORT=${DP_RPC_PORT:-5964}
export SERVICE_PORT=${SERVICE_PORT:-31060}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

# SuperPod (UB fabric): Mooncake auto-negotiates local endpoints. On RoCE-attached
# 950DT products, mount /etc/hixlep and use ascend_local_comm_res_path instead.
export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=2048
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/lib64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH
export GLOO_SOCKET_IFNAME=$NIC_NAME
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enable-expert-parallel \
    --seed 1024 \
    --served-model-name minimax-m3 \
    --reasoning-parser minimax_m3 \
    --safetensors-load-strategy prefetch \
    --distributed-executor-backend mp \
    --max-model-len 133000 \
    --max-num-batched-tokens 32768 \
    --trust-remote-code \
    --max-num-seqs 256 \
    --gpu-memory-utilization 0.92 \
    --dtype bfloat16 \
    --quantization mxfp8 \
    --kv-cache-dtype fp8 \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3, "kv_cache_dtype":"bfloat16"}' \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MooncakeConnectorV1",
        "kv_role":"kv_consumer",
        "kv_port":"26900",
        "kv_connector_extra_config":{
            "use_ascend_direct":true,
            "prefill":{"dp_size":2,"tp_size":4,"pp_size":1},
            "decode":{"dp_size":2,"tp_size":4,"pp_size":1}
        }
    }'

准备完成后,在每个节点上使用以下命令启动服务:

1. Prefill 节点

export PREFILL_IP="<PREFILL_NODE_IP>"
export LOCAL_IP="$PREFILL_IP"
export DP_SIZE=2
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=0
export DP_ADDRESS="$PREFILL_IP"
export DP_RPC_PORT=6884
export SERVICE_PORT=31050

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

这将在端口 31050 和 31051 上启动两个 Prefill API 服务。等待两个 rank 均打印 Application startup complete。

2. Decode 节点

export DECODE_IP="<DECODE_NODE_IP>"
export LOCAL_IP="$DECODE_IP"
export DP_SIZE=2
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=0
export DP_ADDRESS="$DECODE_IP"
export DP_RPC_PORT=5964
export SERVICE_PORT=31060

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

这将在端口 31060 和 31061 上启动两个 Decode API 服务。

要设置请求转发,请在一台能够访问所有 Prefill 和 Decode API 端口的节点上运行以下脚本。代理程序可在仓库的 examples 目录中获取:load_balance_proxy_server_example.py。对于 950DT 产品 1P1D,代理会将请求转发到 2 个 Prefill rank 和 2 个 DP rank。

export PREFILL_IP="<PREFILL_NODE_IP>"
export DECODE_IP="<DECODE_NODE_IP>"

unset ftp_proxy
unset https_proxy
unset http_proxy

python load_balance_proxy_server_example.py \
--port 8009 \
--host $PREFILL_IP \
--prefiller-hosts \
    $PREFILL_IP $PREFILL_IP \
--prefiller-ports \
    31050 31051 \
--decoder-hosts \
    $DECODE_IP $DECODE_IP \
--decoder-ports \
    31060 31061

随后可通过 <proxy_ip>:8009 访问服务。对于 PD 分离,请在第 7 节中使用此代理端点。

扩展至三节点(仍为 1P1D)

上述部署可扩展至三节点:一个 Prefill 节点(DP2 × TP4)加上两个 Decode 节点组成一个全局 DP4 组(每个 Decode 节点有两个本地 DP rank,各为 TP4;共 24 个 NPU)。只需修改一处模板:在 Prefill 和 Decode 的 run_dp_template.sh 两者中,更新 Mooncake 额外配置以描述新的 Decode 组 —— "decode":{"dp_size":4,"tp_size":4,"pp_size":1}(Prefill 保持 dp_size: 2)。同时将每个节点模板中的 LOCAL_IP 设置为该节点的计算网络 IP。

完全按照两节点示例启动 Prefill 节点。然后启动第一个 Decode 节点(DECODE0_IP,全局 DP rank 0–1),该节点同时充当 DP 组主节点:

export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export LOCAL_IP="$DECODE0_IP"
export DP_SIZE=4
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=0
export DP_ADDRESS="$DECODE0_IP"
export DP_RPC_PORT=5964
export SERVICE_PORT=31060

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

等待 rank 0 打印 Started DP Coordinator process。在另一个 shell 中,启动第二个 Decode 节点(DECODE1_IP,全局 DP rank 2–3),该节点将加入同一个 DP 组:

export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export DECODE1_IP="<SECOND_DECODE_NODE_IP>"
export LOCAL_IP="$DECODE1_IP"
export DP_SIZE=4
export TP_SIZE=4
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=2
export DP_ADDRESS="$DECODE0_IP"
export DP_RPC_PORT=5964
export SERVICE_PORT=31062

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

第一个 Decode 节点提供 API 端口 31060/31061,第二个提供 31062/31063。请等待全部四个 DP rank 打印 Application startup complete。模板基础 kv_port(26900)可以在两个 Decode 节点上保持一致。请确保全局 DP rank 互不相同(0–1 和 2–3);Mooncake 使用全局 DP rank 偏移量推导握手端口。请在所有六个引擎启动完成后再启动代理(示例代理对每个后端只等待几秒),并注册两个 Prefill rank 和四个 DP rank:

export PREFILL_IP="<PREFILL_NODE_IP>"
export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export DECODE1_IP="<SECOND_DECODE_NODE_IP>"

python load_balance_proxy_server_example.py \
--port 8009 \
--host $PREFILL_IP \
--prefiller-hosts \
    $PREFILL_IP $PREFILL_IP \
--prefiller-ports \
    31050 31051 \
--decoder-hosts \
    $DECODE0_IP $DECODE0_IP $DECODE1_IP $DECODE1_IP \
--decoder-ports \
    31060 31061 31062 31063

在贡献者验证的纯文本运行中,使用此三节点布局并启用 MXFP8、EAGLE3、fp8 KV cache 以及可选的 --language-model-only 标志,全部 232 个请求在 128k 输入 / 1k 输出、并发 58 的情况下均成功完成。平均 TPOT 为 27.3 ms,总输出吞吐量约为 1840 tokens/s。在该设置中,启用 Decode FlashComm1 将输出吞吐量从 1807.9 提升至 1840.7 tokens/s(约 1.8%)。这些测量结果描述的是该工作负载和配置;启动模板将 --language-model-only 保留为可选。

关键参数说明:

launch_online_dp.py 参数:

参数 类型 是否必填 默认值 说明
--dp-size int 是 - 数据并行大小(所有节点上 DP rank 的总数)。
--tp-size int 否 1 每个 DP rank 内的张量并行大小。
--pp-size int 否 1 每个 DP rank 内的流水线并行大小。每个 rank 占用 tp_size * pp_size 个 NPU。
--dp-size-local int 否 (与 --dp-size 相同) 当前节点上的 DP rank 数量。
--dp-rank-start int 否 0 此节点上数据并行 rank 的起始 rank 偏移量。
--dp-address str 是 - 数据并行主节点的 IP 地址。
--dp-rpc-port str 否 12321 数据并行主节点通信的 RPC 端口。
--vllm-start-port int 否 8000 此节点上每个 vLLM 引擎实例的起始端口。每个 DP rank 的引擎端口 = vllm_start_port + 本地 rank 索引。

Prefill 节点专属配置:

  • --language-model-only(可选):对于纯文本测试,可根据可用 KV cache 容量按需添加此标志,以避免为多模态处理预留内存。此标志可与 FLASHCOMM1 一起用于纯文本服务。
  • --pipeline-parallel-size(A3 Prefill:4):将 60 层 MiniMax-M3 拆分到四个流水线阶段。A3 设置 VLLM_PP_LAYER_PARTITION=16,15,15,14,并将 pp_layer_partition 写入 Mooncake 额外配置。使用 TP=4 时,使用 DP=1 可将全部四个阶段放在一个 16-NPU 节点上。Ascend 950DT系列产品启动时在 Prefill 和 Decode 上均使用 --pp-size 1(无流水线并行),因此无需层分区。
  • --max-num-batched-tokens(A3 Prefill:8192):为获得更好的 prefill 性能,当输入长度至少为 8192 个 token 时使用 8192;对于更短的输入,将其设置为输入 token 长度。此建议同样适用于第 5.3.2 节中使用 KV Cache Pool 的 A3 Prefill。
  • --enforce-eager:Prefill 节点保留 eager 执行,不进行图捕获。
  • --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}':普通上下文 Decode 示例和第 5.4.1 节中的单节点示例对仅 decode 批次使用完整图捕获。第 5.4.2 节对其 1M 上下文 PD 布局使用 eager 执行。
  • --speculative-config '{"method":"eagle3", ...}':启用 MiniMax-M3-EAGLE3-GQA 草稿模型。

Decode 节点专属配置:

  • --language-model-only(可选):对于纯文本测试,根据可用的 KV cache 容量按需添加此标志,以避免为多模态处理预留内存。
  • "max_cudagraph_capture_size"(可选,默认省略):限制 ACL 图捕获所覆盖的最大解码批次大小以及为其预留的图内存;程序默认值为 512。使用 EAGLE3 投机解码时,每个请求在一个解码步骤中扩展为 1 + num_speculative_tokens 个 tokens(当 num_speculative_tokens=3 时为 4 个 tokens)。由于 DP 按 rank 分发请求,每个 rank 的批次大小很重要:例如,使用 DP2 和 --max-num-seqs 256 时,每个 DP rank 处理 128 个请求,每步产生 4 × 128 = 512 个 tokens——恰好处于默认限制。如果并发升至 257,一个 DP rank 处理 129 个请求,得到 4 × 129 = 516 > 512;超过 512 的批次会跳过图捕获并回退到 eager 执行,从而降低解码吞吐量。在这种情况下,在 --compilation-config 中设置 "max_cudagraph_capture_size":1024(例如 --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY","max_cudagraph_capture_size":1024}')。由于更大的捕获大小会预留额外的 NPU 内存,本教程中的配置保持默认值;仅当目标并发需要时才添加此选项。
  • --max-num-seqs 256:经验证的 Ascend 950DT系列产品 1P1D 启动所使用的 Decode 并发数。A3 使用 128。

Mooncake KV 传输配置(--kv-transfer-config):

  • "kv_connector": "MooncakeConnectorV1":使用 Mooncake 作为 prefill 和 decode 节点之间的 KV cache 传输连接器。
  • "kv_role": "kv_producer" / "kv_consumer":prefill 节点上为 kv_producer,decode 节点上为 kv_consumer。
  • "kv_port":Mooncake KV 传输端口。prefill 和 decode 使用不同的端口。经验证的值是 A3 为 36000/36100,Ascend 950DT系列产品为 30000/26900。
  • "use_ascend_direct": true:为 KV cache 启用昇腾直接传输。
  • "ascend_local_comm_res_path": "/etc/hixlep"(仅 Ascend 950DT系列产品):用于挂载了 /etc/hixlep/ 的 RoCE 连接的 950DT。在 SuperPod UB 网络上,省略此选项并改为导出 ASCEND_LOCAL_COMM_RES='{"version":"1.3"}',如第 5.3.1 节模板所示。第 5.3.2 节的 950DT KV-pool 模板保留了静态路径设置;使用 UB 网络时,以相同方式调整 MultiConnector 内的 Mooncake 连接器。
  • "prefill" / "decode" 部分:dp_size、tp_size 和 pp_size 必须与每个节点上的实际全局布局匹配。A3 在一个节点上使用 prefill: dp1 tp4 pp4,在两个节点上使用 decode: dp8 tp4 pp1(每个 Decode 节点有四个本地 DP rank)。Ascend 950DT系列产品在两个节点上使用 prefill: dp2 tp4 pp1 和 decode: dp2 tp4 pp1,或在三个节点上使用 decode: dp4 tp4 pp1。

请求转发(代理):

  • 在启动代理之前,等待 Prefill 节点和 DP rank 打印 Application startup complete。
  • 代理将每个 prefill 引擎端点和每个 decode 引擎端点映射到端口 8009 上的单一入口点。
  • 如果请求到达代理但没有返回输出,请检查代理主机列表是否包含每个健康的 Prefill 节点和 DP rank,以及所有节点在之前的运行后是否仍有空闲的 NPU 内存。

关于上述环境变量的进一步说明和限制,请参阅 envs.py。

5.3.2 使用 KV Cache Pool 的 Prefill-Decode 分离

本节建立在第 5.3.1 节的基础上。A3 示例使用与第 5.3.1 节相同的三节点 1P1D 拓扑、launch_online_dp.py、代理映射和 MiniMax vllm serve 设置(一个 P 节点加两个 D 节点)。950DT pool 示例保留其两节点 1P1D 拓扑。Prefill 和 Decode 切换到 MultiConnector,以便实时 P→D KV 传输和 Mooncake KV Cache Pool 协同工作:

  • MooncakeConnectorV1 将 KV 从 Prefill 实时传输到 Decode(与 5.3.1 节中的作用相同)。
  • AscendStoreConnector 将 KV 存储到 Mooncake KV Cache Pool 中,使后续具有相同前缀的 Prefill 可以命中该池而无需重新计算。
  • 默认情况下,Prefill 节点执行池查找、加载和写入。

以下示例启用三层 KV 存储:活跃的 NPU KV 缓存、Mooncake 内存池以及 SSD 卸载。

有关后端选择、mooncake.json、Mooncake Master、驱逐、租户选项以及特定硬件的池化导出,请参阅 KV Cache Pool 部署指南。有关 MiniMax 特定问题,请参阅第 10 章 FAQ。

与 5.3.1 节中的普通 PD 相比,请特别注意以下仅池化模式才有的要求:

项目 普通 PD(5.3.1) 池化 PD(本节)
连接器 单一 MooncakeConnectorV1 MultiConnector 包装 MooncakeConnectorV1 + AscendStoreConnector
Mooncake Master 不需要 在启动 Decode / Prefill 之前启动 mooncake_master --enable_offload=true
mooncake.json 不需要 每个 rank 都需要;A3 的 P 和两个 D 节点使用 15GB;950DT 的 P 和 D 使用 64GB;在所有节点上启用 SSD 卸载
lookup_rpc_port 未使用 每个 DP rank 必须唯一(37000/37100 + DP_RANK),以避免 IPC 端点冲突
额外环境变量 仅 5.3.1 节的 HCCL_* 保留 5.3.1 节的环境变量,然后从 KV Cache Pool 部署指南 中添加池化 fabric/UB 相关导出
容器挂载 950DT 需要 /etc/hixlep/ 还需挂载 /etc/hccn.conf 和本地 SSD 卸载目录;在 950DT 上保留 /etc/hixlep/
启动顺序 Decode → Prefill → Proxy Mooncake Master → Decode → Prefill → Proxy
验证 仅 P→D KV 传输 还需在重复前缀预热后检查 Prefill 池的 lookup/get/put 命中情况
5.3.2.1 前提条件

将主机 HCCN 配置挂载到每个参与池化的容器中:

-v /etc/hccn.conf:/etc/hccn.conf:ro

在 Ascend 950DT系列产品上,还需保留 5.3.1 节中的 /etc/hixlep/ 挂载,用于昇腾直接 KV 传输。

在每个 Prefill 和 Decode 主机上使用本地 SSD 目录来存储从内存池卸载的 KV cache 数据。/nvme/mooncake_offload 是容器内的示例目录,并非必需的 SSD 挂载点,也不是每台主机上都已存在的目录。

在每台主机上,首先识别本地 SSD 及其挂载点:

lsblk -o NAME,TYPE,SIZE,ROTA,FSTYPE,MOUNTPOINTS,MODEL
df -hT

使用 MODEL 识别 SSD,使用 MOUNTPOINTS 查找其挂载的文件系统。ROTA=0 表示非旋转设备;请通过机器的磁盘信息确认存储类型,尤其是 RAID 或虚拟磁盘。选择一个已存在且具有足够可用空间的本地 SSD 文件系统。共享网络文件系统不属于本地 SSD 层级。

例如,如果 SSD 挂载在 /data/nvme,请在启动容器前在该处创建卸载目录。将下面的 /data/nvme 替换为实际的 SSD 挂载点:

mkdir -p /data/nvme/mooncake_offload
findmnt -T /data/nvme/mooncake_offload
df -hT /data/nvme/mooncake_offload

确认 findmnt 报告的是所选 SSD 文件系统,并且 df 显示有足够的可用空间。仅创建一个名为 /nvme 的目录并不会挂载 SSD,也不能确保数据存储在其上。

在创建每个模型容器时添加此绑定挂载:

-v /data/nvme/mooncake_offload:/nvme/mooncake_offload

左侧是该主机 SSD 上的目录;右侧是容器内可见的目录。使用此映射时,请在 mooncake.json 中保留 "ssd_offload_path": "/nvme/mooncake_offload"。如果容器路径发生变化,请更新 ssd_offload_path 以保持一致。请使用存在且 vLLM 进程可写的绝对路径;不要使用符号链接。在 P 和每个 D 主机上重复此设置:相同的路径字符串在每台主机上指向各自独立的本地 SSD 存储。后端会在其下创建各 rank 的子目录。已安装的 Mooncake 包必须支持 MooncakeDistributedStore.setup() 中的 enable_ssd_offload 和 ssd_offload_path 参数;请使用 KV Cache Pool 部署指南 中的依赖项。

在每个节点上将 mooncake.json 放在 run_dp_template.sh 旁边。在 P 和 D 上使用相同的可达 Mooncake Master 地址和 tenant_id。global_segment_size 按 worker rank 分配,而不是按节点分配;非零值必须按 1GB 对齐。如果已导出 MOONCAKE_GLOBAL_SEGMENT_SIZE,请将其更新为预期大小,或在启动前取消设置,因为它会覆盖 JSON 中的值。

A3 上 P、第一个 D 和第二个 D 的 mooncake.json(将 <MOONCAKE_MASTER_IP> 替换为实际的 Master IP):

{
  "metadata_server": "P2PHANDSHAKE",
  "protocol": "ascend",
  "device_name": "",
  "master_server_address": "<MOONCAKE_MASTER_IP>:50088",
  "global_segment_size": "15GB",
  "preferred_segment": false,
  "prefer_alloc_in_same_node": true,
  "enable_ssd_offload": true,
  "ssd_offload_path": "/nvme/mooncake_offload",
  "tenant_id": "default"
}

A3 示例在 P 和两个 D 节点上为每个 worker rank 使用 15GB。在为 vLLM 和其他进程预留内存后,请根据每台机器的可用可分配内存和碎片情况调整此值。为 SSD I/O 缓冲区和分配余量预留额外空间,并考虑节点上所有参与贡献的 worker rank。

950DT Prefill 的 mooncake.json(替换 <MOONCAKE_MASTER_IP>):

{
  "metadata_server": "P2PHANDSHAKE",
  "protocol": "ascend",
  "device_name": "",
  "master_server_address": "<MOONCAKE_MASTER_IP>:50088",
  "global_segment_size": "64GB",
  "preferred_segment": false,
  "prefer_alloc_in_same_node": true,
  "enable_ssd_offload": true,
  "ssd_offload_path": "/nvme/mooncake_offload",
  "tenant_id": "default"
}

950DT Decode 的 mooncake.json(相同的 Master 和 tenant_id;P 和 D 均贡献内存并启用 SSD 卸载):

{
  "metadata_server": "P2PHANDSHAKE",
  "protocol": "ascend",
  "device_name": "",
  "master_server_address": "<MOONCAKE_MASTER_IP>:50088",
  "global_segment_size": "64GB",
  "preferred_segment": true,
  "prefer_alloc_in_same_node": true,
  "enable_ssd_offload": true,
  "ssd_offload_path": "/nvme/mooncake_offload",
  "tenant_id": "default"
}

950DT 示例在 P 和 D 上为每个 worker rank 使用 64GB。请根据每台机器的实际可用内存和碎片情况调整大小,而不要将 64GB 视为固定要求。为节点上的所有 worker rank、SSD I/O 缓冲区和其他分配预留预算;如果机器无法注册所请求的内存,请减小 segment 大小。

5.3.2.2 环境变量

从第 5.3.1 节的环境配置块开始(HCCL_IF_IP、HCCL/GLOO socket IFNAME、HCCL_BUFFSIZE、PYTORCH_NPU_ALLOC_CONF、ASCEND_RT_VISIBLE_DEVICES 以及 A3 Prefill 的 VLLM_PP_LAYER_PARTITION="16,15,15,14")。然后添加下面池化所需的变量。根据您的机器和链路类型,从 Mooncake 后端启动示例中选择硬件/通信导出项。

Prefill 节点和 DP rank 上常用的池化导出:

# Optional: only if Mooncake is installed in a non-standard path (same as Section 5.3.1).
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export MOONCAKE_CONFIG_PATH=./mooncake.json
export PYTHONHASHSEED=0
# SSD I/O buffer per worker: 1GB, aligned for A3 fabric memory.
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824
# SSD disk budget per NPU worker rank: 10 GiB.
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru

SSD I/O 缓冲区与 global_segment_size 分开分配。上面的 1GB 值是一个对齐的起始值;请根据 KV 读写批次确定其大小,并将其计入每个 rank 的内存预算。

对于此三层(NPU、主机内存和 SSD)示例,建议在每个 Prefill 和 Decode 节点上为每个 NPU worker rank 预留 10 GiB 的 SSD 起始预算。这两个容量限制描述的是同一份 SSD 预算;它们不会累加为 20 GiB:

  • MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES 设置向 Mooncake Master 报告的每个 worker 的 SSD 容量。其默认值为每个 worker 2199023255552 字节(2 TiB);这是对外通告的容量,并非立即分配的磁盘空间。
  • MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE 设置本地 bucket 大小限制。其默认值为 0,表示物理磁盘容量的 90%。请与通告容量一起显式设置。
  • MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru 启用最近最少使用驱逐策略,在配置的 bucket 限制内移除旧的 SSD 缓存条目,为新写入腾出空间。

请根据工作负载和可用 SSD 空间调整这两个值,需考虑共享该磁盘的所有 worker,并为其他数据留出空间。请按 TP 和 PP 的 worker rank 数量计算,而不仅仅是 DP rank 或物理卡数量:一台拥有 16 个逻辑 NPU worker 的 A3 节点,按每个 worker 10 GiB 计算,合计预算为 160 GiB。这些限制控制 SSD 使用量;它们不会改变主机内存池或 SSD I/O 缓冲区大小。详情请参见 Mooncake SSD Offload 参数调优。

硬件 依赖项 所需的池化导出 说明
800I/T A3(HCCS,推荐) HDK >= 26.0,或 HDK >= 25.5 且 mooncake >= v0.3.11;CANN >= 9.0.0 export ASCEND_ENABLE_USE_FABRIC_MEM=1 保留 5.3.1 节的 HCCL_IF_IP / socket IFNAME 导出。
800I/T A3(RoCE)或 800I/T A2 A2:推荐 HDK >= 25.5 export HCCL_INTRA_ROCE_ENABLE=1,加上 HCCL_IF_IP / socket IFNAME,以及 nr_hugepages=200000 使用 KV Cache 池指南中的 RoCE 路径。
950PR/DT(Device UB) HDK >= 25.6 且 mooncake >= v0.3.11;CANN >= 9.1.0 export ASCEND_LOCAL_COMM_RES_PATH=/etc/hixlep/ 和 export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}';unset ASCEND_GLOBAL_RESOURCE_CONFIG 挂载 /etc/hixlep/。若使用 UBOE,请按 KV Cache 池指南中的说明使用 ASCEND_GLOBAL_RESOURCE_CONFIG。
5.3.2.3 Prefill / Decode 脚本

复用 5.3.1 节的 launch_online_dp.py。将每个角色的 run_dp_template.sh 替换为下方的池化版本。保持 5.3.1 节的 vllm serve 参数风格;仅将 --kv-transfer-config 切换为 MultiConnector。根据 DP_RANK 推导 lookup_rpc_port,使每个 rank 使用不同的 IPC 端点。

在 3 台 Atlas 800I A3(64GB × 16)上,使用 KV Cache Pool 为 MiniMax-M3-w8a8(W8A8)配合 MiniMax-M3-EAGLE3-GQA 进行 Prefill-Decode 分离部署。

一个 Prefill 节点使用 DP1 × TP4 × PP4;两个 Decode 节点组成全局 DP8 × TP4 × PP1 组,每个节点有四个本地 rank。将相同的 Decode 模板复制到两个 D 节点,并使用下方针对各节点的启动配置块。服务设置与第 5.3.1 节一致;MultiConnector 增加了 KV 池。--language-model-only 选项仍保留在现有的可选指导中,而不在启动命令中。

1. Prefill 节点

unset http_proxy https_proxy ftp_proxy

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-1}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-4}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-$LOCAL_IP}"
export DP_RPC_PORT=${DP_RPC_PORT:-6884}
export SERVICE_PORT=${SERVICE_PORT:-31050}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"

# Pooling extras: all three A3 nodes use the 15GB mooncake.json in Section 5.3.2.1.
export VLLM_PP_LAYER_PARTITION="16,15,15,14"
export VLLM_SERVER_DEV_MODE=1
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=1024
export HCCL_IF_IP=$LOCAL_IP
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_ENABLE_USE_FABRIC_MEM=1
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
# If Mooncake is installed in a non-standard path, set this before startup.
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME=$NIC_NAME
export MOONCAKE_CONFIG_PATH=./mooncake.json
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export PYTHONHASHSEED=0
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824
# SSD disk budget per NPU worker rank: 10 GiB.
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

# For better prefill performance, keep max_num_batched_tokens at 8192 for input
# lengths >= 8192 tokens; for shorter inputs, set it to the input token length.
vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enforce-eager \
    --distributed-executor-backend mp \
    --served-model-name minimax-m3 \
    --enable-expert-parallel \
    --seed 1024 \
    --max-model-len 133000 \
    --max-num-seqs 32 \
    --max-num-batched-tokens 8192 \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --trust-remote-code \
    --quantization ascend \
    --gpu-memory-utilization 0.92 \
    --limit-mm-per-prompt '{"image":1,"video":0}' \
    --reasoning-parser minimax_m3 \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"weight_nz_mode":2,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MultiConnector",
        "kv_role":"kv_producer",
        "kv_connector_extra_config":{
            "connectors":[
                {
                    "kv_connector":"MooncakeConnectorV1",
                    "kv_buffer_device":"npu",
                    "kv_role":"kv_producer",
                    "kv_port":"36000",
                    "kv_connector_extra_config":{
                        "use_ascend_direct":true,
                        "prefill":{"dp_size":1,"tp_size":4,"pp_size":4,"pp_layer_partition":"16,15,15,14"},
                        "decode":{"dp_size":8,"tp_size":4,"pp_size":1}
                    }
                },
                {
                    "kv_connector":"AscendStoreConnector",
                    "kv_role":"kv_producer",
                    "kv_connector_extra_config":{
                        "backend":"mooncake",
                        "lookup_rpc_port":'$((37000 + $DP_RANK))'
                    }
                }
            ]
        }
    }'

2. Decode 节点

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-8}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-<DECODE_COORDINATOR_IP>}"
export DP_RPC_PORT=${DP_RPC_PORT:-31422}
export SERVICE_PORT=${SERVICE_PORT:-31260}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

# Pooling extras: all three A3 nodes use the 15GB mooncake.json in Section 5.3.2.1.
export VLLM_SERVER_DEV_MODE=1
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=2048
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_ENABLE_USE_FABRIC_MEM=1
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
# If Mooncake is installed in a non-standard path, set this before startup.
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME=$NIC_NAME
export MOONCAKE_CONFIG_PATH=./mooncake.json
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export PYTHONHASHSEED=0
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824
# SSD disk budget per NPU worker rank: 10 GiB.
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enable-expert-parallel \
    --enable-chunked-prefill \
    --enable-prefix-caching \
    --seed 1024 \
    --served-model-name minimax-m3 \
    --reasoning-parser minimax_m3 \
    --distributed-executor-backend mp \
    --max-model-len 133000 \
    --max-num-batched-tokens 32768 \
    --trust-remote-code \
    --quantization ascend \
    --max-num-seqs 128 \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --gpu-memory-utilization 0.92 \
    --limit-mm-per-prompt '{"image":1,"video":0}' \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"weight_nz_mode":2,"enable_shared_expert_dp":true,"enable_fused_mc2":0,"enable_flashcomm1":true}' \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MultiConnector",
        "kv_role":"kv_consumer",
        "kv_connector_extra_config":{
            "connectors":[
                {
                    "kv_connector":"MooncakeConnectorV1",
                    "kv_buffer_device":"npu",
                    "kv_role":"kv_consumer",
                    "kv_port":"36100",
                    "kv_connector_extra_config":{
                        "use_ascend_direct":true,
                        "prefill":{"dp_size":1,"tp_size":4,"pp_size":4,"pp_layer_partition":"16,15,15,14"},
                        "decode":{"dp_size":8,"tp_size":4,"pp_size":1}
                    }
                },
                {
                    "kv_connector":"AscendStoreConnector",
                    "kv_role":"kv_consumer",
                    "kv_connector_extra_config":{
                        "backend":"mooncake",
                        "lookup_rpc_port":'$((37100 + $DP_RANK))'
                    }
                }
            ]
        }
    }'

A3 上的启动顺序:Mooncake Master → 两个 Decode 节点 → Prefill → Proxy。使用第 5.3.2.4 节中的三节点命令,DP/TP/PP 大小和 API 端口与第 5.3.1 节 A3 一致。在启动 proxy 之前,单个 P API 和全部八个 D API 必须处于健康状态。

在 2 台 Ascend 950DT系列产品(96GB × 8)上为 MiniMax-M3-MXFP8 搭配 MiniMax-M3-EAGLE3-GQA 使用 KV Cache Pool 进行 Prefill-Decode 分离部署。挂载 /etc/hixlep/、/etc/hccn.conf 以及第 5.3.2.1 节中的本地 SSD 目录。将第 5.3.2.1 节中的 Prefill / Decode mooncake.json 放到 run_dp_template.sh 旁边(两个角色的 global_segment_size 均为 64GB,并启用 SSD 卸载)。在两个节点上将 master_server_address 设置为同一个可访问的 Mooncake Master。

1. Prefill 节点

unset ftp_proxy https_proxy http_proxy all_proxy
unset FTP_PROXY HTTPS_PROXY HTTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_MXFP8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-2}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-$LOCAL_IP}"
export DP_RPC_PORT=${DP_RPC_PORT:-6884}
export SERVICE_PORT=${SERVICE_PORT:-31050}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

# Runtime environment and pooling extras (Device UB).
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/lib64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH
export GLOO_SOCKET_IFNAME=$NIC_NAME
export MOONCAKE_CONFIG_PATH=./mooncake.json
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export PYTHONHASHSEED=0
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824
# SSD disk budget per NPU worker rank: 10 GiB.
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru
export ASCEND_LOCAL_COMM_RES_PATH=/etc/hixlep/
export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
unset ASCEND_GLOBAL_RESOURCE_CONFIG

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
  --host 0.0.0.0 \
  --port "$SERVICE_PORT" \
  --data-parallel-size "$DP_SIZE" \
  "${DP_RANK_ARGS[@]}" \
  --data-parallel-address "$DP_ADDRESS" \
  --data-parallel-rpc-port "$DP_RPC_PORT" \
  --tensor-parallel-size "$TP_SIZE" \
  --pipeline-parallel-size "$PP_SIZE" \
  --served-model-name minimax-m3 \
  --trust-remote-code \
  --dtype bfloat16 \
  --max-num-seqs 128 \
  --max-num-batched-tokens 32768 \
  --max-model-len 133000 \
  --enable-expert-parallel \
  --quantization mxfp8 \
  --gpu-memory-utilization 0.92 \
  --distributed-executor-backend mp \
  --kv-cache-dtype fp8 \
  --reasoning-parser minimax_m3 \
  --safetensors-load-strategy prefetch \
  --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3, "kv_cache_dtype":"bfloat16"}' \
  --enforce-eager \
  --enable-chunked-prefill \
  --enable-prefix-caching \
  --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_qknorm_rope":true,"fuse_norm_quant":true},"multistream_overlap_shared_expert":true,"enable_shared_expert_dp":true,"enable_flashcomm1":true}' \
  --kv-transfer-config \
  '{
      "kv_connector":"MultiConnector",
      "kv_role":"kv_producer",
      "kv_connector_extra_config":{
          "connectors":[
              {
                  "kv_connector":"MooncakeConnectorV1",
                  "kv_buffer_device":"npu",
                  "kv_role":"kv_producer",
                  "kv_port":"30000",
                  "kv_connector_extra_config":{
                      "use_ascend_direct":true,
                      "ascend_local_comm_res_path":"/etc/hixlep",
                      "prefill":{"dp_size":2,"tp_size":4,"pp_size":1},
                      "decode":{"dp_size":2,"tp_size":4,"pp_size":1}
                  }
              },
              {
                  "kv_connector":"AscendStoreConnector",
                  "kv_role":"kv_producer",
                  "kv_connector_extra_config":{
                      "backend":"mooncake",
                      "lookup_rpc_port":'$((37000 + $DP_RANK))'
                  }
              }
          ]
      }
  }'

2. Decode 节点

unset ftp_proxy https_proxy http_proxy all_proxy
unset FTP_PROXY HTTPS_PROXY HTTP_PROXY ALL_PROXY

# Replace IP, NIC and weight-path placeholders for this node.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_MXFP8_PATH>}"
export EAGLE3_WEIGHT_PATH="${EAGLE3_WEIGHT_PATH:-<MINIMAX_M3_EAGLE3_GQA_PATH>}"

# Role defaults; the launcher overrides these for each engine.
export DP_SIZE=${DP_SIZE:-2}
export TP_SIZE=${TP_SIZE:-4}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-<DECODE_COORDINATOR_IP>}"
export DP_RPC_PORT=${DP_RPC_PORT:-5964}
export SERVICE_PORT=${SERVICE_PORT:-31060}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3}"

# Runtime environment and pooling extras (Device UB).
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=2048
export HCCL_IF_IP=$LOCAL_IP
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME=$NIC_NAME
export ASCEND_RT_VISIBLE_DEVICES=$VISIBLE_DEVICES
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/lib64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH
export GLOO_SOCKET_IFNAME=$NIC_NAME
export MOONCAKE_CONFIG_PATH=./mooncake.json
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export PYTHONHASHSEED=0
export MOONCAKE_OFFLOAD_LOCAL_BUFFER_SIZE_BYTES=1073741824
# SSD disk budget per NPU worker rank: 10 GiB.
export MOONCAKE_OFFLOAD_TOTAL_SIZE_LIMIT_BYTES=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_MAX_TOTAL_SIZE=$((10 * 1024 * 1024 * 1024))
export MOONCAKE_OFFLOAD_BUCKET_EVICTION_POLICY=lru
export ASCEND_LOCAL_COMM_RES_PATH=/etc/hixlep/
export ASCEND_LOCAL_COMM_RES='{"version":"1.3"}'
unset ASCEND_GLOBAL_RESOURCE_CONFIG

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --enable-expert-parallel \
    --seed 1024 \
    --served-model-name minimax-m3 \
    --reasoning-parser minimax_m3 \
    --safetensors-load-strategy prefetch \
    --distributed-executor-backend mp \
    --max-model-len 133000 \
    --max-num-batched-tokens 32768 \
    --trust-remote-code \
    --max-num-seqs 256 \
    --gpu-memory-utilization 0.92 \
    --dtype bfloat16 \
    --quantization mxfp8 \
    --kv-cache-dtype fp8 \
    --speculative-config '{"model":"'"${EAGLE3_WEIGHT_PATH}"'", "method":"eagle3", "num_speculative_tokens":3, "kv_cache_dtype":"bfloat16"}' \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"enable_shared_expert_dp":true}' \
    --kv-transfer-config \
    '{
        "kv_connector":"MultiConnector",
        "kv_role":"kv_consumer",
        "kv_connector_extra_config":{
            "connectors":[
                {
                    "kv_connector":"MooncakeConnectorV1",
                    "kv_buffer_device":"npu",
                    "kv_role":"kv_consumer",
                    "kv_port":"26900",
                    "kv_connector_extra_config":{
                        "use_ascend_direct":true,
                        "ascend_local_comm_res_path":"/etc/hixlep",
                        "prefill":{"dp_size":2,"tp_size":4,"pp_size":1},
                        "decode":{"dp_size":2,"tp_size":4,"pp_size":1}
                    }
                },
                {
                    "kv_connector":"AscendStoreConnector",
                    "kv_role":"kv_consumer",
                    "kv_connector_extra_config":{
                        "backend":"mooncake",
                        "lookup_rpc_port":'$((37100 + $DP_RANK))'
                    }
                }
            ]
        }
    }'

950DT 上的启动顺序:Mooncake Master → Decode → Prefill → Proxy。使用第 5.3.1 节 950DT 双节点命令(两个角色均为 DP2,proxy 监听 8009),并配合上述池化模板;此双节点示例不要使用三节点扩展命令。

5.3.2.4 启动服务

按以下顺序启动:

Mooncake Master
    ↓
First Decode node → Second Decode node (A3 only)
    ↓
Prefill
    ↓
Proxy (:8009)
  1. 在 Prefill 节点或其他可访问的主机上启动 mooncake_master,并在每个 mooncake.json 中使用其实际 IP。确认所有模型节点都能访问端口 50088:

    mooncake_master \
    --port 50088 \
    --eviction_high_watermark_ratio 0.9 \
    --eviction_ratio 0.1 \
    --default_kv_lease_ttl 11000 \
    --enable_offload=true \
    --client_ttl=120
    

    以下是 Master 的示例设置:default_kv_lease_ttl=11000 的单位为毫秒,而 client_ttl=120 的单位为秒。驱逐比例为无量纲值;有关其含义和支持范围,请参阅 Mooncake Master 参数表。对于此 SSD 卸载部署,请保持 enable_offload=true。

  2. 启动第一个 A3 Decode 节点(全局 DP rank 0–3)。使用池化 Decode 模板,而不是普通 PD 模板:

    export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
    export LOCAL_IP="$DECODE0_IP"
    export DP_SIZE=8
    export TP_SIZE=4
    export PP_SIZE=1
    export LOCAL_DP_SIZE=4
    export DP_RANK_START=0
    export DP_ADDRESS="$DECODE0_IP"
    export DP_RPC_PORT=31422
    export SERVICE_PORT=31260
    
    python launch_online_dp.py \
        --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
        --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
        --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
        --vllm-start-port "$SERVICE_PORT"
    

    等待 rank 0 打印 Started DP Coordinator process。保持此 shell 运行,同时从另一个 shell 启动第二个节点;初始化需要两个 D 节点。在 950DT 上,使用第 5.3.1 节的双节点 Decode 启动命令并配合 950DT 池化模板,然后跳过步骤 3。

  3. 启动第二个 A3 Decode 节点(全局 DP rank 4–7)。LOCAL_IP 是第二个节点的 IP,但 DP_ADDRESS 仍为第一个 Decode 节点的 IP:

    export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
    export DECODE1_IP="<SECOND_DECODE_NODE_IP>"
    export LOCAL_IP="$DECODE1_IP"
    export DP_SIZE=8
    export TP_SIZE=4
    export PP_SIZE=1
    export LOCAL_DP_SIZE=4
    export DP_RANK_START=4
    export DP_ADDRESS="$DECODE0_IP"
    export DP_RPC_PORT=31422
    export SERVICE_PORT=31260
    
    python launch_online_dp.py \
        --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
        --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
        --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
        --vllm-start-port "$SERVICE_PORT"
    

    两个 Decode 节点均暴露 API 端口 31260–31263。等待全部八个 DP rank 打印 Application startup complete。

  4. 启动 Prefill。在 A3 上,使用池化 P 模板:

    export PREFILL_IP="<PREFILL_NODE_IP>"
    export LOCAL_IP="$PREFILL_IP"
    export DP_SIZE=1
    export TP_SIZE=4
    export PP_SIZE=4
    export LOCAL_DP_SIZE=1
    export DP_RANK_START=0
    export DP_ADDRESS="$PREFILL_IP"
    export DP_RPC_PORT=6884
    export SERVICE_PORT=31050
    
    python launch_online_dp.py \
        --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
        --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
        --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
        --vllm-start-port "$SERVICE_PORT"
    

    在 950DT 上,使用第 5.3.1 节的双节点 Prefill 命令并配合其池化模板。等待每个 Prefill rank 打印 Application startup complete。

  5. 启动 proxy。A3 proxy 注册一个 Prefill 端点和八个 Decode 端点:

    export PREFILL_IP="<PREFILL_NODE_IP>"
    export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
    export DECODE1_IP="<SECOND_DECODE_NODE_IP>"
    
    unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY
    
    python load_balance_proxy_server_example.py \
    --port 8009 \
    --host $PREFILL_IP \
    --prefiller-hosts \
        $PREFILL_IP \
    --prefiller-ports \
        31050 \
    --decoder-hosts \
        $DECODE0_IP $DECODE0_IP $DECODE0_IP $DECODE0_IP \
        $DECODE1_IP $DECODE1_IP $DECODE1_IP $DECODE1_IP \
    --decoder-ports \
        31260 31261 31262 31263 31260 31261 31262 31263
    

    在 Ascend 950DT系列产品上,使用第 5.3.1 节的双节点代理命令(两个 P 和两个 D 端点)。服务可通过 <proxy_ip>:8009 访问;请在第 7 节中使用此端点。

5.3.2.5 验证
  1. 确认 Mooncake Master 端口 50088 可访问,Master 以 --enable_offload=true 运行,且每个节点使用相同的 Master 地址和 tenant_id。对于 A3,确认 P 和两个 D 节点均加载 global_segment_size="15GB";对于 950DT,确认 P 和 D 均加载 "64GB"。检查 worker 日志以确认 segment 注册成功。
  2. 确认每个 Decode 引擎端口就绪,然后确认每个 Prefill 引擎端口就绪。A3 有九个 API(一个 P 加八个 D);950DT 有四个(两个 P 加两个 D)。
  3. 仅向端口 8009 上的 proxy 发送请求。
  4. 使用重复前缀请求进行预热,然后再次发送,并检查 Prefill 日志中的 KV Pool 查找/get/put 及命中信息。
  5. 确认 Decode 日志仍显示正常的 Mooncake P→D KV 传输。
  6. 确认每个参与 worker 的 SSD 存储在 ssd_offload_path 下完成初始化。使用大于内存池的工作集来验证 SSD 卸载及后续读取;仅命中内存池并不能测试 SSD 层级。

5.4 1M Token 上下文部署

MiniMax-M3 支持 1M token 上下文,可在 Atlas 800I A3(W8A8)和 950DT(MXFP8)上单节点部署,也可采用 5.4.2 节中的三节点 A3 Prefill-Decode 布局。此处 1M 指 1,048,576 个 token。--max-model-len 限制输入与生成 token 的总量,因此在准备请求时需预留输出空间。

5.4.1 单节点部署

以下单节点示例使用此前已验证的长上下文部署布局,并以 FULL_DECODE_ONLY 作为图模式。

平台 / 权重 每节点 NPU 数 TP / PP / DP max-model-len max-num-batched-tokens KV cache dtype
Atlas 800I A3 / W8A8 16 × 64GB 4 / 4 / 1 1049600 8192 auto (default)
950DT / MXFP8 8 × 96GB 8 / 1 / 1 1048576 2048 fp8, excluding layers 0–2
950DT / MXFP8 8 × 96GB 4 / 2 / 1 1048576 8192 fp8, excluding layers 0–2

所有三种配置均使用 Model Runner V2、max-num-seqs=1、FULL_DECODE_ONLY graph 模式以及分块 prefill。前缀缓存、异步调度和静态 kernel 均已禁用;不加载投机模型。较小的 batched-token 预算控制的是每个 prefill 分块的大小,而不是总上下文长度。

按照第 3 节和第 4 节所述准备容器和权重。将 <MODEL_PATH>(A3)或 <WEIGHT_PATH>(950DT)替换为本地权重目录。将 HCCL_SOCKET_IFNAME 和 GLOO_SOCKET_IFNAME 中的 <NIC_NAME> 替换为同一个本地通信接口。命令使用部署配置中的 CANN 环境脚本路径;请将这些路径调整为已安装的 CANN 目录。950DT 示例还需要匹配的 experimental_950_transformer 厂商包,然后才能 source 其环境脚本。

使用一台 16-NPU 节点,配置为 TP4/PP4/DP1。此长上下文配置将 60 个 transformer 层均匀划分为 15,15,15,15。1049600 的上下文限制为 1,048,576 个输入 Token 和最多 1024 个生成 Token 留出空间。当配置的限制超过 checkpoint 声明的最大值时,VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 允许使用该限制。

MODEL_PATH="<MODEL_PATH>"  # MiniMax-M3 W8A8 weights

source /usr/local/Ascend/cann-9.1.0/set_env.sh

export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1
export VLLM_EXECUTE_MODEL_TIMEOUT_SECONDS=7200
export VLLM_PP_LAYER_PARTITION="15,15,15,15"
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_SOCKET_IFNAME="<NIC_NAME>"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
export GLOO_SOCKET_IFNAME="<NIC_NAME>"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve "$MODEL_PATH" \
    --host 0.0.0.0 \
    --port 8000 \
    --served-model-name minimax-m3 \
    --trust-remote-code \
    --language-model-only \
    --reasoning-parser minimax_m3 \
    --distributed-executor-backend mp \
    --tensor-parallel-size 4 \
    --pipeline-parallel-size 4 \
    --data-parallel-size 1 \
    --enable-expert-parallel \
    --quantization ascend \
    --block-size 128 \
    --max-model-len 1049600 \
    --max-num-batched-tokens 8192 \
    --long-prefill-token-threshold 8192 \
    --max-num-seqs 1 \
    --enable-chunked-prefill \
    --no-enable-prefix-caching \
    --no-async-scheduling \
    --gpu-memory-utilization 0.95 \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --additional-config '{
        "enable_cpu_binding": true,
        "ascend_compilation_config": {
            "enable_static_kernel": false,
            "fuse_norm_quant": false
        },
        "multistream_overlap_shared_expert": true,
        "enable_shared_expert_dp": false,
        "weight_nz_mode": 2,
        "enable_flashcomm1": true,
        "enable_reduce_sample": false
    }' > ./minimax-m3-1m-a3.log 2>&1 &

--long-prefill-token-threshold 8192 设置与分块预填充配合使用的长预填充阈值。调度器使用该阈值限制单次迭代中为长请求调度的预填充 token 数量,而 --max-num-batched-tokens 8192 则限定该次迭代的总 token 预算。在这个单请求示例中,两个值均为 8192,因此 1M 的提示词会在该预算内分块处理。该参数不会降低由 --max-model-len 配置的总上下文限制。详情请参阅 vLLM 调度器参数。

在八个 NPU 上选择以下任意一种单节点部署方案。两者均使用 FP8 KV 缓存,同时将第 0、1、2 层保持为默认的 KV 数据类型。输入与生成的 token 总数必须控制在 1,048,576 个 token 以内;例如,通过将输入限制为最多 1,047,552 个 token 来预留 1024 个输出 token。

export WEIGHT_PATH="<WEIGHT_PATH>"  # MiniMax-M3 MXFP8 weights

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="<NIC_NAME>"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
export GLOO_SOCKET_IFNAME="<NIC_NAME>"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

source /usr/local/Ascend/cann-9.1.0/opp/vendors/experimental_950_transformer/bin/set_env.bash

vllm serve "$WEIGHT_PATH" \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --host 0.0.0.0 \
    --port 31050 \
    --served-model-name minimax-m3 \
    --trust-remote-code \
    --distributed-executor-backend mp \
    --tensor-parallel-size 8 \
    --pipeline-parallel-size 1 \
    --data-parallel-size 1 \
    --dtype bfloat16 \
    --quantization mxfp8 \
    --max-model-len 1048576 \
    --max-num-seqs 1 \
    --max-num-batched-tokens 2048 \
    --gpu-memory-utilization 0.92 \
    --kv-cache-dtype fp8 \
    --kv-cache-dtype-skip-layers 0 1 2 \
    --limit-mm-per-prompt '{"image":0,"video":0}' \
    --enable-chunked-prefill \
    --no-enable-prefix-caching \
    --no-async-scheduling \
    --reasoning-parser minimax_m3 \
    --safetensors-load-strategy prefetch \
    --additional-config '{
        "enable_cpu_binding": true,
        "ascend_compilation_config": {
            "fuse_qknorm_rope": false,
            "fuse_norm_quant": false,
            "enable_static_kernel": false
        },
        "multistream_overlap_shared_expert": false,
        "enable_shared_expert_dp": false,
        "enable_flashcomm1": false
    }' > ./minimax-m3-1m-950dt-tp8.log 2>&1 &
export WEIGHT_PATH="<WEIGHT_PATH>"  # MiniMax-M3 MXFP8 weights

export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_SOCKET_IFNAME="<NIC_NAME>"
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
export GLOO_SOCKET_IFNAME="<NIC_NAME>"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

source /usr/local/Ascend/cann-9.1.0/opp/vendors/experimental_950_transformer/bin/set_env.bash

vllm serve "$WEIGHT_PATH" \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --host 0.0.0.0 \
    --port 31050 \
    --served-model-name minimax-m3 \
    --trust-remote-code \
    --distributed-executor-backend mp \
    --tensor-parallel-size 4 \
    --pipeline-parallel-size 2 \
    --data-parallel-size 1 \
    --dtype bfloat16 \
    --quantization mxfp8 \
    --max-model-len 1048576 \
    --max-num-seqs 1 \
    --max-num-batched-tokens 8192 \
    --gpu-memory-utilization 0.92 \
    --kv-cache-dtype fp8 \
    --kv-cache-dtype-skip-layers 0 1 2 \
    --enable-chunked-prefill \
    --no-enable-prefix-caching \
    --no-async-scheduling \
    --reasoning-parser minimax_m3 \
    --safetensors-load-strategy prefetch \
    --additional-config '{
        "enable_cpu_binding": true,
        "ascend_compilation_config": {
            "fuse_qknorm_rope": false,
            "fuse_norm_quant": false,
            "enable_static_kernel": false
        },
        "multistream_overlap_shared_expert": false,
        "enable_shared_expert_dp": false,
        "enable_flashcomm1": false
    }' > ./minimax-m3-1m-950dt-tp4pp2.log 2>&1 &

在发送请求之前,请等待所选命令末尾的日志文件中出现 Application startup complete。将报告的 KV 缓存容量与配置的上下文长度进行核对。这些示例展示了已验证的长上下文部署形态;请针对目标工作负载单独调优并发度和性能。

5.4.2 Prefill-Decode 分离部署

本示例使用三台 Atlas 800I A3 节点(每节点 16 × 64GB NPU)和 W8A8 权重:一个 Prefill 服务和一个 Decode 服务分布在两台节点上。它使用 MooncakeConnectorV1 进行直接的 P→D KV 传输。下方的 1M 上下文 PD 配置针对 A3 提供。

角色 全局 DP / TP / PP 本地 DP rank API 端口 max-num-batched-tokens long-prefill-token-threshold
Prefill 1 / 8 / 2 0 31050 8192 8192
First Decode node 4 / 8 / 1 0–1 31260, 31261 8 8
Second Decode node 4 / 8 / 1 2–3 31260, 31261 8 8

两个角色均使用 Model Runner V2、--max-model-len 1049600、--max-num-seqs 1、--kv-cache-dtype auto、FLASHCOMM1、chunked prefill 以及纯文本服务。前缀缓存、异步调度、shared-expert DP、静态 kernel 和 EAGLE3 均已禁用。Prefill 将 60 层拆分为 30,30 并启用 shared-expert 多流重叠;Decode 禁用该重叠。

在此 PD 配置中,P 和 D 均使用 --enforce-eager 并设置 cudagraph_mode=NONE。此前使用 FULL_DECODE_ONLY 和自动调整 KV cache 大小的 Decode 候选方案在测试环境中分配阶段失败。成功的配置使用 Decode token 预算和 long-prefill 阈值 8,并为每个 worker 显式设置 47620449894 字节(约 44.35 GiB)的 KV cache 预算。这是一个可用的长上下文部署示例;性能需另行调优。

5.4.2.1 准备工作

按照第 3、4 和 5.3.1 节的说明准备模型容器、W8A8 权重、跨节点通信和 Mooncake 依赖。在准备好的容器内运行以下命令。将 IP/网卡占位符替换为各主机的通信网络 IP 及匹配的网卡接口,并设置在每个容器内均可见的权重目录。如果安装路径不同,请调整 CANN 环境脚本路径。在多网卡主机上,请检查启动日志,确保通告的主机地址使用预期的通信网络;仅设置 HCCL/GLOO 接口并不能控制所有组件的地址选择。

复用 5.3.1 节的 launch_online_dp.py。在每台相关主机上创建独立的角色目录:

mkdir -p ~/minimax-m3-1m-pd/prefill ~/minimax-m3-1m-pd/decode

将 launch_online_dp.py 的副本保存到每个将要使用的角色目录中。在 P 上将下方的 Prefill 模板保存为 ~/minimax-m3-1m-pd/prefill/run_dp_template.sh,在两台 D 节点上将 Decode 模板保存为 ~/minimax-m3-1m-pd/decode/run_dp_template.sh。即使使用共享存储,也要保持角色目录相互独立:启动器会从其工作目录读取 ./run_dp_template.sh。

四个 Decode 引擎共享一个全局 DP 组。每个进程通过 --data-parallel-size-local 1 服务一个 DP rank;启动器的 --dp-size-local 2 会在每台 D 主机上启动两个这样的进程。两台 D 主机都必须使用第一台 D 主机的 IP 作为 DP_ADDRESS,并使用不同的全局 DP rank 范围。如果更改 TP/PP/DP,请同时更新两个角色的 kv_connector_extra_config 以及所有启动映射。

5.4.2.2 服务脚本

1. Prefill 节点:prefill/run_dp_template.sh

#!/usr/bin/env bash
set -eo pipefail

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# Set this host's communication IP, NIC and W8A8 weight path.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"

# The Section 5.3.1 launcher supplies these values for the Prefill engine.
export DP_SIZE=${DP_SIZE:-1}
export TP_SIZE=${TP_SIZE:-8}
export PP_SIZE=${PP_SIZE:-2}
export SERVICE_PORT=${SERVICE_PORT:-31050}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"

export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1
export VLLM_EXECUTE_MODEL_TIMEOUT_SECONDS=7200
export VLLM_PP_LAYER_PARTITION="30,30"
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=256
export HCCL_IF_IP="$LOCAL_IP"
export HCCL_SOCKET_IFNAME="$NIC_NAME"
export ASCEND_ENABLE_USE_FABRIC_MEM=1
export ASCEND_RT_VISIBLE_DEVICES="$VISIBLE_DEVICES"
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME="$NIC_NAME"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

vllm serve "$MODEL_PATH" \
    --enforce-eager \
    --compilation-config '{"cudagraph_mode":"NONE"}' \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --distributed-executor-backend mp \
    --served-model-name minimax-m3 \
    --enable-expert-parallel \
    --seed 1024 \
    --max-model-len 1049600 \
    --max-num-seqs 1 \
    --max-num-batched-tokens 8192 \
    --long-prefill-token-threshold 8192 \
    --enable-chunked-prefill \
    --no-enable-prefix-caching \
    --no-async-scheduling \
    --trust-remote-code \
    --quantization ascend \
    --gpu-memory-utilization 0.95 \
    --kv-cache-dtype auto \
    --language-model-only \
    --reasoning-parser minimax_m3 \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"enable_static_kernel":false,"fuse_norm_quant":false},"multistream_overlap_shared_expert":true,"weight_nz_mode":2,"enable_shared_expert_dp":false,"enable_flashcomm1":true}' \
    --kv-transfer-config '{
    "kv_connector": "MooncakeConnectorV1",
    "kv_buffer_device": "npu",
    "kv_role": "kv_producer",
    "kv_port": "36000",
    "kv_connector_extra_config": {
        "use_ascend_direct": true,
        "prefill": {
            "dp_size": 1,
            "tp_size": 8,
            "pp_size": 2,
            "pp_layer_partition": "30,30"
        },
        "decode": {
            "dp_size": 4,
            "tp_size": 8,
            "pp_size": 1
        }
    }
}'

2. Decode 节点:decode/run_dp_template.sh

#!/usr/bin/env bash
set -eo pipefail

unset http_proxy https_proxy ftp_proxy all_proxy HTTP_PROXY HTTPS_PROXY FTP_PROXY ALL_PROXY
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# Set this host's communication IP, NIC and W8A8 weight path.
export LOCAL_IP="${LOCAL_IP:-<CURRENT_NODE_IP>}"
export NIC_NAME="${NIC_NAME:-<CURRENT_NODE_NIC>}"
export MODEL_PATH="${MODEL_PATH:-<MINIMAX_M3_W8A8_PATH>}"

# Both D hosts use the first D host's IP as the global DP coordinator.
export DP_SIZE=${DP_SIZE:-4}
export TP_SIZE=${TP_SIZE:-8}
export PP_SIZE=${PP_SIZE:-1}
export DP_RANK=${DP_RANK:-0}
export DP_ADDRESS="${DP_ADDRESS:-<FIRST_DECODE_NODE_IP>}"
export DP_RPC_PORT=${DP_RPC_PORT:-31422}
export SERVICE_PORT=${SERVICE_PORT:-31260}
export VISIBLE_DEVICES="${VISIBLE_DEVICES:-0,1,2,3,4,5,6,7}"

unset VLLM_PP_LAYER_PARTITION

export VLLM_ALLOW_LONG_MAX_MODEL_LEN=1
export VLLM_EXECUTE_MODEL_TIMEOUT_SECONDS=7200
export VLLM_USE_V2_MODEL_RUNNER=1
export HCCL_BUFFSIZE=64
export HCCL_IF_IP="$LOCAL_IP"
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_SOCKET_IFNAME="$NIC_NAME"
export ASCEND_ENABLE_USE_FABRIC_MEM=1
export ASCEND_RT_VISIBLE_DEVICES="$VISIBLE_DEVICES"
if [ -n "${MOONCAKE_LIB_DIRS:-}" ]; then
    export LD_LIBRARY_PATH="${MOONCAKE_LIB_DIRS}:${LD_LIBRARY_PATH:-}"
fi
export GLOO_SOCKET_IFNAME="$NIC_NAME"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True

# Explicit DP ranks enable external load balancing, which requires DP > 1.
DP_RANK_ARGS=()
if [ "$DP_SIZE" -gt 1 ]; then
    DP_RANK_ARGS=(--data-parallel-rank "$DP_RANK")
fi

vllm serve "$MODEL_PATH" \
    "${DP_RANK_ARGS[@]}" \
    --data-parallel-size-local 1 \
    --data-parallel-address "$DP_ADDRESS" \
    --data-parallel-rpc-port "$DP_RPC_PORT" \
    --enforce-eager \
    --compilation-config '{"cudagraph_mode":"NONE"}' \
    --host 0.0.0.0 \
    --port "$SERVICE_PORT" \
    --data-parallel-size "$DP_SIZE" \
    --tensor-parallel-size "$TP_SIZE" \
    --pipeline-parallel-size "$PP_SIZE" \
    --distributed-executor-backend mp \
    --served-model-name minimax-m3 \
    --enable-expert-parallel \
    --seed 1024 \
    --max-model-len 1049600 \
    --max-num-seqs 1 \
    --max-num-batched-tokens 8 \
    --long-prefill-token-threshold 8 \
    --enable-chunked-prefill \
    --no-enable-prefix-caching \
    --no-async-scheduling \
    --trust-remote-code \
    --quantization ascend \
    --gpu-memory-utilization 0.99 \
    --kv-cache-memory-bytes 47620449894 \
    --kv-cache-dtype auto \
    --language-model-only \
    --reasoning-parser minimax_m3 \
    --additional-config '{"enable_cpu_binding":true,"ascend_compilation_config":{"enable_static_kernel":false,"fuse_norm_quant":false},"multistream_overlap_shared_expert":false,"weight_nz_mode":2,"enable_shared_expert_dp":false,"enable_flashcomm1":true}' \
    --kv-transfer-config '{
    "kv_connector": "MooncakeConnectorV1",
    "kv_buffer_device": "npu",
    "kv_role": "kv_consumer",
    "kv_port": "36100",
    "kv_connector_extra_config": {
        "use_ascend_direct": true,
        "prefill": {
            "dp_size": 1,
            "tp_size": 8,
            "pp_size": 2,
            "pp_layer_partition": "30,30"
        },
        "decode": {
            "dp_size": 4,
            "tp_size": 8,
            "pp_size": 1
        }
    }
}'

上述命令保留了经过测试的 --kv-cache-memory-bytes 47620449894 值。如果针对其他环境进行调整,请参考以下指导:

  • 含义与单位: --kv-cache-memory-bytes 指定每个 NPU worker 的 KV cache 预算,单位为字节(1 GiB = 1,073,741,824 字节)。47620449894(约 44.35 GiB)是该布局下经过测试的示例值,并非 MiniMax-M3 的固定要求。显式设置该值时,它会覆盖 --gpu-memory-utilization 用于 KV cache 大小计算;这两个值不会相加。
  • 取值建议: 在两个 Decode 模板中保持相同的值。在扣除模型权重、通信缓冲区、激活值和算子工作区后,按 Decode worker 中可用 NPU 内存的最小值来设定该值,并预留运行时余量。更改硬件、TP/PP、KV 数据类型或软件版本时,请重新核对该预算。
  • 容量检查: 启动后,确认报告的 KV token 容量能够支持 --max-model-len 1049600,然后验证一个 1M token 的请求。值过大会导致内存不足错误;值过小则无法容纳所需的上下文。如果所需的 KV cache 无法容纳,应调整并行布局,而不是假设更小的分配仍能支持 1M token。

在 P 上 HCCL_BUFFSIZE 为 256,在 D 上为 64。

5.4.2.3 启动服务

1. Prefill 节点

cd ~/minimax-m3-1m-pd/prefill

export LOCAL_IP="<PREFILL_NODE_IP>"
export NIC_NAME="<PREFILL_NODE_NIC>"
export MODEL_PATH="<MINIMAX_M3_W8A8_PATH>"
export DP_SIZE=1
export TP_SIZE=8
export PP_SIZE=2
export LOCAL_DP_SIZE=1
export DP_RANK_START=0
export DP_ADDRESS="$LOCAL_IP"
export DP_RPC_PORT=6884
export SERVICE_PORT=31050

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

2. 第一个 Decode 节点:全局 DP rank 0–1

cd ~/minimax-m3-1m-pd/decode

export LOCAL_IP="<FIRST_DECODE_NODE_IP>"
export NIC_NAME="<FIRST_DECODE_NODE_NIC>"
export MODEL_PATH="<MINIMAX_M3_W8A8_PATH>"
export DP_SIZE=4
export TP_SIZE=8
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=0
export DP_ADDRESS="$LOCAL_IP"
export DP_RPC_PORT=31422
export SERVICE_PORT=31260

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

这将启动 DP 协调器和前两个引擎。保持此命令运行,并从另一个 shell 启动第二个 D 主机;不要等待第一个 D 主机完全健康后再启动第二个。

3. 第二个 Decode 节点:全局 DP rank 2–3

cd ~/minimax-m3-1m-pd/decode

export LOCAL_IP="<SECOND_DECODE_NODE_IP>"
export NIC_NAME="<SECOND_DECODE_NODE_NIC>"
export MODEL_PATH="<MINIMAX_M3_W8A8_PATH>"
export DP_SIZE=4
export TP_SIZE=8
export PP_SIZE=1
export LOCAL_DP_SIZE=2
export DP_RANK_START=2
export DP_ADDRESS="<FIRST_DECODE_NODE_IP>"
export DP_RPC_PORT=31422
export SERVICE_PORT=31260

python launch_online_dp.py \
    --dp-size "$DP_SIZE" --tp-size "$TP_SIZE" --pp-size "$PP_SIZE" \
    --dp-size-local "$LOCAL_DP_SIZE" --dp-rank-start "$DP_RANK_START" \
    --dp-address "$DP_ADDRESS" --dp-rpc-port "$DP_RPC_PORT" \
    --vllm-start-port "$SERVICE_PORT"

启动器的设备分配如下:

主机 / DP rank 本地逻辑 NPU API 端口
Prefill / 0 0–15 31050
First D / 0 0–7 31260
First D / 1 8–15 31261
Second D / 2 0–7 31260
Second D / 3 8–15 31261

等待全部五个 API 报告 Application startup complete,并且 /health 返回 HTTP 200。并发运行两个 D 启动命令,直到它们共享的初始化完成。

4. 代理:一个 Prefill 端点和四个 Decode 端点

使用第 5.3.1 节中的 load_balance_proxy_server_example.py。在能够访问全部五个引擎 API 的容器中运行它,例如在 P 上。替换全部三个 IP 占位符。此拓扑有四个 D 端点;请使用下面的映射,而不是普通上下文 A3 示例中的八端点映射。

export PREFILL_IP="<PREFILL_NODE_IP>"
export DECODE0_IP="<FIRST_DECODE_NODE_IP>"
export DECODE1_IP="<SECOND_DECODE_NODE_IP>"

unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY

python load_balance_proxy_server_example.py \
    --port 18919 \
    --host 0.0.0.0 \
    --prefiller-hosts "$PREFILL_IP" \
    --prefiller-ports 31050 \
    --decoder-hosts \
        "$DECODE0_IP" "$DECODE0_IP" \
        "$DECODE1_IP" "$DECODE1_IP" \
    --decoder-ports \
        31260 31261 31260 31261

将客户端请求发送到 http://<PROXY_HOST_IP>:18919/v1/chat/completions。0.0.0.0 值是代理的监听地址。

5.4.2.4 验证
  1. 在发送长请求之前,检查全部五个 /health 端点以及每个引擎报告的 KV token 容量。
  2. 通过代理发送一个短文本请求,并验证生成的答案。
  3. 使用所部署模型的 tokenizer 准备一个恰好包含 1,048,576 个 token 的提示词。确保输入加上请求的输出不超过 1049600;该配置为完整的 1M token 输入预留最多 1024 个输出 token。
  4. 验证 API 的输入 token 计数和请求的检索答案。检查 Prefill 的提示词 token 计数器以及接收方 Decode rank 的外部前缀缓存命中计数器,以确认长前缀已被传输。Decode 不应重新计算完整的 1M prefill。

记录的 A3 运行使用了 vLLM 0.30.0+empty 和 vLLM Ascend 0.30.0rc2.dev166+g7672a5b50。全部五个引擎均健康,一个包含 1,048,576 个输入 token 和 33 个输出 token 的真实请求正确检索了分布在上下文中的三个随机值。P 处理了 1,048,576 个 prompt token;接收方 D rank 报告了相同的传输前缀命中增量和 33 个迭代 token,且无抢占。这验证了一个 1M 上下文的 PD 请求。它并不能证明四个同时的 1M 请求或 AISBench 性能结果。模板保留了该次运行的服务参数和 KV 拓扑,并将环境导出项规范化为本指南的形式。这些规范化片段尚未在 NPU 上重新运行,且现有验证容器未针对预先存在的更改进行全面审计。在不同构建上复现时,请重新检查兼容性。

5.5 多模态与 ViT DP(可选)

MiniMax-M3 在昇腾上支持图像和视频输入。上述部署示例将 --limit-mm-per-prompt '{"image":1,"video":0}' 作为默认的多模态容量假设,因为其他服务参数是针对单图像路径调优的。

MiniMax-M3 的图像和视频输入共享同一个 Vision Tower。如果服务只需要一种模态,请将未使用的模态显式设置为 0;例如,仅图像服务使用 {"image":1,"video":0},仅视频服务使用 {"image":0,"video":1}。只要图像或视频任一保持启用,共享的 Vision Tower 就会被保留。将未使用的模态设置为 0 比省略它更清晰,因为省略的模态仍可能参与多模态容量和性能分析规划。

对于 ViT / 多模态编码器部分,支持数据并行执行,可以通过以下方式启用:

--mm-encoder-tp-mode data

默认部署示例中未启用此选项,因为它可能会增加每卡内存使用量。启用 ViT DP 时,请针对目标工作负载重新评估内存相关参数,例如 --max-model-len、--max-num-seqs 和 --gpu-memory-utilization。

对于视频或图像-视频混合请求,请根据实际请求形态调整多模态限制,而不是盲目更改默认模板:

# one video
--limit-mm-per-prompt '{"image":0,"video":1}'

# one image and one video
--limit-mm-per-prompt '{"image":1,"video":1}'

当在请求中使用本地媒体路径(例如 file:///path/to/video.mp4)时,请添加显式的白名单路径:

--allowed-local-media-path /

如果未指定采样的视频帧数,vLLM 将使用其默认的视频采样策略,默认采样 32 帧。对于快速功能冒烟测试,可以在请求或评估配置中设置较小的帧数,例如 8 或 16。对于基准测试运行,请遵循数据集协议。

FLASHCOMM1 与 --language-model-only 可以同时启用以用于纯文本服务,包括 第 5.4 节 中的 A3 1M 上下文示例。通过 additional_config.enable_flashcomm1 启用 FLASHCOMM1。--language-model-only 标志为可选项,对于多模态输入必须省略。

# Enable FLASHCOMM1.
--additional-config '{"enable_flashcomm1": true}'

# Enable language-model-only mode.
--language-model-only

6 思考与解析器配置

6.1 思考模式

MiniMax-M3 支持三种思考模式,通过 chat_template_kwargs 中的 thinking_mode 控制:

模式 行为 使用场景
enabled 模型在每次响应前进行思考,包括在工具结果之后 复杂推理、智能体
disabled 不进行思考;模型直接回答 对延迟敏感的轮次
adaptive 模型根据任务决定是否思考(未设置时的默认值) 一般用途

6.1.1 请求示例

禁用思考(curl):

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3",
    "messages": [{"role": "user", "content": "who are you?"}],
    "max_tokens": 100,
    "stream": false,
    "top_p": 0.95,
    "top_k": 40,
    "temperature": 1.0,
    "chat_template_kwargs": {"thinking_mode": "disabled"}
  }'

根据需要将 "thinking_mode" 更改为 "enabled" 或 "adaptive"。已弃用的 enable_thinking 参数(等同于 thinking_mode: "enabled")也受支持。

启用思考(Python SDK):

将 base_url 设置为已部署的 API 地址,需包含 /v1。以下示例使用 5.1 节的服务端口;对于 PD 分离场景,请改用代理地址和端口。

from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:11223/v1")

response = client.chat.completions.create(
    model="minimax-m3",
    messages=[{"role": "user", "content": "Prove there are infinitely many primes."}],
    extra_body={"chat_template_kwargs": {"thinking_mode": "enabled"}},
)
msg = response.choices[0].message
print(getattr(msg, "reasoning", None))  # the <mm:think> block
print(msg.content)                       # the final answer

6.2 推理解析器

MiniMax-M3 推理解析器(--reasoning-parser minimax_m3)从模型输出中提取思考块 <mm:think>...</mm:think>,并将其作为 reasoning 字段暴露。其余文本作为 content 返回。

6.2.1 服务器配置

--reasoning-parser minimax_m3 标志启用 MiniMax-M3 推理解析器,该解析器使用 <mm:think>...</mm:think> 分隔符将模型输出拆分为推理和内容:

export VLLM_USE_V2_MODEL_RUNNER=1

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --reasoning-parser minimax_m3 \
  ...

6.2.2 输出格式

MiniMax-M3 使用显式的思考分隔符:

<mm:think>reasoning process...</mm:think>final answer

6.2.3 解析器行为

  • thinking_mode="enabled":聊天模板在提示中预填充 <mm:think>。生成的文本从推理块内部开始,并在 </mm:think> 之后过渡到内容。
  • thinking_mode="disabled" 或默认:模型输出被视为纯内容。如果出现 <mm:think>,解析器将根据分隔符进行拆分。
  • 流式输出:推理和内容通过 DeltaMessage.reasoning 和 DeltaMessage.content 逐 token 增量流式传输。
  • Token 计数:<mm:think> 块内的推理 token 会被正确计数。

6.3 工具调用解析器

MiniMax-M3 使用以命名空间分隔的 XML 格式进行工具调用。通过 --tool-call-parser minimax_m3 启用该功能。

6.3.1 服务器配置

当同时指定 --reasoning-parser minimax_m3 和 --tool-call-parser minimax_m3 时,解析器会自动协同工作,处理同时包含推理块和工具调用的响应:

export VLLM_USE_V2_MODEL_RUNNER=1

vllm serve ${WEIGHT_PATH} \
  --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
  --reasoning-parser minimax_m3 \
  --enable-auto-tool-choice \
  --tool-call-parser minimax_m3 \
  ...

6.3.2 工具调用格式

每个结构标签前都有 ]<]minimax[>[ 命名空间标记:

]<]minimax[>[<tool_call>
]<]minimax[>[<invoke name="create_order">
]<]minimax[>[<user_id>42]<]minimax[>[</user_id>
]<]minimax[>[<shipping>
]<]minimax[>[<city>Singapore]<]minimax[>[</city>
]<]minimax[>[<zip>018956]<]minimax[>[</zip>
]<]minimax[>[</shipping>
]<]minimax[>[</invoke>
]<]minimax[>[</tool_call>

6.3.3 主要特性

  • 递归参数解析:支持嵌套对象和数组(例如,包含 city/zip 的 shipping)。
  • 模式感知类型转换:根据函数的 JSON Schema 定义,字符串参数值会自动转换为正确的类型(整数、布尔值、对象、数组)。
  • 多次调用:单个 <tool_call> 块可以包含多个 <invoke> 块。
  • 流式输出:工具名称和参数片段在接收 <invoke> 块时增量流式传输。

6.3.4 请求示例(curl)

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3",
    "messages": [{"role": "user", "content": "What is the weather like in Shanghai?"}],
    "max_tokens": 300,
    "stream": false,
    "tool_choice": "auto",
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current weather for a city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "City or country name"
                        }
                    },
                    "required": ["location"],
                    "additionalProperties": false
                }
            }
        }
    ],
    "chat_template_kwargs": {"thinking_mode": "disabled"}
  }'

7 功能验证

7.1 文本

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": "Answer the following multiple choice question. The last line of your response should be of the following format: 'Answer: LETTER' (without quotes) where LETTER is one of ABCD. Think step by step before answering.\n\nA student regrets that he fell asleep during a lecture in electrochemistry, facing the following incomplete statement in a test:\nThermodynamically, oxygen is a …oxidant in basic solutions. Kinetically, oxygen reacts …in acidic solutions.\nWhich combination of weaker/stronger and faster/slower is correct?\n\nA) weaker —faster\nB) stronger —faster\nC) weaker - slower\nD) stronger —slower"
    }
  ],
  "max_tokens": 8000,
  "temperature": 1.0
}
EOF

预期结果:答案为 C。

7.2 单张图片

以启用图像输入的方式启动服务,例如 --limit-mm-per-prompt '{"image":1,"video":0}'。在客户端将 ${IMAGE_PATH} 替换为本地图像路径。

IMAGE_PATH=/path/to/image.jpg
IMAGE_BASE64="$(base64 -w 0 "${IMAGE_PATH}")"

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"}},
        {"type": "text", "text": "Briefly describe this image."}
      ]
    }
  ],
  "max_tokens": 512,
  "temperature": 0
}
EOF

预期结果:HTTP 200 响应,JSON 响应体包含非空的 choices 以及描述该图像的生成文本。

7.3 单个视频

以启用视频输入的方式启动服务,例如 --limit-mm-per-prompt '{"image":0,"video":1}'。如果请求使用 file:// 本地视频路径,还需添加 --allowed-local-media-path / 或更窄的允许目录。如果未指定 media_io_kwargs.video.num_frames,vLLM 默认采样 32 帧。

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-m3",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "video_url",
            "video_url": {
              "url": "file:///path/to/video.mp4"
            }
          },
          {
            "type": "text",
            "text": "Briefly describe the main content of this video."
          }
        ]
      }
    ],
    "max_tokens": 512,
    "temperature": 0
  }'

预期结果:HTTP 200 响应,JSON 响应体包含非空的 choices 以及描述该视频内容的生成文本。

7.4 图像和视频混合请求

启动服务时同时启用图像和视频输入。对于以下请求,使用 --limit-mm-per-prompt '{"image":1,"video":1}'。如果请求使用 file:// 本地视频路径,还需添加 --allowed-local-media-path / 或更窄的允许目录。

IMAGE_BASE64="$(base64 -w 0 /path/to/image.jpg)"

curl http://{ip}:{port}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @- <<EOF
{
  "model": "minimax-m3",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,${IMAGE_BASE64}"}},
        {"type": "video_url", "video_url": {"url": "file:///path/to/video.mp4"}},
        {"type": "text", "text": "Describe the image and video separately, and explain whether they are related."}
      ]
    }
  ],
  "max_tokens": 512,
  "temperature": 0
}
EOF

预期结果:HTTP 200 响应,JSON 响应体包含非空的 choices 以及分别描述图像和视频并说明二者是否相关的生成文本。

8 精度评估

下表中的上下文限制条目使用统一的服务设置 max-model-len=133000。精度分数沿用现有评测结果,未随本次文档更新重新测量。

8.1 使用 AISBench

详细说明请参阅 使用 AISBench 进行精度评估。

8.2 文本评估

数据集 硬件 分数 max-model-len max-num-seqs max_out_len batch_size generation_kwargs
GSM8K 8 H20 (96GB × 8) 96.72 133000 16 49152 16 temperature=1.0, top_p=0.95
GSM8K 8 Atlas 800I A3 (64GB × 16) 96.36 133000 16 9500 20 temperature=1.0, top_p=0.95
AIME2025 8 H20 (96GB × 8) 95@repeat4 - - - - -
AIME2025 8 Atlas 800I A3 (64GB × 16) 93.3@repeat2 133000 32 65536 8 temperature=1.0, top_p=0.95
GPQA-Diamond 8 H20 (96GB × 8) 92.42 133000 64 75776 8 temperature=0.6, top_p=0.95
GPQA-Diamond 8 Atlas 800I A3 (64GB × 16) 92.42 263000 32 131072 64 temperature=1.0, top_p=0.95
GPQA-Diamond 8 950DT products (96GB × 8) 92.9 133000 128 131072 128 temperature=1.0, top_p=0.95
MMMU-pro 8 950DT products (96GB × 8) 78.9 133000 128 131072 50 temperature=1.0, top_p=0.95

8.3 多模态评估

MiniMax-M3 多模态精度使用 AISBench 进行评估。ViT DP 路径是可选的,可通过在服务命令中添加 --mm-encoder-tp-mode data 来启用,但并非所有多模态精度测试都需要该路径。对于视频评估,如果请求或评估配置中未指定帧数,vLLM 默认采样 32 帧。

以下 Video-MME 结果是在 chunk1 和 chunk2 上测得的,并非完整数据集。

从 Video-MME 数据集 获取视频文件以及问题/答案标注,该数据集由 Video-MME 官方仓库 链接。请在本地准备好 chunk1/chunk2 视频,并按以下说明将数据集配置中的 path 和 video_path 设置为相应的元数据和已解压视频目录。

对于 Video-MME 评测,请启用视频输入并运行 vLLM 的 OpenAI 兼容服务,然后使用 AISBench 发送 Video-MME 请求。官方 AISBench 指南可能未将 Video-MME 列为内置示例,因此推荐的 MiniMax-M3 设置如下:

  • 使用 --limit-mm-per-prompt '{"image":0,"video":1}' 启动服务;
  • 不要设置 media_io_kwargs.video.num_frames,这样 vLLM 会使用默认的 32 个采样帧;
  • 使用 max-model-len=133000 和 max_out_len=8192;
  • 评测 Video-MME 的 chunk1 和 chunk2,而非完整数据集。

用于 Video-MME chunk1+chunk2 评估的 AISBench 命令如下:

ais_bench \
  --models vllm_api_general_chat \
  --datasets videomme_subset_1_2.py \
  --mode all \
  --dump-eval-details \
  --merge-ds

videomme_subset_1_2.py 是一个本地 AISBench 数据集配置,源自原始 Video-MME 配置(如 videomme_gen.py)。它将 path 指向根据本地可用的 chunk1/chunk2 视频从完整 Video-MME 元数据中筛选出的 parquet 文件,并将 video_path 指向提取的 chunk1/chunk2 .mp4 目录。这样既保持了评估的轻量性,又保留了标准的 Video-MME 请求和评分流程。

Dataset Modality Tool Hardware ViT DP max-model-len max_out_len Input Config generation_kwargs Score
TextVQA Image AISBench GPU disabled 133000 512 --limit-mm-per-prompt '{"image":1,"video":0}' temperature=1.0, top_p=0.95 70.82
TextVQA Image AISBench NPU disabled 133000 512 --limit-mm-per-prompt '{"image":1,"video":0}' temperature=1.0, top_p=0.95 72.75
Video-MME chunk1+chunk2 Video AISBench GPU - 133000 8192 --limit-mm-per-prompt '{"image":0,"video":1}', default 32 frames temperature=1.0, top_p=0.95 73.41
Video-MME chunk1+chunk2 Video AISBench NPU - 133000 8192 --limit-mm-per-prompt '{"image":0,"video":1}', default 32 frames temperature=1.0, top_p=0.95 74.21

9 性能调优

注意:以下配置在特定测试环境中经过验证,仅供参考。最佳配置取决于最大输入/输出长度、前缀缓存命中率、精度要求以及部署机器比例等因素。建议根据实际情况参考第 9.2 节进行调优。

9.1 推荐配置

推荐配置与第 5 章 在线服务部署 中指定的配置相同。

9.2 调优指南

9.2.1 通用调优参考

有关通用调优方法,请参阅公共性能调优文档。

请参阅特性矩阵获取详细的特性描述。

9.2.2 针对特定工作负载的调优

可将以下调整作为目标工作负载的起点。每次更改后请重新检查内存使用、延迟和吞吐量。

场景 参数 调整示例 调优目标
受设备内存限制、KV 缓存容量制约并发度的工作负载 HCCL_BUFFSIZE 从 2048 降低到 1024(MB)。 减少 HCCL 通信缓冲区内存占用,为 KV 缓存腾出更多设备内存,从而支持更高的并发度。
短输入工作负载,例如 4K 输入 token --max-num-batched-tokens 从 32768 降低到 8192。 使用更小的单次迭代 token 预算以降低内存压力,并调优短序列性能。

10 常见问题

  • 问:如何重新安装 vLLM Ascend?

答:使用以下命令重新安装 vLLM Ascend,并使用当前 Python 环境中的依赖进行构建:

pip install -v --no-build-isolation -e . -i http://mirrors.aliyun.com/pypi/simple --trusted-host mirrors.aliyun.com
  • 问:当未设置 media_io_kwargs.video.num_frames 时,视频请求变慢或超时该怎么办?

答:默认情况下,vLLM 在读取视频时会采样 32 帧。MiniMax-M3 每帧会产生大量视觉 token,因此 32 帧的视频会显著增加预填充计算量。如果请求变慢或超时,请显式将 media_io_kwargs.video.num_frames 设置为较小的值,例如 8 或 16 帧:

{
  "media_io_kwargs": {
    "video": {
      "num_frames": 8
    }
  }
}