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 镜像
步骤 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):
预期结果:容器列出且状态为 Up。在原始容器终端中,验证 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 配置挂载到每个参与池化的容器中:
在 Ascend 950DT系列产品上,还需保留 5.3.1 节中的 /etc/hixlep/ 挂载,用于昇腾直接 KV 传输。
在每个 Prefill 和 Decode 主机上使用本地 SSD 目录来存储从内存池卸载的 KV cache 数据。/nvme/mooncake_offload 是容器内的示例目录,并非必需的 SSD 挂载点,也不是每台主机上都已存在的目录。
在每台主机上,首先识别本地 SSD 及其挂载点:
使用 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,也不能确保数据存储在其上。
在创建每个模型容器时添加此绑定挂载:
左侧是该主机 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 容量。其默认值为每个 worker2199023255552字节(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 启动服务¶
按以下顺序启动:
-
在 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。 -
启动第一个 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。 -
启动第二个 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。 -
启动 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。 -
启动 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 验证¶
- 确认 Mooncake Master 端口
50088可访问,Master 以--enable_offload=true运行,且每个节点使用相同的 Master 地址和tenant_id。对于 A3,确认 P 和两个 D 节点均加载global_segment_size="15GB";对于 950DT,确认 P 和 D 均加载"64GB"。检查 worker 日志以确认 segment 注册成功。 - 确认每个 Decode 引擎端口就绪,然后确认每个 Prefill 引擎端口就绪。A3 有九个 API(一个 P 加八个 D);950DT 有四个(两个 P 加两个 D)。
- 仅向端口
8009上的 proxy 发送请求。 - 使用重复前缀请求进行预热,然后再次发送,并检查 Prefill 日志中的 KV Pool 查找/get/put 及命中信息。
- 确认 Decode 日志仍显示正常的 Mooncake P→D KV 传输。
- 确认每个参与 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。在每台相关主机上创建独立的角色目录:
将 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 验证¶
- 在发送长请求之前,检查全部五个
/health端点以及每个引擎报告的 KV token 容量。 - 通过代理发送一个短文本请求,并验证生成的答案。
- 使用所部署模型的 tokenizer 准备一个恰好包含 1,048,576 个 token 的提示词。确保输入加上请求的输出不超过
1049600;该配置为完整的 1M token 输入预留最多 1024 个输出 token。 - 验证 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 / 多模态编码器部分,支持数据并行执行,可以通过以下方式启用:
默认部署示例中未启用此选项,因为它可能会增加每卡内存使用量。启用 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)时,请添加显式的白名单路径:
如果未指定采样的视频帧数,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 使用显式的思考分隔符:
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 帧: