MiniMax-M2

1 引言

MiniMax-M2 是 MiniMax 的旗舰大语言模型系列，包括 MiniMax-M2.5 和 MiniMax-M2.7。该系列针对代码生成、智能工具调用/搜索以及复杂办公工作流等高价值场景进行了强化，注重推理效率和具有挑战性任务的端到端速度。

本文档将展示 MiniMax-M2.5 和 MiniMax-M2.7 的主要验证步骤，包括支持的特性、特性配置、环境准备、单节点和多节点部署、精度与性能评估。

本文档基于最新的 vLLM-Ascend 版本编写。MiniMax-M2.5 和 MiniMax-M2.7 均完全支持。如需使用最新特性（例如 PD 分离、EAGLE3 推测解码），建议使用最新版本。

2 支持的特性

请参考支持的特性获取模型支持的特性矩阵。

请参考特性指南获取特性的配置方法。

3 前提条件

3.1 模型权重

以下模型权重和 EAGLE3 权重可在 ModelScope 上获取。请在 ModelScope 上搜索对应的模型名称以获取最新的权重文件。

模型	描述	推荐硬件	来源
MiniMax-M2.7-w8a8-QuaRot	M2.7 W8A8 量化版本	1× Atlas 800 A3（64GB × 16）或 1× Atlas 800I A2（64GB × 8）	MiniMax-M2.7-w8a8-QuaRot
MiniMax-M2.5-w8a8-QuaRot	M2.5 W8A8 量化版本	1× Atlas 800 A3（64GB × 16）或 1× Atlas 800I A2（64GB × 8）	MiniMax-M2.5-w8a8-QuaRot
MiniMax-M2.7-w8a8c8-QuaRot	M2.7 W8A8C8 量化版本	1× Atlas 800 A3（64GB × 16）或 1× Atlas 800I A2（64GB × 8）	MiniMax-M2.7-w8a8c8-QuaRot
EAGLE3（M2.7）	M2.7 推测解码头模型	与基础模型节点数匹配	MiniMax-M2.7-eagle-model
EAGLE3（M2.5）	M2.5 推测解码头模型	与基础模型节点数匹配	MiniMax-M2.5-eagle-model

建议将模型权重下载到共享目录，例如 /root/.cache/。

3.2 验证多节点通信（可选）

如果需要部署多节点环境，请按照验证多节点通信环境 验证多节点通信。

4 安装

4.1 Docker 镜像安装

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

A3 系列

Docker 运行命令：

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0-a3

docker run \
    --name vllm-ascend-env \
    --ipc host \
    --net host \
    --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/Ascend/driver:/usr/local/Ascend/driver \
    -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 /usr/local/sbin:/usr/local/sbin \
    -it -d $IMAGE bash

备注

A3 有 8 个 NPU，采用双芯设计（共 16 个芯片：/dev/davinci[0-15]）。如果您在共享机器上，请仅映射您需要的芯片（例如，NPU 0-3 对应 /dev/davinci[0-7]）。

A2 系列

Docker 运行命令：

export IMAGE=quay.io/ascend/vllm-ascend:v0.23.0

docker run \
    --name vllm-ascend-env \
    --ipc host \
    --net host \
    --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/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    -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 /usr/local/sbin:/usr/local/sbin \
    -it -d $IMAGE bash

小技巧

上述挂载是访问 NPU 驱动所需的最低要求。请根据您的环境添加额外的 -v 挂载（例如模型权重路径、数据集）。

默认工作目录是 /workspace。vLLM 和 vLLM-Ascend 作为 Python 包安装在 site-packages 中。

安装验证：

启动容器后，运行以下命令验证安装：

docker ps | grep vllm-ascend-env

预期结果：容器列出，状态为 Up。您还可以在容器内验证 vllm-ascend 版本：

pip show vllm-ascend

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

4.2 源码安装

如果您希望从源码构建而非使用 Docker 镜像，请按照安装指南安装 vLLM-Ascend。

验证源码安装：

python -c "import vllm_ascend; print(vllm_ascend.__version__)"

5 在线服务部署

备注

在本教程中，我们假设您已下载模型权重。请将 /path/to/weight/ 替换为您的实际模型权重路径。

