miles-rl-training

miles: 大規模モデル学習向けのエンタープライズグレード RL

miles は、大規模モデルのポストトレーニングに最適化された、高性能でエンタープライズ対応の RL フレームワークです。slime の本番フォークとして構築されており、MoE 学習の安定性、低精度学習、学習と推論の整合性といった重要な課題に対応しています。

miles を使うべき場合

miles を選ぶべき場合:

• 1TB 以上の MoE モデル（DeepSeek V3、Qwen3-MoE）を学習する場合
• FP8 または INT4 の量子化を考慮した学習が必要な場合
• ビット単位で同一の学習・推論整合性が必要な場合
• 最大スループットのための投機的 RL が必要な場合
• エンタープライズサポートを伴う本番環境での安定性が必要な場合

代替案を検討すべき場合:

• 研究志向のオリジナル版が欲しい → slime を使用
• 柔軟なバックエンド切り替えが必要 → verl を使用
• PyTorch ネイティブの抽象化を求める → torchforge を使用

主な機能

低精度学習

• 統合 FP8: 推論と学習の両方でエンドツーエンドの FP8
• INT4 QAT: 単一マシンの VRAM（H200）で 1TB モデルを扱う
• Rollout Routing Replay (R3): MoE 向けのビット単位のエキスパート整合

パフォーマンス最適化

• 投機的 RL: オンライン SFT ドラフトモデルによりロールアウトを 25% 以上高速化
• ゼロコピー重み同期: CUDA IPC によるゼロコピーマッピング
• 部分ロールアウト: 途中まで完了した軌跡を再利用

学習・推論の整合性

• TIS/MIS: オフポリシー補正のための Truncated/Masked Importance Sampling
• カーネルレベルの最適化: FlashAttention-3、DeepGEMM の統合

インストール

# Recommended: Docker
docker pull radixark/miles:latest
docker run --rm --gpus all --ipc=host --shm-size=16g \
  -it radixark/miles:latest /bin/bash

# From source
git clone https://github.com/radixark/miles.git
cd miles
pip install -r requirements.txt
pip install -e .

クイックスタート

miles は slime の設定システムを引き継いでいます。基本的な学習:

python train.py \
    --advantage-estimator grpo \
    --model-name qwen3-30b-a3b \
    --hf-checkpoint /path/to/qwen3-30b-a3b-hf \
    --rollout-batch-size 512 \
    --n-samples-per-prompt 8

---

ワークフロー 1: 大規模 MoE 学習

DeepSeek V3 や Qwen3-MoE などの大規模 MoE モデルを学習する場合にこのワークフローを使用します。

前提条件チェックリスト

• FP8 に対応した H100/H200 GPU
• MoE モデル（DeepSeek V3、Qwen3-MoE）
• miles を含む Docker 環境

ステップ 1: 環境のセットアップ

# FP8 block scaling (recommended for stability)
export NVTE_FP8_BLOCK_SCALING_FP32_SCALES=1
export CUDA_DEVICE_MAX_CONNECTIONS=1

ステップ 2: 学習の設定

python train.py \
    --actor-num-gpus-per-node 8 \
    --rollout-num-gpus 8 \
    --hf-checkpoint /path/to/deepseek-v3 \
    --advantage-estimator grpo \
    --tensor-model-parallel-size 8 \
    --expert-model-parallel-size 4 \
    --prompt-data /path/to/data.jsonl \
    --num-rollout 3000

検証チェックリスト

• モデルがエラーなく読み込まれる
• ルーティングの判断が一貫している
• 損失値に NaN/Inf が含まれていない

---

ワークフロー 2: 投機的 RL 学習

EAGLE による投機的デコーディングで最大のロールアウトスループットを得たい場合にこのワークフローを使用します。

投機的 RL の仕組み

1. 小型のドラフトモデルが候補トークンを生成する
2. ターゲットモデルが並列に検証する
3. ドラフトモデルはオンライン SFT によりポリシーに追従するよう更新される

ステップ 1: 投機的デコーディングの有効化

miles は SGLang を介して EAGLE の投機的デコーディングをサポートしています。

python train.py \
    --actor-num-gpus-per-node 8 \
    --hf-checkpoint /path/to/target-model \
    --sglang-speculative-algorithm EAGLE \
    --sglang-speculative-num-steps 3 \
    --sglang-speculative-eagle-topk 1 \
    --sglang-speculative-num-draft-tokens 4 \
    --sglang-speculative-draft-model-path /path/to/draft-model \
    --advantage-estimator grpo \
    --prompt-data /path/to/data.jsonl

ステップ 2: オンライン MTP 学習の有効化（任意）

学習中にドラフトモデルをオンライン SFT する場合:

--mtp-num-layers 1 \
--enable-mtp-training \
--mtp-loss-scaling-factor 0.2

注意: オンライン MTP 学習には MTP の重みを含む torch dist チェックポイントが必要です。HuggingFace からのチェックポイント変換時に --mtp-num-layers 1 を追加してください。

