Fix: DGX Spark公式手順に準拠（NGCイメージ + Rayクラスター構成）

dgx-spark-minimax-m25-reap.md

@@ -39,79 +39,151 @@ MiniMax-M2.5は、中国MiniMax社が開発したコーディング・エージ
 | GPU | Blackwell GPU × 2 |
 | メモリ | 256GB統合メモリ（LPDDR5x）|
 | ストレージ | 4TB NVMe × 2 |
-| ネットワーク | ConnectX-7 (クラスタ間接続) |
+| ネットワーク | ConnectX-7 (QSFP接続) |
 
-※ 単体構成（128GB）の場合は、より小さいREAP-139B版か量子化版を検討してください。
+---
+
+## 事前準備：ネットワーク構成
+
+デュアルSpark構成では、2台のノードをQSFPケーブルで物理接続する必要があります。
+
+詳細な手順は公式ドキュメントを参照してください：
+👉 [Connect two Sparks](https://build.nvidia.com/spark/connect-two-sparks)
+
+### 確認事項
+
+- QSFPケーブルによる物理接続
+- ネットワークインターフェース設定（自動または手動IP割当）
+- パスワードなしSSHの設定
+- ネットワーク疎通確認
 
 ---
 
 ## 環境構築
 
-### 1. システムアップデート
+### 1. Dockerグループの設定（初回のみ）
 
 ```bash
-sudo apt update && sudo apt upgrade -y
+sudo groupadd docker
+sudo usermod -aG docker $USER
+newgrp docker
 ```
 
-### 2. Python環境の準備
+### 2. NGC公式vLLMイメージの取得
+
+DGX Sparkではドライバー互換性の関係で、**必ずNGC公式イメージを使用**してください。
 
 ```bash
-# Python 3.11推奨
+# 両方のノードで実行
-sudo apt install python3.11 python3.11-venv python3-pip -y
+docker pull nvcr.io/nvidia/vllm:25.11-py3
-
+export VLLM_IMAGE=nvcr.io/nvidia/vllm:25.11-py3
-# 仮想環境作成
-python3.11 -m venv ~/minimax-env
-source ~/minimax-env/bin/activate
 ```
 
-### 3. vLLMのインストール
+### 3. クラスターデプロイスクリプトの取得
 
 ```bash
-# nightlyビルド推奨（最新モデル対応）
+# 両方のノードで実行
-pip install -U vllm --extra-index-url https://wheels.vllm.ai/nightly
+wget https://raw.githubusercontent.com/vllm-project/vllm/refs/heads/main/examples/online_serving/run_cluster.sh
-
+chmod +x run_cluster.sh
-# または検証済みバージョン
-export VLLM_COMMIT=dea63512bb9bdf7521d591546c52138d9d79e8ce
-pip install vllm \
-  --torch-backend=auto \
-  --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}
 ```
 
-### 4. 関連パッケージ
+---
+
+## Rayクラスターの起動
+
+### Node 1（ヘッドノード）の起動
 
 ```bash
-pip install transformers accelerate huggingface_hub
+# Node 1で実行
+
+# 高速インターフェースのIPアドレスを取得
+# ibdev2netdev で "(Up)" と表示されるインターフェースを使用
+export MN_IF_NAME=enp1s0f1np1
+export VLLM_HOST_IP=$(ip -4 addr show $MN_IF_NAME | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
+
+echo "Using interface $MN_IF_NAME with IP $VLLM_HOST_IP"
+
+bash run_cluster.sh $VLLM_IMAGE $VLLM_HOST_IP --head ~/.cache/huggingface \
+  -e VLLM_HOST_IP=$VLLM_HOST_IP \
+  -e UCX_NET_DEVICES=$MN_IF_NAME \
+  -e NCCL_SOCKET_IFNAME=$MN_IF_NAME \
+  -e OMPI_MCA_btl_tcp_if_include=$MN_IF_NAME \
+  -e GLOO_SOCKET_IFNAME=$MN_IF_NAME \
+  -e TP_SOCKET_IFNAME=$MN_IF_NAME \
+  -e RAY_memory_monitor_refresh_ms=0 \
+  -e MASTER_ADDR=$VLLM_HOST_IP
 ```
 
+### Node 2（ワーカーノード）の起動
+
+```bash
+# Node 2で実行
+
+export MN_IF_NAME=enp1s0f1np1
+export VLLM_HOST_IP=$(ip -4 addr show $MN_IF_NAME | grep -oP '(?<=inet\s)\d+(\.\d+){3}')
+
+# 重要：Node 1のIPアドレスを設定
+# Node 1で `echo $VLLM_HOST_IP` を実行して確認
+export HEAD_NODE_IP=<NODE_1_IP_ADDRESS>
+
+echo "Worker IP: $VLLM_HOST_IP, connecting to head node at: $HEAD_NODE_IP"
+
+bash run_cluster.sh $VLLM_IMAGE $HEAD_NODE_IP --worker ~/.cache/huggingface \
+  -e VLLM_HOST_IP=$VLLM_HOST_IP \
+  -e UCX_NET_DEVICES=$MN_IF_NAME \
+  -e NCCL_SOCKET_IFNAME=$MN_IF_NAME \
+  -e OMPI_MCA_btl_tcp_if_include=$MN_IF_NAME \
+  -e GLOO_SOCKET_IFNAME=$MN_IF_NAME \
+  -e TP_SOCKET_IFNAME=$MN_IF_NAME \
+  -e RAY_memory_monitor_refresh_ms=0 \
+  -e MASTER_ADDR=$HEAD_NODE_IP
+```
+
+### クラスター状態の確認
+
+```bash
+# Node 1で実行
+export VLLM_CONTAINER=$(docker ps --format '{{.Names}}' | grep -E '^node-[0-9]+$')
+echo "Found container: $VLLM_CONTAINER"
+
+docker exec $VLLM_CONTAINER ray status
+```
+
+2ノードが認識され、GPUリソースが利用可能と表示されればOKです。
+
 ---
 
 ## モデルのダウンロード
 
-### Hugging Face CLIでダウンロード
+### Hugging Faceへのログイン
 
 ```bash
-# ログイン（初回のみ）
+# Node 1のコンテナ内で実行
-huggingface-cli login
+export VLLM_CONTAINER=$(docker ps --format '{{.Names}}' | grep -E '^node-[0-9]+$')
+docker exec -it $VLLM_CONTAINER /bin/bash
 
-# モデルダウンロード（約330GB、時間かかります）
+# コンテナ内で
-huggingface-cli download cerebras/MiniMax-M2.5-REAP-172B-A10B \
+huggingface-cli login
-  --local-dir ~/models/MiniMax-M2.5-REAP-172B-A10B
 ```
 
-### ダウンロード時間の目安
+### MiniMax-M2.5-REAP-172Bのダウンロード
 
-| 回線速度 | 所要時間 |
+```bash
-|---------|---------|
+# コンテナ内で（約330GB、時間がかかります）
-| 1Gbps | 約45分 |
+huggingface-cli download cerebras/MiniMax-M2.5-REAP-172B-A10B
-| 10Gbps | 約5分 |
+```
 
 ---
 
-## モデルの起動
+## 推論サーバーの起動
 
-### 基本起動コマンド（デュアル構成・256GB）
+### MiniMax-M2.5-REAP-172B用の起動コマンド
 
 ```bash
+# Node 1で実行
+export VLLM_CONTAINER=$(docker ps --format '{{.Names}}' | grep -E '^node-[0-9]+$')
+
+docker exec -it $VLLM_CONTAINER /bin/bash -c '
   vllm serve cerebras/MiniMax-M2.5-REAP-172B-A10B \
     --tensor-parallel-size 2 \
     --tool-call-parser minimax_m2 \
@@ -119,7 +191,7 @@ vllm serve cerebras/MiniMax-M2.5-REAP-172B-A10B \
     --trust-remote-code \
     --enable-auto-tool-choice \
     --max-model-len 65536 \
-  --gpu-memory-utilization 0.90
+    --gpu-memory-utilization 0.90'
 ```
 
 ### パラメータ解説
@@ -135,6 +207,7 @@ vllm serve cerebras/MiniMax-M2.5-REAP-172B-A10B \
 ### メモリ節約版（長文不要な場合）
 
 ```bash
+docker exec -it $VLLM_CONTAINER /bin/bash -c '
   vllm serve cerebras/MiniMax-M2.5-REAP-172B-A10B \
     --tensor-parallel-size 2 \
     --tool-call-parser minimax_m2 \
@@ -143,7 +216,7 @@ vllm serve cerebras/MiniMax-M2.5-REAP-172B-A10B \
     --enable-auto-tool-choice \
     --max-model-len 16384 \
     --max-num-seqs 32 \
-  --gpu-memory-utilization 0.85
+    --gpu-memory-utilization 0.85'
 ```
 
 ---
@@ -166,50 +239,32 @@ curl http://localhost:8000/v1/chat/completions \
   }'
 ```
 
-### Pythonクライアント
+### ヘルスチェック
 
-```python
+```bash
-from openai import OpenAI
+curl http://localhost:8000/health
-
-client = OpenAI(
-    base_url="http://localhost:8000/v1",
-    api_key="dummy"  # vLLMはAPIキー不要
-)
-
-response = client.chat.completions.create(
-    model="cerebras/MiniMax-M2.5-REAP-172B-A10B",
-    messages=[
-        {"role": "user", "content": "SWE-benchスタイルのバグ修正タスクをシミュレートして"}
-    ],
-    temperature=1.0,
-    top_p=0.95
-)
-
-print(response.choices[0].message.content)
 ```
 
 ---
 