5.1 单节点在线部署

单节点部署在同一节点内完成 Prefill 和 Decode，适用于开发、测试以及中低吞吐量的生产场景。

常见问题提示： 如果遇到 OOM、HCCL 端口冲突或其他启动问题，请参考公共 FAQ 进行故障排除。对于 MiniMax 特定问题，请参考第 10 章 FAQ。

A3（单节点）

以下是短上下文条件（例如 3.5k 输入 / 1.5k 输出）下的推荐启动配置，以获得良好性能。

注意：

• 如果只关心短上下文低延迟，可以设置 --max-model-len 32768、--tensor-parallel-size 4 和 --data-parallel-size 4。

export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=1024
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export OMP_NUM_THREADS=1
echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0
sysctl kernel.sched_migration_cost_ns=50000
export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2:$LD_PRELOAD
export TASK_QUEUE_ENABLE=1

export VLLM_ASCEND_BALANCE_SCHEDULING=0

vllm serve /path/to/weight/MiniMax-M2.7-w8a8-QuaRot \
    --served-model-name "MiniMax-M2.7" \
    --host 0.0.0.0 \
    --port 8000 \
    --trust-remote-code \
    --quantization ascend \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --async-scheduling \
    --additional-config '{"enable_cpu_binding":true,
                          "enable_fused_mc2":true,
                          "enable_flashcomm1":true,
                          "weight_nz_mode":true}' \
    --enable-expert-parallel \
    --tensor-parallel-size 4 \
    --data-parallel-size 4 \
    --max-num-seqs 48 \
    --max-model-len 40690 \
    --max-num-batched-tokens 16384 \
    --gpu-memory-utilization 0.85 \
    --speculative_config '{"enforce_eager": true, "method": "eagle3", "model": "/path/to/weight/Eagle3/", "num_speculative_tokens": 3}'

备注：

• minimax_m2_append_think 将 <think>...</think> 保留在 content 中。

• 如果主要依赖 /v1/responses 的推理语义，建议改用 --reasoning-parser minimax_m2。

• 为了在长上下文场景（如 128k 或 64k）中获得更好的性能，建议进行以下调整：

    --tensor-parallel-size 8 \
    --data-parallel-size 1 \
    --decode-context-parallel-size 1 \
    --prefill-context-parallel-size 2 \
    --cp-kv-cache-interleave-size 128 \
    --max-num-seqs 16 \
    --max-model-len 138000 \
    --max-num-batched-tokens 65536 \
    --gpu-memory-utilization 0.85 \
    --speculative_config '{"enforce_eager": true, "method": "eagle3", "model": "/path/to/weight/Eagle3/", "num_speculative_tokens": 1}'

注意：上述参数在特定测试环境中验证，仅供参考。请根据实际输入/输出长度、并发数和硬件配置调整 --max-model-len、--max-num-seqs、--max-num-batched-tokens 和 --gpu-memory-utilization。

• 如果需要使用 curl 和工具调用进行测试，请在启动命令中添加以下内容：

    --enable-auto-tool-choice \
    --tool-call-parser minimax_m2 \
    --reasoning-parser minimax_m2_append_think \

A2（单节点）

export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2:$LD_PRELOAD
export HCCL_OP_EXPANSION_MODE="AIV"
export HCCL_BUFFSIZE=512
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0
sysctl kernel.sched_migration_cost_ns=50000
export TASK_QUEUE_ENABLE=1
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export HCCL_INTRA_PCIE_ENABLE=1
export HCCL_INTRA_ROCE_ENABLE=0
export OMP_PROC_BIND=false
export OMP_NUM_THREADS=1

vllm serve /path/to/weight/MiniMax-M2.7-w8a8-QuaRot \
    --served-model-name MiniMax-M2.7 \
    --host 0.0.0.0 \
    --port 8000 \
    --trust-remote-code \
    --tensor-parallel-size 8 \
    --quantization ascend \
    --enable-expert-parallel \
    --max-num-seqs 32 \
    --seed 1024 \
    --max-num-batched-tokens 32768 \
    --compilation-config '{"cudagraph_mode": "FULL_DECODE_ONLY"}' \
    --gpu-memory-utilization 0.85 \
    --additional-config '{"enable_cpu_binding":true,
                          "enable_flashcomm1":true}' \
    --model-loader-extra-config '{"enable_multithread_load":true,"num_threads":16}' \
    --speculative_config '{"method": "eagle3", "model": "/path/to/weight/Eagle3/", "num_speculative_tokens":3}'

