vllm-plugin-fl-setup-flagos

vLLM-Plugin-FL のセットアップ

概要

vLLM-Plugin-FL は、FlagOS の統合オペレーターライブラリ FlagGems と通信ライブラリ FlagCX を通じて、さまざまなハードウェアバックエンド（NVIDIA、Ascend、MetaX、Iluvatar など）でのモデル推論／サービングをサポートするよう vLLM を拡張します。このスキルでは、インストール、ハードウェア固有の環境設定、依存関係のセットアップについて説明します。

前提条件

• Linux OS（Ubuntu 20.04 以降を推奨）
• Python 3.10 以降
• vLLM v0.13.0 — 公式の v0.13.0 リリース またはフォーク版 vllm-FL からインストールします
• 適切なドライバーを備えた GPU（NVIDIA CUDA、Huawei Ascend など）
• pip パッケージマネージャー
• Git

続行する前に、vLLM のバージョンを確認します。

python -c "import vllm; print(vllm.__version__)"
# Expected output: 0.13.0

インストールの手順

ステップ 1：ハードウェアバックエンドを特定する

# NVIDIA GPU
nvidia-smi

# Huawei NPU
npu-smi info

# Moore Threads GPU
mthreads-gmi

# Iluvatar GPU
ixsmi

ステップ 2：vLLM-Plugin-FL をインストールする

まずワークスペースディレクトリを作成し、ソースコードのクローンを試みます。

mkdir -p ~/flagos-workspace && cd ~/flagos-workspace
git clone https://github.com/flagos-ai/vllm-plugin-FL

ネットワークの問題で git clone に失敗した場合は、ユーザーにネットワークプロキシの設定（例：http_proxy／https_proxy）を尋ね、プロキシを設定してから、もう一度クローンを試します。

次に、ソースディレクトリからインストールします。

cd vllm-plugin-FL
pip install -r requirements.txt
pip install --no-build-isolation .
# Required to enable vLLM-Plugin-FL when running vLLM
export VLLM_PLUGINS='fl'

vLLM-Plugin-FL のインストールを確認します。

python -c "import vllm_fl; print('vllm-plugin-FL installed successfully')"

ステップ 3：FlagGems をインストールする

Ascend NPU ユーザーの方へ： FlagGems をインストールする前に、必ず FlagTree をインストールしてください。references/npu.md を参照し、先にそちらの FlagTree のインストール手順を完了してください。完了しないと、FlagGems の検証が繰り返し失敗し、Triton が再インストールされ続けます。

# Install build dependencies
pip install -U scikit-build-core==0.11 pybind11 ninja cmake

# Clone FlagGems source code
cd ~/flagos-workspace
git clone https://github.com/flagos-ai/FlagGems

ネットワークの問題で git clone に失敗した場合は、ユーザーにネットワークプロキシの設定（例：http_proxy／https_proxy）を尋ね、プロキシを設定してから、もう一度クローンを試します。

次に、ソースディレクトリからインストールします。

cd FlagGems
pip install --no-build-isolation .

FlagGems のインストールを確認します。

python -c "import flag_gems; print('FlagGems installed successfully')"

ステップ 4：（任意）FlagCX をインストールする

FlagCX は、同種および異種の構成に対応した、複数デバイスでの分散推論向け統合通信ライブラリです。単一デバイスで実行する場合は、この手順をスキップしてください。

注記： Ascend NPU では FlagCX は不要です。Ascend バックエンドの場合は、この手順をスキップしてください。

cd ~/flagos-workspace
git clone https://github.com/flagos-ai/FlagCX.git

ネットワークの問題で git clone に失敗した場合は、ユーザーにネットワークプロキシの設定（例：http_proxy／https_proxy）を尋ね、プロキシを設定してから、もう一度クローンを試します。

次に、ソースディレクトリからビルドしてインストールします。

cd FlagCX

git submodule update --init --recursive

# Build for your platform (e.g. USE_NVIDIA=1 for NVIDIA)
make USE_NVIDIA=1

export FLAGCX_PATH="$PWD"

