支持 NPU 的 SGLang 安装#

您可以使用以下任何一种方法安装 SGLang。请阅读 系统设置 章节，以确保集群发挥最大性能。如果您遇到任何困难或问题，请随时在 sglang GitHub 提交 issue。

准备运行环境#

方法 1：通过源码及依赖项安装#

Python 版本#

目前仅支持 python==3.11。如果您不想破坏系统预装的 Python，请尝试使用 conda 进行安装。

conda create --name sglang_npu python=3.11
conda activate sglang_npu

CANN#

在昇腾上开始使用 SGLang 之前，您需要安装 CANN Toolkit、Kernels 算子包和 NNAL 8.3.RC2 或更高版本，请参考安装指南

MemFabric 适配器#

如果您想使用 PD 分离模式，则需要安装 MemFabric 适配器。MemFabric 适配器是 Mooncake 传输引擎的替代方案，可在昇腾 NPU 集群上实现 KV 缓存传输。

pip install mf-adapter==1.0.0

昇腾上的 Pytorch 及 Pytorch 框架适配器#

目前 NPUGraph 优化仅在 torch_npu==2.6.0.post3 中受支持，该版本需要 ‘torch==2.6.0’。TODO：NPUGraph 优化将在未来的 ‘torch_npu’ 2.7.1、2.8.0 和 2.9.0 版本中提供支持

PYTORCH_VERSION=2.6.0
TORCHVISION_VERSION=0.21.0
TORCH_NPU_VERSION=2.6.0.post3
pip install torch==$PYTORCH_VERSION torchvision==$TORCHVISION_VERSION --index-url https://download.pytorch.org/whl/cpu
pip install torch_npu==$TORCH_NPU_VERSION

由于目前尚未发布适用于 ‘torch==2.7.1’ 和 ‘torch==2.8.0’ 的 ‘torch_npu’ 版本，我们提供了自定义构建的 ‘torch_npu’。PLATFORM 可以是 ‘aarch64’ 或 ‘x86_64’

PLATFORM="aarch64"
PYTORCH_VERSION=2.8.0
TORCHVISION_VERSION=0.23.0
pip install torch==$PYTORCH_VERSION torchvision==$TORCHVISION_VERSION --index-url https://download.pytorch.org/whl/cpu
wget https://sglang-ascend.obs.cn-east-3.myhuaweicloud.com/sglang/torch_npu/torch_npu-${PYTORCH_VERSION}.post2.dev20251120-cp311-cp311-manylinux_2_28_${PLATFORM}.whl
pip install torch_npu-${PYTORCH_VERSION}.post2.dev20251120-cp311-cp311-manylinux_2_28_${PLATFORM}.whl

如果您使用的是其他版本的 ‘torch’，请从源码安装 ‘torch_npu’，参考安装指南

昇腾上的 Triton#

我们为昇腾提供了自己的 Triton 实现。

BISHENG_NAME="Ascend-BiSheng-toolkit_aarch64_20251121.run"
BISHENG_URL="https://sglang-ascend.obs.cn-east-3.myhuaweicloud.com/sglang/triton_ascend/${BISHENG_NAME}"
wget -O "${BISHENG_NAME}" "${BISHENG_URL}" && chmod a+x "${BISHENG_NAME}" && "./${BISHENG_NAME}" --install && rm "${BISHENG_NAME}"

pip install triton-ascend==3.2.0rc4

有关在昇腾上安装 Triton 每夜构建版或从源码安装的信息，请参考安装指南

SGLang NPU 内核#

我们提供了一套自己的 SGL 内核，请参考安装指南。

DeepEP 兼容库#

我们提供了一个 DeepEP 兼容库，作为 deepseek-ai 的 DeepEP 库的直接替代方案，请参考安装指南。

自定义算子 (CustomOps)#

TODO：一旦合并到 sgl-kernel-npu 即可移除。 包含自定义算子的附加包。DEVICE_TYPE 对于 Atlas A3 服务器可以是 “a3”，对于 Atlas A2 服务器可以是 “910b”。

DEVICE_TYPE="a3"
wget https://sglang-ascend.obs.cn-east-3.myhuaweicloud.com/ops/CANN-custom_ops-8.2.0.0-$DEVICE_TYPE-linux.aarch64.run
chmod a+x ./CANN-custom_ops-8.2.0.0-$DEVICE_TYPE-linux.aarch64.run
./CANN-custom_ops-8.2.0.0-$DEVICE_TYPE-linux.aarch64.run --quiet --install-path=/usr/local/Ascend/ascend-toolkit/latest/opp
wget https://sglang-ascend.obs.cn-east-3.myhuaweicloud.com/ops/custom_ops-1.0.$DEVICE_TYPE-cp311-cp311-linux_aarch64.whl
pip install ./custom_ops-1.0.$DEVICE_TYPE-cp311-cp311-linux_aarch64.whl

从源码安装 SGLang#

# Use the last release branch
git clone -b v0.5.6.post2 https://github.com/sgl-project/sglang.git
cd sglang
mv python/pyproject_other.toml python/pyproject.toml
pip install -e python[srt_npu]

方法 2：使用 Docker#

获取镜像#

您可以下载 SGLang 镜像，或基于 Dockerfile 构建镜像以获取昇腾 NPU 镜像。

下载 SGLang 镜像

dockerhub: docker.io/lmsysorg/sglang:$tag
# Main-based tag, change main to specific version like v0.5.6,
# you can get image for specific version
Atlas 800I A3 : {main}-cann8.3.rc2-a3
Atlas 800I A2: {main}-cann8.3.rc2-910b