注意：上述参数在特定测试环境中验证，仅供参考。请根据实际输入/输出长度、并发数和硬件配置调整 --max-model-len、--max-num-seqs、--max-num-batched-tokens 和 --gpu-memory-utilization。

• 如果需要使用 curl 和工具调用进行测试，请在启动命令中添加以下内容：

    --enable-auto-tool-choice \
    --tool-call-parser minimax_m2 \
    --reasoning-parser minimax_m2_append_think \

5.2 多节点 PD 分离部署

PD（Prefill-Decode）分离将 Prefill 和 Decode 阶段分布到不同节点，以获得更好的吞吐量。以下 1P1D 配置已针对 MiniMax-M2.7-W8A8 的 128k 输入/输出场景验证。

硬件：2× Atlas 800 A3（64GB × 16），一个用于 Prefill，一个用于 Decode。

常见问题提示：对于 KV 传输超时或 Mooncake 连接错误等 PD 分离特定问题，请参考公共 FAQ。对于 MiniMax 特定的 PD 分离问题，请参考第 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)
    parser.add_argument("--tp-size", type=int, default=1)
    parser.add_argument("--dp-size-local", type=int, default=-1)
    parser.add_argument("--dp-rank-start", type=int, default=0)
    parser.add_argument("--dp-address", type=str, required=True)
    parser.add_argument("--dp-rpc-port", type=str, default=12345)
    parser.add_argument("--vllm-start-port", type=int, default=9000)
    return parser.parse_args()

args = parse_args()
dp_size, tp_size = args.dp_size, args.tp_size
dp_size_local = args.dp_size_local if args.dp_size_local != -1 else dp_size

def run_command(visible_devices, dp_rank, vllm_engine_port):
    subprocess.run([
        "bash", "./run_dp_template.sh",
        visible_devices, str(vllm_engine_port),
        str(dp_size), str(dp_rank), args.dp_address,
        args.dp_rpc_port, str(tp_size),
    ], check=True)

if __name__ == "__main__":
    for i in range(dp_size_local):
        dp_rank = args.dp_rank_start + i
        vllm_port = args.vllm_start_port + i
        visible_devices = ",".join(str(x) for x in range(i * tp_size, (i + 1) * tp_size))
        p = multiprocessing.Process(target=run_command, args=(visible_devices, dp_rank, vllm_port))
        p.start()
        p.join()

然后在每个节点上准备 run_dp_template.sh。

Prefill 节点（将 nic_name 和 local_ip 设置为您自己的）：

unset http_proxy https_proxy ftp_proxy

nic_name="<your_nic_name>"
local_ip="<your_ip>"

export HCCL_IF_IP=$local_ip
export GLOO_SOCKET_IFNAME=$nic_name
export TP_SOCKET_IFNAME=$nic_name
export HCCL_SOCKET_IFNAME=$nic_name

export HCCL_BUFFSIZE=1024
export HCCL_OP_EXPANSION_MODE="AIV"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export OMP_NUM_THREADS=1
echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0
sysctl kernel.sched_migration_cost_ns=50000
export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2:$LD_PRELOAD
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH

export TASK_QUEUE_ENABLE=1
export VLLM_ASCEND_ENABLE_FLASHCOMM1=1
export VLLM_ASCEND_ENABLE_FUSED_MC2=1
export PYTHONHASHSEED=0

export ASCEND_RT_VISIBLE_DEVICES=$1