# Install Python binding (replace [xxx] with your platform: nvidia, ascend, etc.)
cd plugin/torch/
FLAGCX_ADAPTOR=[xxx] pip install --no-build-isolation .

FlagCX のインストールを確認します。

python -c "import flagcx; print('FlagCX installed successfully')"

ステップ 5：バックエンド固有のセットアップ

一部のハードウェアバックエンドでは、追加のセットアップが必要です。該当するリファレンスドキュメントを参照してください。

バックエンド	チップベンダー	リファレンス
Ascend NPU	Huawei	references/npu.md
MetaX GPU	MetaX	TBD
Iluvatar GPU (BI-V150)	Iluvatar	references/iluvatar_gpu.md
Pingtouge-Zhenwu	Pingtouge	TBD
Tsingmicro	Tsingmicro	TBD
Moore Threads GPU	Moore Threads	references/mthreads_gpu.md
Hygon DCU	Hygon	TBD

クイックテスト

1. テストするモデル名（例：Qwen3-4B、DeepSeek-R1）をユーザーに尋ねます。
2. マシン上にそのモデルのローカルコピーがあるか検索します。

   find / -maxdepth 5 -type d -name "<user_provided_model_name>" 2>/dev/null
   

3. 見つかった場合は、そのパスを使用します。見つからなかった場合は、ユーザーにその旨を伝え、別のモデル名またはローカルのフルパスを指定してもらってから、再度検索します。3 回試しても有効なモデルが見つからない場合は、クイックテストをスキップし、再試行する前にモデルを準備するようユーザーに伝えます。
4. 推論を実行する前に、FL プラグインが有効になっていることを確認します。

   export VLLM_PLUGINS='fl'
   

   Moore Threads GPU の場合は、さらに次の設定を行います。

   export USE_FLAGGEMS=1
   export FLAGCX_PATH=/workspace/FlagCX  # MUST point to the actual FlagCX installation directory; this is only an example
   export VLLM_MUSA_ENABLE_MOE_TRITON=1
   

5. 有効なモデルパスを確定したら、オフラインのバッチ推論を実行して、スタック全体を検証します。

from vllm import LLM, SamplingParams

model_path = "<resolved_model_path>"
prompts = [
    "Hello, my name is",
]
sampling_params = SamplingParams(max_tokens=10, temperature=0.0)

# For Moore Threads GPU, add: enforce_eager=True, block_size=64, attention_config={"backend": "TORCH_SDPA"}
# For Iluvatar BI-V150, add: enforce_eager=True
llm = LLM(model=model_path, max_num_batched_tokens=16384, max_num_seqs=2048)
outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

トラブルシューティング

モデル読み込み時のメモリ不足：gpu_memory_utilization パラメーターを使用して、メモリ使用量を制限してください。まずは 0.8 に設定し、調整してください。

from vllm import LLM
llm = LLM(model="...", gpu_memory_utilization=0.8)

FlagGems のビルド失敗：ビルド依存関係（scikit-build-core、pybind11、ninja、cmake）がインストールされていることを確認してください。また、コンパイラーが C++17 に対応していることを確認してください。

プラグインが読み込まれない：vLLM が FL プラグインを使用しない場合は、環境で VLLM_PLUGINS='fl' が設定されていることを確認してください。

FlagCX の通信エラー：FLAGCX_PATH が正しく設定され、ライブラリが使用するプラットフォーム向けにビルドされていることを確認してください。NVIDIA の場合は、make USE_NVIDIA=1 で確認してください。

Ascend 固有の問題：FlagTree のセットアップや Eager Execution の要件など、Ascend NPU のトラブルシューティングについては references/npu.md を参照してください。

GitHub に接続できない：ネットワークのプロキシ設定（例：http_proxy／https_proxy）をユーザーに確認し、プロキシを設定してから、git clone コマンドを再試行してください。

参考資料

• vLLM-Plugin-FL GitHub
• FlagGems GitHub
• FlagCX GitHub
• NVIDIA 以外のチップについては、ハードウェア固有の設定とセットアップ手順が記載されている references ディレクトリを参照してください