FlagOS + FlagTree 安装部署指南

概念说明 FlagOS：是一整套面向异构AI芯片的系统软件栈，包含 FlagTree（多后端编译器，基于Triton二次开发）、FlagGems算子库、FlagCX通信库、vllm‑plugin‑FL等组件。 FlagTree：FlagOS 的核心编译器，实现"一次编写，多芯片运行"，替代原生 triton，支持英伟达、昇腾、海光、天数智芯、摩尔线程等硬件。
环境前置要求

操作系统：Ubuntu 22.04 Linux（推荐）；Windows 需要 WSL2；macOS 支持有限不推荐。
Python：3.10 / 3.11
硬件：对应AI芯片的驱动、SDK必须提前装好（如CUDA12.x、昇腾CANN、海光HCU SDK等）
两种部署方式：预编译whl快速安装（推荐） 、源码编译安装 、Docker镜像部署。

方式一：预编译wheel包快速安装（NVIDIA GPU示例，最省事）

⚠️必须先卸载系统原有triton，FlagTree是替换triton的实现。

python 复制代码

# 1. 创建conda虚拟环境
conda create -n flagos_env python=3.10
conda activate flagos_env

# 2. 卸载原生triton
pip uninstall -y triton triton‑language

# 3. 安装 FlagTree（智源私有源，版本0.6.0）
pip install flagtree==0.6.0 --index-url=https://resource.flagos.net/repository/flagos-pypi-hosted/simple

# 4. 安装 FlagGems（高性能算子库，FlagOS必备）
git clone https://github.com/flagos-ai/FlagGems.git
cd FlagGems
git checkout v5.3.0
pip install --no-build-isolation -e .

#（可选）vLLM‑plugin‑FL：对接vLLM推理框架
git clone https://github.com/flagos-ai/vllm-plugin-FL.git
cd vllm-plugin-FL
pip install vllm==0.20.2
pip install --no-build-isolation -e .

验证安装

python 复制代码

python -c "import flagtree; print(flagtree.__version__)"
python -c "import triton; print(triton.__version__)"
# 输出版本号无报错代表安装成功

切换硬件后端：通过环境变量选择芯片后端

python 复制代码

export FLAGTREE_BACKEND=nvidia   #可选 nvidia / ascend / hcu / iluvatar / mthreads
python your_kernel.py

方式二：源码编译 FlagTree（适合二次开发，编译耗时久）

python 复制代码

git clone https://github.com/flagos-ai/FlagTree.git
cd FlagTree

# 根据你的硬件选择分支
# main：通用；triton_v3.5.x、triton_v3.6.x 对应不同Triton版本
git checkout triton_v3.6.x

# 编译，需要系统安装 cmake clang llvm
apt update && apt install cmake clang libclang‑dev

# 本地可编辑模式编译安装
pip install --no-build-isolation -e .

⚠️源码编译会编译LLVM，8‑30分钟，内存建议≥16G。不同芯片后端看官方wiki对应分支说明。

方式三：Docker镜像部署（官方预构建镜像，环境零污染）

官方提供打包好的镜像，内置FlagOS+FlagTree+FlagGems，适合多芯片开发环境。

python 复制代码

# 下载镜像包（以HCU海光镜像举例，其他芯片镜像看wiki）
wget https://baai‑cp‑web.ks3‑cn‑beijing.ksyuncs.com/trans/flagtree‑hcu3.0‑py310‑torch2.4.1‑ubuntu22.04.202603.tar.gz

docker load -i flagtree‑hcu3.0‑py310‑torch2.4.1‑ubuntu22.04.202603.tar.gz

# 启动容器，透传硬件设备
docker run -dit \
  --network=host --ipc=host --privileged=true \
  -v /data:/data \
  --name flagos‑dev flagtree‑hcu3.0‑py310‑torch2.4.1‑ubuntu22.04:202603

docker exec -it flagos‑dev bash

完整 FlagOS 软件栈组件清单

组件	作用
FlagTree	多后端编译器，替换triton，算子编译
FlagGems	预优化算子库，矩阵乘、FlashAttention等
FlagCX	跨芯片多机通信库（可选，多卡分布式）
vllm‑plugin‑FL	vLLM异构硬件插件，大模型推理
FlagScale	自动并行调度库

常见坑点

不要同时装 triton 和 flagtree：flagtree 接管 triton 的Python入口，版本冲突会直接crash。
不同芯片后端不能一套wheel通吃：昇腾、海光、摩尔线程，需要对应后端的预编译包，不能直接用nvidia包。
私有源resource.flagos.net内网访问不到时，需要下载离线whl包本地安装。
芯片SDK必须提前安装完成：比如昇腾需要CANN，HCU需要海光驱动SDK，FlagTree只是上层编译器，不包含底层硬件驱动。

官方参考文档

FlagTree Github：https://github.com/flagos‑ai/FlagTree
Wiki各硬件安装手册：https://github.com/flagos‑ai/FlagTree/wiki

如果你告诉我你的硬件（Nvidia / 昇腾 / 海光HCU /摩尔线程等），我可以给你一套针对该硬件可直接复制粘贴的完整部署脚本。