vllm serve /path/to/weight/MiniMax-M2.7-w8a8-QuaRot \
    --host 0.0.0.0 \
    --port $2 \
    --data-parallel-size $3 \
    --data-parallel-rank $4 \
    --data-parallel-address $5 \
    --data-parallel-rpc-port $6 \
    --tensor-parallel-size $7 \
    --enable-expert-parallel \
    --served-model-name minimax \
    --max-model-len 200000 \
    --max-num-batched-tokens 16384 \
    --max-num-seqs 64 \
    --trust-remote-code \
    --gpu-memory-utilization 0.75 \
    --quantization ascend \
    --enforce-eager \
    --speculative_config '{"method": "eagle3", "model": "/path/to/weight/Eagle3/", "num_speculative_tokens": 1}' \
    --additional-config '{"enable_cpu_binding":true}' \
    --kv-transfer-config \
        '{"kv_connector": "MooncakeConnectorV1",
        "kv_role": "kv_producer",
        "kv_port": "35880",
        "engine_id": "0",
        "kv_connector_extra_config": {
             "use_ascend_direct": true,
             "prefill": {"dp_size": 2, "tp_size": 8},
             "decode":  {"dp_size": 2, "tp_size": 8}
        }}'

Decode 节点（将 nic_name 和 local_ip 设置为您自己的）：

unset http_proxy https_proxy ftp_proxy

nic_name="<your_nic_name>"
local_ip="<your_ip>"

export HCCL_IF_IP=$local_ip
export GLOO_SOCKET_IFNAME=$nic_name
export TP_SOCKET_IFNAME=$nic_name
export HCCL_SOCKET_IFNAME=$nic_name

export HCCL_BUFFSIZE=2048
export HCCL_OP_EXPANSION_MODE="AIV"
export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
export OMP_NUM_THREADS=1
echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0
sysctl kernel.sched_migration_cost_ns=50000
export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2:$LD_PRELOAD
export LD_LIBRARY_PATH=/usr/local/Ascend/ascend-toolkit/latest/python/site-packages/mooncake:$LD_LIBRARY_PATH

export TASK_QUEUE_ENABLE=1
export VLLM_ASCEND_ENABLE_FLASHCOMM1=0
export VLLM_ASCEND_ENABLE_FUSED_MC2=1
export PYTHONHASHSEED=0

export ASCEND_RT_VISIBLE_DEVICES=$1

vllm serve /path/to/weight/MiniMax-M2.7-w8a8-QuaRot \
    --host 0.0.0.0 \
    --port $2 \
    --data-parallel-size $3 \
    --data-parallel-rank $4 \
    --data-parallel-address $5 \
    --data-parallel-rpc-port $6 \
    --tensor-parallel-size $7 \
    --enable-expert-parallel \
    --served-model-name minimax \
    --max-model-len 200000 \
    --max-num-batched-tokens 16384 \
    --max-num-seqs 16 \
    --trust-remote-code \
    --no-enable-prefix-caching \
    --gpu-memory-utilization 0.75 \
    --quantization ascend \
    --async-scheduling \
    --compilation-config '{"cudagraph_mode":"FULL_DECODE_ONLY"}' \
    --speculative_config '{"method": "eagle3", "model": "/path/to/weight/Eagle3/", "num_speculative_tokens": 3}' \
    --additional-config '{"enable_cpu_binding":true}' \
    --kv-transfer-config \
        '{"kv_connector": "MooncakeConnectorV1",
        "kv_role": "kv_consumer",
        "kv_port": "56900",
        "engine_id": "1",
        "kv_connector_extra_config": {
             "use_ascend_direct": true,
             "prefill": {"dp_size": 2, "tp_size": 8},
             "decode":  {"dp_size": 2, "tp_size": 8}
        }}'

脚本准备就绪后，在每个节点上启动服务器。

Prefill 节点：

python launch_online_dp.py \
    --dp-size 2 --tp-size 8 \
    --dp-size-local 2 --dp-rank-start 0 \
    --dp-address <prefill_ip> --dp-rpc-port 12321 \
    --vllm-start-port 7000

Decode 节点：

python launch_online_dp.py \
    --dp-size 2 --tp-size 8 \
    --dp-size-local 2 --dp-rank-start 0 \
    --dp-address <decode_ip> --dp-rpc-port 12321 \
    --vllm-start-port 7100

请求转发

在能够访问两个节点的任意机器上运行代理。您可以从仓库获取代理脚本：load_balance_proxy_server_example.py。