期待される高速化

• 標準ロールアウト: ベースライン
• 投機的 RL: ロールアウトが 25〜40% 高速
• 部分ロールアウトと併用: さらに 10〜15% のスループット向上

---

設定リファレンス

miles は slime の引数をすべて引き継いでいます。完全な一覧は slime API リファレンス を参照してください。

クラスターリソース（slime から）

--actor-num-nodes 1
--actor-num-gpus-per-node 8
--rollout-num-gpus 8
--rollout-num-gpus-per-engine 2
--colocate

Megatron の並列化（slime から）

--tensor-model-parallel-size 8
--pipeline-model-parallel-size 2
--expert-model-parallel-size 4    # MoE expert parallelism

投機的デコーディング（miles 固有）

--sglang-speculative-algorithm EAGLE
--sglang-speculative-num-steps 3
--sglang-speculative-eagle-topk 1
--sglang-speculative-num-draft-tokens 4
--sglang-enable-draft-weights-cpu-backup
--sglang-speculative-draft-model-path /your/draft/model/path

オンライン MTP 学習（miles 固有）

--mtp-num-layers 1
--enable-mtp-training
--mtp-loss-scaling-factor 0.2

---

主な機能（概念的な説明）

以下の機能は miles に文書化されていますが、具体的な CLI フラグは変わる可能性があります。最新の設定については miles リポジトリを参照してください。

統合 FP8 パイプライン

MoE モデルで RL の崩壊を招く量子化起因の不一致を解消する、エンドツーエンドの FP8 サンプリングと学習です。

Rollout Routing Replay (R3)

SGLang の推論中にエキスパートのルーティング判断を記録し、Megatron の学習中にそれを再生してビット単位のエキスパート整合を実現します。

R3 の仕組み:

1. SGLang の推論中に、エキスパートのルーティング判断が記録される
2. ルーティングの判断は sample.rollout_routed_experts に保存される
3. Megatron の学習中は、ルーティングを再計算する代わりに再生する
4. 学習と推論で同一のエキスパートが選択されることを保証する

INT4 量子化認識トレーニング

1TB超のモデルを単一マシンでデプロイできるようにします（例：H200 上）。

INT4 によるメモリ削減:

モデルサイズ	BF16 VRAM	INT4 VRAM	削減率
70B	140GB	45GB	3.1x
235B	470GB	150GB	3.1x
671B	1.3TB	420GB	3.1x

学習と推論の整合

miles は次の仕組みにより、学習と推論の間で「正確に 0 の KL ダイバージェンス」を実現します。

• Flash Attention 3
• DeepGEMM
• Thinking Machines Lab によるバッチ不変カーネル
• torch.compile 統合

---

サンプルデータ構造

miles は slime と同じ Sample データクラスを使用し、MoE ルーティングのリプレイ用に rollout_routed_experts フィールドを追加しています。

@dataclass
class Sample:
    prompt: str | list[dict]
    tokens: list[int]
    response: str
    reward: float | dict
    loss_mask: list[int]
    status: Status
    metadata: dict
    rollout_log_probs: list[float]
    rollout_routed_experts: list[list[int]]  # MoE routing for R3

完全な Sample の定義については、slime API リファレンス を参照してください。

---

よくある問題と解決策

問題：FP8 トレーニングの崩壊

症状: 損失が発散し、NaN 値が発生する

解決策:

• ブロックスケーリングを使用する：export NVTE_FP8_BLOCK_SCALING_FP32_SCALES=1
• 学習率を下げる：--lr 5e-7
• 学習と推論の間で MoE ルーティングが一貫していることを確認する

問題：投機的ドラフトのドリフト

症状: 時間の経過とともに受理率が低下する

解決策:

• オンライン MTP トレーニングを有効にして、ドラフトモデルを整合させ続ける
• 投機的ステップ数を減らす：--sglang-speculative-num-steps 2
• CPU バックアップを使用する：--sglang-enable-draft-weights-cpu-backup

問題：学習と推論の不一致

症状: ポリシーの発散、報酬の崩壊

解決策:

• オフポリシー補正に TIS を使用する：--use-tis --tis-threshold 0.9
• SGLang と Megatron の間で対数確率が一致することを検証する
• MoE モデルで R3 を有効にする

---

サポート対象モデル

ファミリー	モデル	MoE サポート
DeepSeek	R1, V3, V3.2	完全対応
Qwen	2, 2.5, 3（MoE を含む）	完全対応
Llama	3, 3.1, 3.3, 4	Dense のみ
Gemma	2, 3, 3N	Dense のみ
GLM	4.5, 4.6, 4.7	Dense のみ
MiniMax	M2, M2.1	完全対応

---

リソース

• GitHub: https://github.com/radixark/miles
• 紹介ブログ: https://lmsys.org/blog/2025-11-19-miles/
• Slime（上流）: https://github.com/THUDM/slime
• SGLang: https://github.com/sgl-project/sglang