SGLang 在昇腾 NPU 上如何按 CANN 版本匹配组件并完成安装【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang在昇腾 Atlas 800I A2 / A3 设备上部署 SGLang 前先要确定使用哪一套 CANN 版本组合官方安装文档明确写了「每个 CANN 版本需要一整套匹配的组件版本不得跨套件混用」目前文档给出 CANN 9.0.0 与 CANN 9.1.0 两套映射。目标结果是装好 SGLang 并让推理服务跑通服务器日志出现The server is fired up and ready to roll!/health检查返回 200测试请求返回预期文本。下文按「识别设备 → 查组件映射 → 安装镜像或源码→ 验证」的顺序展开内容来自 installation.mdx、quick_start.mdx 和 faq.mdx。确认设备型号与运行环境文档支持的设备是 Atlas 800I A2 与 Atlas 800I A3 两个推理系列。先用npu-smi info -l识别自己的设备npu-smi info -l文档给出的区分依据A3 每台 NPU 报告Chip Count: 2A2 报告Chip Count: 1。这个区别影响后续 Docker 容器要挂载哪些/dev/davinci*设备节点。走镜像路径前再确认主机上 Docker 已安装且守护进程在运行以及磁盘空间docker --version docker info df -h文档要求每个 Docker 镜像至少30GB空闲空间如果要额外下载模型权重还要按模型大小再预留空间。按 CANN 版本选择组件套件这是安装的核心步骤。两个 CANN 版本对应的组件套件如下来自安装文档的 Component Version Mapping 表组件CANN 9.0.0 套件CANN 9.1.0 套件HDK25.5.225.5.2CANN9.0.09.1.0TorchNPU26.0.026.1.0MemFabricmemfabric-hybrid1.1.41.1.4Tritontriton-ascend3.2.1.dev202605303.2.2SGLang NPU Kernelsgl-kernel-npu2026.9.020260821MemFabric-zbal1.1.21.1.3Python3.113.12各组件的获取方式按文档说明HDK 25.5.2从昇腾官网固件与驱动社区页面获取CANN安装 CANN Toolkit、Kernels 算子包和 NNAL按昇腾官方 CANN 安装指南或直接拉取对应版本的 CANN 基础镜像TorchNPU从 Ascend pytorch 项目的发布页获取对应版本triton-ascend、memfabric-hybrid、memfabric-zbal用pip install安装命令见下文安装步骤sgl-kernel-npu从 sgl-kernel-npu 项目发布页下载对应版本或按 FAQ 从源码构建。CANN 基础镜像的拉取命令按设备区分# Atlas 800I A3 # CANN 9.0.0 docker pull quay.io/ascend/cann:9.0.0-a3-ubuntu22.04-py3.11 # CANN 9.1.0 docker pull quay.io/ascend/cann:9.1.0-a3-ubuntu22.04-py3.12# Atlas 800I A2 # CANN 9.0.0 docker pull quay.io/ascend/cann:9.0.0-910b-ubuntu22.04-py3.11 # CANN 9.1.0 docker pull quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12注意镜像 tag 里带 Python 版本9.0.0 套件对应py3.119.1.0 套件对应py3.12与上表一致。关键边界CANN 9.1.0 套件的 SGLang 预构建镜像尚未发布。文档说明如果走预构建镜像方式一目前只能用 CANN 9.0.0 套件要使用 9.1.0 套件必须从源码安装方式二或基于 CANN 9.1.0 基础镜像起步。方式一使用官方预构建镜像安装最短路径适合使用 CANN 9.0.0 套件、不想逐个装依赖的场景。拉取 SGLang 镜像文档同时发布stable release经过验证的版本和daily build最新开发版本二选一# Atlas 800I A3 # Stable release docker pull quay.io/ascend/sglang:cann9.0.0-a3-v0.5.16 # Daily build docker pull quay.io/ascend/sglang:main-cann9.0.0-a3# Atlas 800I A2 # Stable release docker pull quay.io/ascend/sglang:cann9.0.0-910b-v0.5.16 # Daily build docker pull quay.io/ascend/sglang:main-cann9.0.0-910b如果遇到问题且怀疑是镜像版本导致文档建议切换到 daily build 试一次。也可以不用发布镜像改用仓库里的 npu.Dockerfile 自行构建git clone https://github.com/sgl-project/sglang.git cd sglang/docker # TARGETARCH 替换为目标架构如 amd64、arm64image_name 替换为你指定的镜像名 # 可选构建参数 # --build-arg DEVICE_TYPE910b # Atlas 800I A2 必需 # --build-arg APTMIRRORmirror_url # 自定义 APT 镜像源加速下载 docker build --build-arg TARGETARCHarch_tag -t image_name -f npu.Dockerfile .创建容器并进入以 A3 为例A2 的设备列表见下# 二选一注释掉不用的那行 export IMAGEquay.io/ascend/sglang:cann9.0.0-a3-v0.5.16 # Stable release # export IMAGEquay.io/ascend/sglang:main-cann9.0.0-a3 # Daily build docker run -it --rm --privileged --networkhost --ipchost --shm-size16g \ --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/ \ --entrypointbash \ $IMAGEA2 与 A3 命令的区别只在设备列表A2 只挂载--device/dev/davinci0到--device/dev/davinci7没有 8–15 号节点。几个参数的文档说明--privileged和--networkhost是 RDMA 所必需的而 Ascend NPU 集群通常依赖 RDMA--rm表示命令结束含 CtrlC后容器会被自动删除--volume ~/.cache/:/root/.cache/把宿主机缓存目录挂进容器。设备节点列表按你机器的实际 davinci 设备调整上面两个列表与文档中 A3/A2 的示例一致。启动服务并验证容器内 SGLang 已预装先确认版本pip show sglang启动服务。模型默认从 Hugging Face 下载首次运行可能需要数分钟# 网络无法直连 Hugging Face 时设置镜像站点 export HF_ENDPOINThttps://hf-mirror.com # 下载受限模型时设置为你自己的 HF token示例模型为公开模型时可不设置 export HF_TOKEN你的 token # 启动服务后台运行 sglang serve --model-path Qwen/Qwen2.5-7B-Instruct --attention-backend ascend 如果模型权重已经下载到本地给docker run加--volume /path/to/model:/path/to/model挂载进容器然后直接--model-path /path/to/model。启动成功后日志输出文档示例INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:30000 (Press CTRLC to quit) The server is fired up and ready to roll!看到The server is fired up and ready to roll!后发测试请求curl -X POST http://localhost:30000/generate \ -H Content-Type: application/json \ -d { text: The capital of France is, sampling_params: { temperature: 0, max_new_tokens: 16 } }文档给出的成功判断响应中的 text 字段包含 Paris说明服务按预期工作。停止服务时向进程发SIGINT只影响 sglang serve 进程本身SGLANG_PID$(pgrep -f sglang serve) kill -SIGINT $SGLANG_PID文档示例的关闭日志会依次出现Shutting down、Application shutdown complete、Finished server process。用ps -ef | grep sglang确认没有匹配进程后按CtrlD退出容器--rm会随之删除容器。方式二源码安装CANN 9.1.0 套件的必要路径安装文档的 Method 1 默认安装CANN 9.0.0套件要装 9.1.0 套件按文档说法是「同样的步骤 映射表里 9.1.0 套件的组件版本且 Python 必须是 3.12」。创建 Python 环境CANN 9.0.0 套件要求python3.119.1.0 套件要求python3.12。文档建议用 conda 避免破坏系统预装的 Pythonconda create --name sglang_npu python3.11 conda activate sglang_npu如果conda create报 “Terms of Service have not been accepted”是默认 Anaconda 仓库拦截了下载。文档给出的解法是配置清华镜像源然后删除环境重建conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/ conda config --set show_channel_urls yes conda config --remove channels defaults conda clean -i conda env remove -n sglang_npu conda create --name sglang_npu python3.11 conda activate sglang_npu文档还提示需要同时检查系统级 conda 配置如~/miniconda3/.condarc中硬编码的 defaults 通道。安装 CANN 与 Python 侧组件前置条件先安装 CANN Toolkit、Kernels 算子包和 NNAL9.0.0 套件装 9.0.0 版本按昇腾官方 CANN 安装指南操作或者使用上文「按 CANN 版本选择组件套件」中的 CANN 基础镜像作为环境。然后依次安装 Python 侧组件以下命令为文档中 CANN 9.0.0 套件的默认值# PyTorch 与 Ascend 框架适配层 PYTORCH_VERSION2.10.0 TORCHVISION_VERSION0.25.0 TORCH_NPU_VERSION2.10.0 pip install torch$PYTORCH_VERSION torchvision$TORCHVISION_VERSION --index-url https://download.pytorch.org/whl/cpu pip install torch_npu$TORCH_NPU_VERSION# Triton on AscendSGLang 提供的 Ascend 实现 pip install triton-ascend3.2.1.dev20260530 \ --extra-index-urlhttps://mirrors.huaweicloud.com/ascend/repos/pypi/nightly \ --trusted-host mirrors.huaweicloud.com# libGL 等系统库需要 apt 权限 apt update apt install libgl1 libglib2.0-0 # 确保 setuptools 包含 pkg_resources 模块 pip install setuptools80条件依赖按需安装# 仅当使用 PD 分离模式MemFabric-Hybrid 是 Mooncake Transfer Engine 的替代 # 在 Ascend NPU 集群上完成 KV cache 传输 pip install memfabric-hybrid1.0.8# 仅 aarch64arm64主机需要MemFabric-zbal # 是面向 LLM 推理/训练的高性能算子库作为 MemFabric-Hybrid 之外的附加安装 pip install memfabric-zbal1.1.1sgl-kernel-npu 按映射表取对应版本9.0.0 套件 2026.9.09.1.0 套件 20260821从 sgl-kernel-npu 项目发布页下载 wheel 安装。也可以从源码构建FAQ 给出的更新流程git clone https://github.com/sgl-project/sgl-kernel-npu.git source /usr/local/Ascend/ascend-toolkit/set_env.sh cd sgl-kernel-npu bash build.sh pip install output/sgl_kernel_npu*.whl --force-reinstall # 验证导入是否成功FAQ 给出的可选检查 python -c import sgl_kernel_npu; print(sgl_kernel_npu.__path__)另外文档说明还提供一个 DeepEP 兼容库作为 deepseek-ai DeepEP 库的替代安装方式见 sgl-kernel-npu 仓库内的说明文档。版本记录不一致的提示上面部分pip install命令里写的版本号torch_npu 2.10.0、memfabric-hybrid 1.0.8、memfabric-zbal 1.1.1与映射表中 CANN 9.0.0 套件列出的版本TorchNPU 26.0.0、1.1.4、1.1.2不一致文档没有进一步解释两者关系而文档对 9.1.0 套件的明确要求是「按映射表中的组件版本执行」。实际执行时请对照你所选 CANN 套件的映射表核对组件版本并保持同一套件内版本成套一致——文档明确禁止跨套件混用版本。从源码安装 SGLang# 使用最新的 release 分支 git clone https://github.com/sgl-project/sglang.git cd sglang mv python/pyproject_npu.toml python/pyproject.toml pip install -e python[all_npu]mv这一步用 NPU 专用的 pyproject_npu.toml 替换克隆仓库python/目录下的 pyproject.toml只影响本地克隆不影响远端仓库。启动服务并验证以文档「PD Mixed Scene」的大语言模型启动命令为例# Enabling CPU Affinity export SGLANG_SET_CPU_AFFINITY1 python3 -m sglang.launch_server \ --model-path meta-llama/Llama-3.1-8B-Instruct \ --attention-backend ascend \ --host 127.0.0.1 \ --port 30000日志出现The server is fired up and ready to roll!后做健康检查成功响应为 HTTP 200、空响应体curl http://127.0.0.1:30000/health再发一条生成请求curl http://127.0.0.1:30000/generate \ -H Content-Type: application/json \ -d { text: What is the capital of France?, sampling_params: {temperature: 0, max_new_tokens: 128} }文档说明期望输出应包含 Paris。默认监听端口是30000不指定--port时可用--host/--port修改。安装完成后的推荐系统设置安装文档在开头提示「请浏览 System Settings 一节以确保集群以最佳性能运行」以下三项均用 sudo 修改系统设置属可选项# 1. CPU 电源方案Ascend 硬件默认 ondemand文档建议改为 performance echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor # 验证应显示 performance cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor# 2. 关闭 NUMA balancing sudo sysctl -w kernel.numa_balancing0 # 验证应显示 0 cat /proc/sys/kernel/numa_balancing# 3. 降低 swap 倾向防止系统内存被换出 sudo sysctl -w vm.swappiness10 # 验证应显示 10 cat /proc/sys/vm/swappiness版本边界与已知问题CANN 9.1.0 套件镜像缺失预构建 SGLang 镜像目前只覆盖 CANN 9.0.0 套件9.1.0 只能走源码安装或基于 CANN 9.1.0 基础镜像构建。禁止跨套件混用组件版本这是映射表的第一条规则混装 9.0.0 套件的 Triton 和 9.1.0 套件的 TorchNPU 这类组合不在文档支持范围内。图模式报错aclnnInplaceFillScalar/ 错误码 507000FAQ原因是捕获的 graph 过多导致更新流冲突与 CANN TorchNPU 版本组合有关。文档说 CANN 8.5 TorchNPU 2.8 组合应已解决该问题如果你的版本组合不匹配可把捕获的 graph 数量降到 10 个以内。下载模型报[Errno 101] Network is unreachableFAQ机器无法直连 HuggingFace 时设置export HF_ENDPOINThttps://hf-mirror.com或配置http_proxy/https_proxy也可以在别的机器下载后用本地路径参数指定。conda 源被拦截即上文 “Terms of Service have not been accepted” 报错按清华镜像源步骤处理。安装并验证通过后同一份安装文档还覆盖了多模态模型启动如--mm-attention-backend ascend_attn和 PD 分离部署Prefill/Decode/Router 三进程的启动示例可按需继续在 installation.mdx 中查阅。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考