unset http_proxy https_proxy

python load_balance_proxy_server_example.py \
    --port 8009 \
    --host <prefill_ip> \
    --prefiller-hosts \
       <prefill_ip> <prefill_ip> \
    --prefiller-ports \
       7000 7001 \
    --decoder-hosts \
       <decode_ip> <decode_ip> \
    --decoder-ports \
       7100 7101

然后可以通过 http://<proxy_ip>:8009 访问服务。

6 功能验证

服务器启动后，您可以使用输入提示查询模型。

注意：

• <node_ip>：运行服务器的节点 IP 地址（例如单节点时为 localhost）。

• <port>：服务器启动命令中指定的端口号（例如 8000）。

使用 curl

curl http://<node_ip>:<port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M2.7",
    "messages": [{"role": "user", "content": "Hello, who are you?"}],
    "stream": false,
    "temperature": 0.8,
    "max_tokens": 200
  }'

预期结果：HTTP 200，JSON 响应中包含 choices 字段，其中包含模型的回复文本。

使用 OpenAI Python 客户端

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="na")

resp = client.chat.completions.create(
    model="MiniMax-M2.7",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己，并展示一次工具调用的参数格式。"}],
    max_tokens=256,
)
print(resp.choices[0].message.content)

预期结果：响应应在 content 字段中包含连贯的自我介绍和工具调用参数格式。

工具调用验证

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M2.7",
    "messages": [{"role": "user", "content": "请查询上海的天气。"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get weather by city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
          },
          "required": ["city"]
        }
      }
    }],
    "tool_choice": "auto",
    "temperature": 0,
    "max_tokens": 512
  }'

预期结果：HTTP 200，JSON 响应中包含 tool_calls 字段，其中包含函数名称和参数。

7 精度评估

注意：后处理参数（例如 max_tokens、temperature、stop tokens）应与模型权重的 generation_config.json 中定义的参数匹配。GPQA-diamond 和 AIME2025 的推荐最大输出长度为 64k（65536 tokens）。

以下是两种精度评估方法。

7.1 使用 AISBench

有关详细信息，请参考使用 AISBench。

7.2 使用 Language Model Evaluation Harness

以 gsm8k 数据集为例，在在线模式下运行 MiniMax-M2.7-W8A8 的精度评估。

1. 有关 lm_eval 的安装，请参考使用 lm_eval。

2. 运行 lm_eval 执行精度评估：

lm_eval \
  --model local-completions \
  --model_args model=/path/to/weight/MiniMax-M2.7-w8a8-QuaRot,base_url=http://127.0.0.1:8000/v1/completions,tokenized_requests=False,trust_remote_code=True \
  --tasks gsm8k \
  --output_path ./

8 性能评估

8.1 使用 AISBench

有关详细信息，请参考使用 AISBench 进行性能评估。

8.2 使用 vLLM Benchmark

以 MiniMax-M2.7-W8A8 为例运行性能评估。

有关更多详细信息，请参考 vllm benchmark。

以 serve 子命令为例：

export VLLM_USE_MODELSCOPE=True
vllm bench serve \
  --model /path/to/weight/MiniMax-M2.7-w8a8-QuaRot \
  --dataset-name random \
  --random-input 200 \
  --num-prompts 200 \
  --request-rate 1 \
  --save-result \
  --result-dir ./

9 性能调优

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

9.1 推荐配置

以下配置已在内部测试中验证，并按使用场景进行分类。

场景	输入/输出	部署	NPU	P 配置	D 配置	最大批处理 Tokens	最大序列数 (P/D)	最大模型长度	EAGLE3	FUSED_MC2	FlashComm1	异步调度
短序列高吞吐	3.5k → 1.5k	1P2D PD分离	24 (A3)	DP8TP2EP16	DP32TP1EP32	16384	128 / 128	32k	3	开启	开启	开启
短序列低时延	3.5k → 1.5k	1P2D PD分离	24 (A3)	DP4TP4EP16	DP8TP4EP32	16384	128 / 128	32k	3	开启	开启	开启
长序列高吞吐	128k → 1k （90% 缓存命中）	1P1D PD分离	16 (A3)	DP2TP8EP16	DP2TP8EP16	16384	64 / 16	200k	3	开启	开启	开启
长序列低时延	128k → 1k （90% 缓存命中）	1P2D PD分离	24 (A3)	DP2TP8EP16	DP4TP8EP32	16384	64 / 16	200k	3	开启	开启	开启