-## パフォーマンスチューニング
+## 監視とデバッグ
 
-### 推奨設定
+### Rayダッシュボード
 
-```bash
+```
-# 環境変数でCUDAグラフ最適化
+http://<head-node-ip>:8265
-export VLLM_ATTENTION_BACKEND=FLASHINFER
-
-# DeepGEMMを有効化（要インストール）
-./tools/install_deepgemm.sh
 ```
 
-### 期待されるスループット
+### GPU使用状況の確認
 
-| 設定 | Input/Output | スループット |
+```bash
-|------|-------------|-------------|
+# 両ノードで
-| TP=2, 64K context | 2048/1024 | ~100 tok/s |
+nvidia-smi
-| TP=2, 16K context | 2048/1024 | ~150 tok/s |
 
-※ 実測値は環境により変動します
+# コンテナ内から
+export VLLM_CONTAINER=$(docker ps --format '{{.Names}}' | grep -E '^node-[0-9]+$')
+docker exec $VLLM_CONTAINER nvidia-smi --query-gpu=memory.used,memory.total --format=csv
+```
 
 ---
 
@@ -235,11 +290,18 @@ export VLLM_ATTENTION_BACKEND=FLASHINFER
 --compilation-config "{\"cudagraph_mode\": \"PIECEWISE\"}"
 ```
 