基于 Dockerfile 构建镜像

# Clone the SGLang repository
git clone https://github.com/sgl-project/sglang.git
cd sglang/docker

# Build the docker image
docker build -t <image_name> -f npu.Dockerfile .

创建容器#

注意： RDMA 需要 --privileged 和 --network=host，这通常是昇腾 NPU 集群所必需的。

注意： 以下 docker 命令基于 Atlas 800I A3 机器。如果您使用的是 Atlas 800I A2，请确保仅将 davinci[0-7] 映射到容器中。

alias drun='docker run -it --rm --privileged --network=host --ipc=host --shm-size=16g \
    --device=/dev/davinci0 --device=/dev/davinci1 --device=/dev/davinci2 --device=/dev/davinci3 \
    --device=/dev/davinci4 --device=/dev/davinci5 --device=/dev/davinci6 --device=/dev/davinci7 \
    --device=/dev/davinci8 --device=/dev/davinci9 --device=/dev/davinci10 --device=/dev/davinci11 \
    --device=/dev/davinci12 --device=/dev/davinci13 --device=/dev/davinci14 --device=/dev/davinci15 \
    --device=/dev/davinci_manager --device=/dev/hisi_hdc \
    --volume /usr/local/sbin:/usr/local/sbin --volume /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    --volume /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
    --volume /etc/ascend_install.info:/etc/ascend_install.info \
    --volume /var/queue_schedule:/var/queue_schedule --volume ~/.cache/:/root/.cache/'

# Add HF_TOKEN env for download model by SGLang
drun --env "HF_TOKEN=<secret>" \
    <image_name> \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --attention-backend ascend --host 0.0.0.0 --port 30000

系统设置#

CPU 性能电源策略#

昇腾硬件上的默认电源策略是 ondemand，这可能会影响性能，建议将其更改为 performance。

echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# Make sure changes are applied successfully
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor # shows performance

禁用 NUMA 平衡#

sudo sysctl -w kernel.numa_balancing=0

# Check
cat /proc/sys/kernel/numa_balancing # shows 0

防止交换出系统内存#

sudo sysctl -w vm.swappiness=10

# Check
cat /proc/sys/vm/swappiness # shows 10

运行 SGLang 服务#

运行大语言模型 (LLM) 服务#

PD 混合场景#

python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --attention-backend ascend --host 0.0.0.0 --port 30000

PD 分离场景#

启动 Prefill 服务器

export SGLANG_SET_CPU_AFFINITY=1
# PIP: recommended to config first Prefill Server IP, all server need to be config the same ip, PORT: one free port
export ASCEND_MF_STORE_URL="tcp://PIP:PORT"
# if you are Atlas 800I A2 hardware and use rdma for kv cache transfer, add this parameter
export ASCEND_MF_TRANSFER_PROTOCOL="device_rdma"
python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --disaggregation-mode prefill \
    --disaggregation-transfer-backend ascend \
    --disaggregation-bootstrap-port 8995 \
    --attention-backend ascend \
    --device npu \
    --base-gpu-id 0 \
    --tp-size 1 \
    --host 127.0.0.1  \
    --port 8000

启动 Decode 服务器

export SGLANG_SET_CPU_AFFINITY=1
# PIP: recommended to config first Prefill Server IP, all server need to be config the same ip, PORT: one free port
export ASCEND_MF_STORE_URL="tcp://PIP:PORT"
# if you are Atlas 800I A2 hardware and use rdma for kv cache transfer, add this parameter
export ASCEND_MF_TRANSFER_PROTOCOL="device_rdma"
python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --disaggregation-mode decode \
    --disaggregation-transfer-backend ascend \
    --attention-backend ascend \
    --device npu \
    --base-gpu-id 1 \
    --tp-size 1 \
    --host 127.0.0.1 \
    --port 8001

启动 Router (路由器)

python3 -m sglang_router.launch_router \
    --pd-disaggregation \
    --policy cache_aware \
    --prefill http://127.0.0.1:8000 8995 \
    --decode http://127.0.0.1:8001 \
    --host 127.0.0.1 \
    --port 6688

运行多模态语言模型 (VLM) 服务#

PD 混合场景#

python3 -m sglang.launch_server \
    --model-path Qwen3-VL-30B-A3B-Instruct \
    --host 127.0.0.1 \
    --port 8000 \
    --tp 4 \
    --device npu \
    --attention-backend ascend \
    --mm-attention-backend ascend_attn \
    --disable-radix-cache \
    --trust-remote-code \
    --enable-multimodal \
    --sampling-backend ascend

支持 NPU 的 SGLang 安装

目录

支持 NPU 的 SGLang 安装#

准备运行环境#

方法 1：通过源码及依赖项安装#

Python 版本#

CANN#

MemFabric 适配器#

昇腾上的 Pytorch 及 Pytorch 框架适配器#

昇腾上的 Triton#

SGLang NPU 内核#

DeepEP 兼容库#

自定义算子 (CustomOps)#

从源码安装 SGLang#

方法 2：使用 Docker#

获取镜像#

创建容器#

系统设置#

CPU 性能电源策略#

禁用 NUMA 平衡#

防止交换出系统内存#

运行 SGLang 服务#

运行大语言模型 (LLM) 服务#

PD 混合场景#

PD 分离场景#

运行多模态语言模型 (VLM) 服务#

PD 混合场景#