vllm-plugin-fl-setup-flagos

vLLM-Plugin-FL 安装

概述

vLLM-Plugin-FL 通过 FlagOS 统一算子库 FlagGems 和通信库 FlagCX 扩展 vLLM，以支持在多种硬件后端（NVIDIA、Ascend、MetaX、Iluvatar 等）上进行模型推理和服务。本指南介绍安装、硬件专属环境配置和依赖项设置。

先决条件

• Linux 操作系统（推荐 Ubuntu 20.04+）
• Python 3.10+
• vLLM v0.13.0 — 从官方 v0.13.0 release 或分支 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 特定问题：请参阅 references/npu.md，了解 Ascend NPU 故障排除信息，包括 FlagTree 设置和 eager 执行要求。

无法连接到 GitHub：请用户提供网络代理设置（例如 http_proxy / https_proxy），配置代理后重试 git clone 命令。

参考资料

• vLLM-Plugin-FL GitHub
• FlagGems GitHub
• FlagCX GitHub
• 对于非 NVIDIA 芯片，请参阅 references 目录，了解特定硬件的配置和设置说明