-### 出力が文字化け/破損する
+### Rayクラスターに接続できない
 
 ```bash
-# vLLMを最新のnightlyに更新
+# ネットワークインターフェースの確認
-pip install -U vllm --extra-index-url https://wheels.vllm.ai/nightly
+ibdev2netdev
+
+# ファイアウォールの確認
+sudo ufw status
+
+# Rayポートの開放（必要な場合）
+sudo ufw allow 6379
+sudo ufw allow 8265
 ```
 
 ---
@@ -258,15 +320,26 @@ content = response.replace(r'<think>.*?</think>', '')
 history.append({"role": "assistant", "content": response})
 ```
 
+### 推奨推論パラメータ
+
+```json
+{
+  "temperature": 1.0,
+  "top_p": 0.95,
+  "top_k": 40
+}
+```
+
 ---
 
 ## まとめ
 
-DGX Sparkデュアル構成（256GB）があれば、最新のMiniMax-M2.5-REAP-172Bが快適に動作します。オープンソースモデルとしてはトップクラスのコーディング・エージェント性能を持つこのモデル、ぜひ試してみてください。
+DGX Sparkデュアル構成（256GB）とNGC公式vLLMイメージを使えば、最新のMiniMax-M2.5-REAP-172Bが快適に動作します。オープンソースモデルとしてはトップクラスのコーディング・エージェント性能を持つこのモデル、ぜひ試してみてください。
 
 ### 参考リンク
 
 - [MiniMax-M2.5-REAP-172B (Hugging Face)](https://huggingface.co/cerebras/MiniMax-M2.5-REAP-172B-A10B)
+- [DGX Spark vLLM公式ガイド](https://build.nvidia.com/spark/vllm/stacked-sparks)
 - [MiniMax-M2 公式リポジトリ (GitHub)](https://github.com/MiniMax-AI/MiniMax-M2)
 - [vLLM MiniMax-M2 デプロイガイド](https://docs.vllm.ai/projects/recipes/en/latest/MiniMax/MiniMax-M2.html)
 - [REAP論文 (arXiv)](https://arxiv.org/abs/2510.13999)