用 vLLM 部署 MiniMax M3 並開啟 OpenAI API

這篇教你用 vLLM 在本機或伺服器部署 MiniMax M3，並開出相容 OpenAI 的 API 端點。

這份操作指南是給想把 MiniMax M3 以服務形式跑起來的開發者。照著做完，你會得到一個可用的模型伺服器、已啟用工具呼叫與推理解析的設定，以及一組可以直接驗證連線的測試指令。

你也會清楚知道部署時最重要的幾個元件：GPU 存取、Hugging Face 快取掛載、張量平行設定，還有 vLLM 針對 MiniMax M3 所需的啟動參數。

開始之前

• 已安裝 Docker 24+。
• 主機具備 NVIDIA GPU，且驅動已支援 CUDA。
• 至少 1 張 GPU；示範的張量平行設定建議 8 張 GPU。
• 已申請 Hugging Face 帳號，並可存取 MiniMaxAI/MiniMax-M3-MXFP8 模型。
• 本機已完成 huggingface-cli login，或已準備等效的祕密掛載。
• Linux 主機可使用 --privileged 與 --ipc=host 參數。
• 磁碟空間充足，建議至少保留 100 GB 可用空間。

Step 1: 下載 vLLM 映像檔

這一步的目的，是先準備好已包含 OpenAI 相容伺服器進入點的容器映像檔，讓後續啟動時不用額外拼裝執行環境。

docker pull vllm/vllm-openai:minimax-m3

驗收方式很簡單：下載完成後，執行 docker images，你應該看到 vllm/vllm-openai 與 minimax-m3 標籤出現在清單中。

Step 2: 建立 Hugging Face 快取資料夾

這一步的目的，是把模型權重與 token 快取固定在主機上，避免每次重啟容器都重新下載。

mkdir -p ~/.cache/huggingface

接著確認你已經登入 Hugging Face，或已把 token 以祕密掛載方式提供給容器。驗收時，你應該能在 ~/.cache/huggingface 看到快取目錄，第一次下載模型後也會出現對應檔案。

Step 3: 啟動 MiniMax M3 服務

這一步的目的，是把 MiniMax M3 以 API 服務形式跑起來，並套用 vLLM 對應的模型參數與解析器設定。

docker run --gpus all --privileged --ipc=host -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:minimax-m3 MiniMaxAI/MiniMax-M3-MXFP8 \
  --block-size 128 \
  --tensor-parallel-size 8 \
  --tool-call-parser minimax_m3 \
  --enable-auto-tool-choice \
  --reasoning-parser minimax_m3

驗收時，你應該看到 vLLM 日誌出現模型載入、tokenizer 初始化，以及伺服器綁定到 0.0.0.0:8000。如果模型正在下載，前面會先出現進度輸出，這是正常現象。

Step 4: 查詢模型清單端點

這一步的目的，是確認 OpenAI 相容路徑真的有回應，而不是只有容器在背景執行。

curl http://localhost:8000/v1/models

驗收時，你應該看到一段 JSON 回應，內容包含已載入的模型或可用模型項目。只要這個端點能正常回應，就代表服務已經可被外部呼叫。

Step 5: 測試聊天與工具呼叫

這一步的目的，是確認 MiniMax M3 的工具呼叫與推理解析路徑都已啟用，之後才能接到代理人框架或自訂客戶端。

curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMaxAI/MiniMax-M3-MXFP8",
    "messages": [{"role": "user", "content": "列出你會用來檢查程式碼庫的兩種工具。"}],
    "max_tokens": 64
  }'

驗收時，你應該看到聊天完成回應，而不是錯誤訊息；同時伺服器日誌也應顯示請求有走進 MiniMax M3 的解析流程。這表示你的端點已經可以交給應用程式直接使用。

常見錯誤

• 模型名稱打錯。修法：請完整使用 MiniMaxAI/MiniMax-M3-MXFP8，除非 vLLM 官方文件有更新。
• Docker 沒有 GPU 權限。修法：安裝 NVIDIA Container Toolkit，並重新以 --gpus all 啟動。
• 張量平行數大於可見 GPU 數。修法：把 --tensor-parallel-size 調整為實際可用 GPU 數量，或在較小機器上降低設定。

接下來可以看什麼

當服務穩定後，下一步可以把代理人框架或客戶端 SDK 接到 http://localhost:8000/v1，再依照 vLLM recipe 與 MiniMax M3 的說明，調整上下文長度、批次處理與 GPU 記憶體設定。