MiniMax-M3 用 vLLM 部署

这篇适合谁

适合手上有 4 张或 8 张 GPU、想在自己的机器或服务器上跑 MiniMax-M3，并希望用 OpenAI 兼容接口调用它的开发者。读完你应该能用 vLLM 启动模型服务，并用 Python 或 curl 发出对话和图片输入请求。

MiniMax-M3 和 vLLM 各是什么

MiniMax-M3 是 MiniMax 推出的开源大语言模型。它的上下文窗口扩展到 512K，单次最多输出 128K，并支持图片输入^[1]。图片输入可以通过 OpenAI 兼容和 Anthropic 兼容两套接口使用，视频、音频和文档目前还不支持^[1]。官方代码仓库在 GitHub 的 MiniMax-AI/MiniMax-M3，模型页在 Hugging Face 的 MiniMaxAI/MiniMax-M3^[2]。

vLLM 是面向大语言模型的高性能推理框架，开箱即用，提供 OpenAI 兼容接口。它支持长上下文推理、流式输出、工具调用，以及对思考内容的解析^[1]^[3]。多卡运行时可以用张量并行（tensor parallelism）或专家并行（expert parallelism）。张量并行把模型的计算拆到多张卡上，4 卡示例用的是这种方式；8 卡示例在此基础上还开启了专家并行^[1]。

准备工作

先看显存，它决定模型能不能跑起来。官方给出的数字是：权重约需 220 GB 显存，每 1M 上下文 token 约需 240 GB 显存^[1]。按 96 GB 显存的 4 张卡算，总上下文容量约 40 万 token；按 144 GB 显存的 8 张卡算，约 300 万 token^[1]。这些是硬件能支持的最大缓存总量，不是单个请求的上限。实际部署时，要根据同时在线的请求数和每个请求的上下文长度重新估算，再决定用几张卡。

环境方面，先用 nvidia-smi 确认所有显卡都被系统识别，再用 PyTorch 检查 CUDA 是否可用^[1]。Python 环境建议用 venv、conda 或 uv 单独建一个虚拟环境，避免和其他项目的依赖互相冲突^[1]。

上手步骤

检查显卡和 CUDA。nvidia-smi 应能列出 4 张或 8 张卡，PyTorch 的 CUDA 检测结果为 True。
创建虚拟环境并安装 vLLM。用 uv 的命令如下^[1]：

uv venv
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

前两行建立并激活虚拟环境，最后一行安装 vLLM，其中的 --torch-backend=auto 照写即可^[1]。

下载模型（可选）。vLLM 首次启动时会自动从 Hugging Face 拉取并缓存模型，所以不一定要提前下载。如果想先下好，或者 Hugging Face 访问不稳定，可以用 ModelScope 下载^[1]：

pip install modelscope
python model_download.py

下载脚本调用的是 modelscope 包里的 snapshot_download，模型 ID 是 MiniMaxAI/MiniMax-M3，revision 为 master^[1]。用 ModelScope 下载时不需要设置 HF 镜像。如果让 vLLM 直接从 Hugging Face 拉取、而网络受限，可以先执行 export HF_ENDPOINT=https://hf-mirror.com^[1]。

启动服务。4 卡部署的命令是^[1]：

SAFETENSORS_FAST_GPU=1 vllm serve \
    MiniMaxAI/MiniMax-M3 --trust-remote-code \
    --tensor-parallel-size 4 \
    --enable-auto-tool-choice --tool-call-parser minimax_m2 \
    --reasoning-parser minimax_m2_append_think

8 卡部署在命令里加上 --enable_expert_parallel，并把张量并行大小设为 8^[1]：

SAFETENSORS_FAST_GPU=1 vllm serve \
    MiniMaxAI/MiniMax-M3 --trust-remote-code \
    --enable_expert_parallel --tensor-parallel-size 8 \
    --enable-auto-tool-choice --tool-call-parser minimax_m2 \
    --reasoning-parser minimax_m2_append_think

首次加载非常慢，可能超过半小时^[1]。服务启动后监听 http://127.0.0.1:8000/v1^[1]，后面所有客户端都用这个地址作为 base_url。

用 curl 测试。向聊天接口发送一条请求，能返回模型的回答，就说明服务正常^[1]：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-M3",
    "messages": [
      {"role": "system", "content": [{"type": "text", "text": "You are a helpful assistant."}]},
      {"role": "user", "content": [{"type": "text", "text": "请简要介绍 MiniMax-M3 模型的特点。"}]}
    ]
  }'

用 Python 调用。OpenAI 官方 Python SDK 只需把 base_url 指向本地服务，api_key 填任意字符串即可^[1]：

# test_chat.py
from openai import OpenAI

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

response = client.chat.completions.create(
    model="MiniMaxAI/MiniMax-M3",
    messages=[
        {"role": "user", "content": "请介绍 MiniMax-M3 相比 M2.5 有哪些提升？"}
    ],
    max_tokens=8192,
    top_p=0.95,
    temperature=1.0,
)

msg = response.choices[0].message
print("MiniMax-M3:", msg.content)

代码里的 response.choices[0].message 是模型的回复，msg.content 是其中的文本^[1]。官方推荐的采样参数是 temperature 1.0、top_p 0.95、top_k 20^[1]。max_tokens 控制生成长度，M3 最多能输出 128K，但设得过大会增加显存占用和延迟^[1]。

图片输入

图片输入要放在 user 消息的 content 数组里，和一段文字并列，作为一个 image_url 项^[1]。目前只支持图片，视频、音频和文档都不支持^[1]。如果要让模型理解文档，需要先自己把内容转成文字或图片，再交给模型。

工具调用和思考内容

工具调用要在服务端开启。--enable-auto-tool-choice 让模型在需要时自己发起工具调用，--tool-call-parser minimax_m2 指定 MiniMax 的解析器，--reasoning-parser minimax_m2_append_think 用于解析思考内容^[1]。这三个参数已经包含在前面的启动命令里，直接使用即可。

常见问题

Hugging Face 下载慢或连不上：改用 ModelScope 下载，或设置 HF_ENDPOINT 镜像^[1]。
报错 "MiniMax-M3 model is not currently supported"：vLLM 版本太旧，执行 pip install -U vllm 升级^[1]。
CUDA 内存错误（torch.AcceleratorError）：在启动参数里加上 --compilation-config "{\"cudagraph_mode\": \"PIECEWISE\"}"^[1]。
输出乱码：升级到与 MiniMax-M3 匹配的最新 vLLM 版本^[1]。