注意：短序列测试的前缀缓存命中率为0%，长序列测试为90%。请根据实际工作负载调整max-num-seqs、max-model-len和max-num-batched-tokens。

9.2 调优指南

9.2.1 通用调优参考

通用调优方法请参考公共性能调优文档。

详细功能描述请参考功能矩阵。

9.2.2 模型专属优化

默认启用的优化

以下优化默认启用，无需额外配置：

优化技术	技术原理	性能收益
全图优化	通过compilation_config={"cudagraph_mode":"FULL_DECODE_ONLY"}一次性捕获并重放整个解码图	显著降低调度时延，稳定多设备性能
CPU绑定	使用--additional-config '{"enable_cpu_binding":true}'绑定CPU核心	减少跨核调度开销，提升解码时延稳定性
多线程权重加载	使用--model-loader-extra-config '{"enable_multithread_load":true}'进行并行权重加载	减少模型加载时间

需显式启用的优化

优化技术	适用场景	启用方法	技术原理	注意事项
FlashComm v1	高并发、TP场景	--additional-config '{"enable_flashcomm1": true}'	将传统Allreduce分解为Reduce-Scatter和All-Gather	阈值保护：仅在实际token数超过阈值时生效
Fused MC2	TP ≥ 4场景	--additional-config '{"enable_fused_mc2": true}'	融合多个通信和计算操作	推荐A3使用，不适用于A2
均衡调度	高DP场景	export VLLM_ASCEND_BALANCE_SCHEDULING=1	增强prefill和decode之间的调度能力	当前默认关闭（0）。仅在并发数 ≈ DP × max-num-seqs时设为1。长上下文场景请关闭
EAGLE3投机解码	所有场景	--speculative_config '{"method": "eagle3", "model": "/path/to/Eagle3/", "num_speculative_tokens": 3}'	使用草稿模型预测未来token	长上下文1-3个token，短上下文3个token
jemalloc预加载	所有场景	export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libjemalloc.so.2	替换默认内存分配器以减少碎片	确保容器中已安装jemalloc

10 常见问题

常见环境、安装和通用参数问题请参考公共FAQ。本章仅涵盖MiniMax-M2（M2.5/M2.7）模型专属问题。

• 问：C8量化是否支持EAGLE3投机解码？

  答：暂不支持。当前不支持C8量化与EAGLE3同时使用。

• 问：工具调用任务推荐使用哪个--reasoning-parser？

  答：工具调用任务推荐使用--reasoning-parser minimax_m2_append_think。

• 问：使用 minimax_m2_append_think 时，为什么 reasoning 字段经常为空，我应该如何选择正确的 --reasoning-parser？

  答：这是预期行为。minimax_m2_append_think 解析器会将 <think>...</think> 块直接保留在 content 字段中，而不是将其分离出来。如果您的下游应用依赖于 /v1/responses 的标准推理语义（即思考过程和最终答案分离），则应使用 --reasoning-parser minimax_m2 以确保专用的 reasoning 字段被正确填充。

• 问：启动时出现HCCL端口冲突（地址已绑定）导致失败，该如何处理？

  答：检查是否有其他进程已占用该端口（例如 lsof -i :<port> 或 ss -tlnp | grep <port>）。若发现端口冲突，可通过 --port 切换至其他端口，或终止占用该端口的特定进程。

• 问：如何处理 OOM 或启动不稳定？

  答：请参考上游 vLLM 的内存不足故障排除指南。简而言之：首先减少 --max-num-seqs 和 --max-num-batched-tokens，降低 --gpu-memory-utilization（例如从 0.9 降至 0.85），或减少并发请求数量。

• 问：哪些端口必须可访问？

  答：至少需开放服务端口（例如 8000）。对于多节点部署，还需确保 HCCL 通信端口和 DP RPC 端口可访问。