<col style={{width: "33%"}} />
<col style={{width: "33%"}} />
</colgroup>
<thead>
<tr style={{borderBottom: "2px solid #d55816"}}>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Component</th>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.05)"}}>Version</th>
<th style={{textAlign: "left", padding: "10px 12px", fontWeight: 700, whiteSpace: "nowrap", backgroundColor: "rgba(255,255,255,0.02)"}}>Obtain Method</th>
</tr>
</thead>
<tbody>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>HDK</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>25.5.2</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}><a href="https://www.hiascend.com/hardware/firmware-drivers/community?product=1&model=30&cann=9.0.0&driver=Ascend+HDK+25.5.2">link</a></td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>CANN</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>9.1.0</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}><a href="#obtain-cann-image">Obtain Images</a></td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>TorchNPU</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>26.1.0</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}><a href="https://gitcode.com/Ascend/pytorch/releases">link</a></td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>MemFabric</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>1.1.4</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`pip install memfabric-hybrid==1.1.4`</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>Triton</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>3.2.2</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`pip install https://github.com/triton-lang/triton-ascend/releases/download/v3.2.2/triton_ascend-3.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl`<br />`(aarch64 host: replace x86_64 with aarch64)`</td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>SGLang NPU Kernel</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>20260821</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}><a href="https://github.com/sgl-project/sgl-kernel-npu/releases/tag/20260821">link</a></td>
</tr>
<tr>
<td style={{padding: "9px 12px", fontWeight: 500, backgroundColor: "rgba(255,255,255,0.02)"}}>MemFabric-zbal</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.05)"}}>1.1.3</td>
<td style={{padding: "9px 12px", backgroundColor: "rgba(255,255,255,0.02)"}}>`pip install memfabric-zbal==1.1.3`</td>
</tr>
</tbody>
</table>
<Note>
CANN 9.1.0 세트용 SGLang Docker 이미지는 아직 공개되지 않았어요. 사전 빌드된 SGLang
이미지로 배포한다면([방법 2](#method-2-using-docker-image)) 지금은 CANN 9.0.0 세트를 사용하세요. CANN 9.1.0 세트를 쓰려면
소스에서 SGLang을 설치하거나([방법 1](#method-1-installing-from-source-with-prerequisites), 이 탭의 컴포넌트 버전 사용)
CANN 9.1.0 기반 이미지에서 시작하세요([CANN 이미지 얻기](#obtain-cann-image) 참고).
</Note>
CANN 이미지 얻기
이미지를 받기 전에 충분한 디스크 공간을 확보하세요. 각 Docker 이미지는 최소 **30GB**의 여유 공간이 필요해요.
이미지를 통해 특정 버전의 CANN 의존성을 얻을 수 있어요.
```bash Command theme={null}
# 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
```
```bash Command theme={null}
# 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
```
실행 환경 준비 (Preparing the Running Environment)
방법 1: 전제 조건과 함께 소스에서 설치
이 방법의 단계는 CANN 9.0.0 세트를 설치해요. CANN 9.1.0 세트를 소스에서 설치하려면 버전 매핑 표의 컴포넌트 버전으로 동일한 단계를 따르면 되고, CANN 9.1.0 세트에는 python 3.12가 필요해요.
Python 버전
CANN 9.0.0 세트는 python==3.11이 필요하고, CANN 9.1.0 세트는 python==3.12를 사용해요. 시스템에 미리 설치된 python을 망가뜨리고 싶지 않다면 conda로 설치해 보세요.
conda create --name sglang_npu python=3.11
conda activate sglang_npu
Anaconda 저장소 제한에 관한 참고
conda create 단계에서 "Terms of Service have not been accepted" 같은 오류가 발생하면, 기본 Anaconda 저장소가 패키지 다운로드를 차단하고 있는 거예요. 이 문제를 해결하려면 미러(예: Tsinghua Open Source Mirror)를 설정하세요:
# Add Tsinghua mirrors
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 config를 편집하세요(예: vi ~/miniconda3/.condarc). 그 다음 실패한 환경을 제거하고 다시 생성하세요:
conda clean -i
conda env remove -n sglang_npu
conda create --name sglang_npu python=3.11
conda activate sglang_npu
CANN
Ascend에서 SGLang 작업을 시작하기 전에 CANN Toolkit, Kernels 운영자 패키지, NNAL 버전 9.0.0을 설치해야 해요. 설치 가이드를 확인하세요.
MemFabric-Hybrid
PD 분리(disaggregation) 모드를 사용하려면 MemFabric-Hybrid를 설치해야 해요. MemFabric-Hybrid는 Mooncake Transfer Engine의 드롭인 대체품으로, Ascend NPU 클러스터에서 KV 캐시 전송을 가능하게 해줘요.
pip install memfabric-hybrid==1.0.8
MemFabric-zbal
MemFabric-zbal은 Ascend에서 LLM 추론과 학습을 위한 고성능 연산자의 Zero Buffer Acceleration Library예요. 중간 메모리 버퍼를 제거해 연산을 가속하고, aarch64 클러스터에서만 필요하며 MemFabric-Hybrid에 추가로 설치해요.
# Only needed on aarch64 (arm64) hosts
pip install memfabric-zbal==1.1.1
PyTorch 및 Ascend용 PyTorch 프레임워크 어댑터
PYTORCH_VERSION=2.10.0
TORCHVISION_VERSION=0.25.0
TORCH_NPU_VERSION=2.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
다른 버전의 torch를 사용하면서 torch_npu를 설치한다면 설치 가이드를 확인하세요.
Ascend용 Triton
Ascend용 Triton 자체 구현을 제공해요.
pip install triton-ascend==3.2.1.dev20260530 \
--extra-index-url=https://mirrors.huaweicloud.com/ascend/repos/pypi/nightly \
--trusted-host mirrors.huaweicloud.com
Ascend용 Triton nightly 빌드나 소스 설치에 대해서는 설치 가이드를 따라하세요.
SGLang Kernels NPU
Ascend NPU용 SGL 커널을 제공해요. 설치 가이드를 확인하세요.
DeepEP 호환 라이브러리
deepseek-ai의 DeepEP 라이브러리의 드롭인 대체품인 DeepEP 호환 라이브러리를 제공해요. 설치 가이드를 확인하세요.
기타 의존성
# libGL
apt update
apt install libgl1 libglib2.0-0
# ensure setuptools contains pkg_resources module
pip install "setuptools<80"
소스에서 SGLang 설치하기
# Use the last release branch
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]
방법 2: Docker 이미지 사용하기
이미지 얻기
SGLang 이미지를 다운로드하거나 Dockerfile을 기반으로 이미지를 빌드해 Ascend NPU 이미지를 얻을 수 있어요.
이미지를 받기 전에 충분한 디스크 공간을 확보하세요. 각 Docker 이미지는 최소 **30GB**의 여유 공간이 필요해요. 모델 가중치를 다운로드해야 한다면 [ModelScope](https://www.modelscope.cn/models)에서 모델 크기를 확인해 충분한 공간을 확보하세요.
- SGLang 이미지 다운로드
**안정 릴리스**와 **데일리 빌드**를 모두 공개해요. 검증된 버전을 원하면 안정 릴리스 태그(예: `cann9.0.0-a3-v0.5.16`)를, 최신 개발 변경 사항이 필요하면 데일리 빌드 태그(예: `main-cann9.0.0-a3`)를 선택하세요.
CANN 9.1.0 세트용 SGLang 이미지는 아직 공개되지 않았어요. 지금은 아래 CANN 9.0.0 이미지를 사용하세요.
```bash Command theme={null}
# 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
```
```bash Command theme={null}
# 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
```
- Dockerfile 기반으로 이미지 빌드
# Clone the SGLang repository
git clone https://github.com/sgl-project/sglang.git
cd sglang/docker
# Build the docker image
# Replace <arch_tag> with the target architecture, e.g., amd64, arm64.
# Optional build arguments:
# --build-arg DEVICE_TYPE=910b # Required for Ascend A2 Series
# --build-arg APTMIRROR=<mirror_url> # Use a custom APT mirror to improve download speed
# If there are network errors, please modify the Dockerfile to add ARG HTTP_PROXY/HTTPS_PROXY and set them as ENV.
docker build --build-arg TARGETARCH=<arch_tag> -t <image_name> -f npu.Dockerfile .
Docker 생성하기
참고: --privileged와 --network=host는 RDMA에 필요하며, RDMA는 Ascend NPU 클러스터에서 보통 필요해요.
```bash Command theme={null}
# Create a shortcut 'drun' to launch a privileged Docker container
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 downloading models by SGLang.
# The container runs with the '--rm' flag, so it will be automatically removed after the command finishes (including Ctrl+C)
drun --env "HF_TOKEN=<secret>" \
<image_name> \
python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --attention-backend ascend
```
```bash Command theme={null}
# Create a shortcut 'drun' to launch a privileged Docker container
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/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 downloading models by SGLang.
# The container runs with the '--rm' flag, so it will be automatically removed after the command finishes (including Ctrl+C)
drun --env "HF_TOKEN=<secret>" \
<image_name> \
python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --attention-backend ascend
```
SGLang은 기본적으로 `http://127.0.0.1:30000`에서 서빙해요. `--host`와 `--port` 파라미터로 호스트와 포트를 바꿀 수 있어요.
시스템 설정 (System Settings)
CPU 성능 전원 스킴
Ascend 하드웨어의 기본 전원 스킴은 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 서비스 실행하기
대규모 언어 모델 서비스 실행
PD 혼합 시나리오
# Enabling CPU Affinity
export SGLANG_SET_CPU_AFFINITY=1
python3 -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--attention-backend ascend \
--host 127.0.0.1 \
--port 30000
PD 분리 시나리오
- Prefill 서버 실행
```bash Command theme={null}
# Enabling CPU Affinity
export SGLANG_SET_CPU_AFFINITY=1
# PREFILL_IP: IP address of the first Prefill Server
# FREE_PORT: any available port
# all SGLang servers need to be configured with the same PREFILL_IP and FREE_PORT
export ASCEND_MF_STORE_URL="tcp://PREFILL_IP:FREE_PORT"
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 30001
```
```bash Command theme={null}
# Enabling CPU Affinity
export SGLANG_SET_CPU_AFFINITY=1
# PREFILL_IP: IP address of the first Prefill Server
# FREE_PORT: any available port
# all SGLang servers need to be configured with the same PREFILL_IP and FREE_PORT
export ASCEND_MF_STORE_URL="tcp://PREFILL_IP:FREE_PORT"
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 30001
```
- Decode 서버 실행
```bash Command theme={null}
# PREFILL_IP: IP address of the first Prefill Server
# FREE_PORT: any available port
# all SGLang servers need to be configured with the same PREFILL_IP and FREE_PORT
export ASCEND_MF_STORE_URL="tcp://PREFILL_IP:FREE_PORT"
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 30002
```
```bash Command theme={null}
# PREFILL_IP: IP address of the first Prefill Server
# FREE_PORT: any available port
# all SGLang servers need to be configured with the same PREFILL_IP and FREE_PORT
export ASCEND_MF_STORE_URL="tcp://PREFILL_IP:FREE_PORT"
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 30002
```
- Router 실행
python3 -m sglang_router.launch_router \
--pd-disaggregation \
--policy cache_aware \
--prefill http://127.0.0.1:30001 8995 \
--decode http://127.0.0.1:30002 \
--host 127.0.0.1 \
--port 30000
명령 스크립트의 `8995`는 분리 부트스트랩 포트예요. 1단계에서 prefill 서버에 설정한
`--disaggregation-bootstrap-port` 값과 일치해야 해요.
멀티모달 언어 모델 서비스 실행
PD 혼합 시나리오
python3 -m sglang.launch_server \
--model-path Qwen/Qwen3-VL-30B-A3B-Instruct \
--host 127.0.0.1 \
--port 30000 \
--tp 4 \
--device npu \
--attention-backend ascend \
--mm-attention-backend ascend_attn \
--disable-radix-cache \
--trust-remote-code \
--enable-multimodal \
--sampling-backend ascend
서비스 테스트하기 (Testing the Service)
서버 로그에 The server is fired up and ready to roll!가 출력되면 요청을 받을 준비가 된 거예요.
요청을 보낼 포트
사용할 포트는 배포 모드에 따라 달라져요:
| 시나리오 |
요청을 보낼 곳 |
| Non-PD (단일 서버) |
서버의 --port (위 예시의 30000 등) |
| Non-PD (멀티 노드) |
기본 노드의 (--node-rank 0) --port; 워커 노드에는 요청을 보내지 마세요 |
| PD 분리 |
Router의 --port (위 예시의 30000 등); prefill 또는 decode 서버에는 직접 요청을 보내지 마세요 |
`--port`를 지정하지 않으면 SGLang은 기본적으로 포트 `30000`을 사용해요. 이 가이드의 예시는 명확성을 위해 명시적 포트를 씁니다.
헬스 체크 (Health Check)
curl http://127.0.0.1:30000/health
성공 응답은 빈 본문과 함께 HTTP 200을 반환해요.
Generate (네이티브 엔드포인트)
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"가 포함되어야 해요.
Chat Completions (OpenAI 호환)
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "meta-llama/Llama-3.1-8B-Instruct",
"messages": [{"role": "user", "content": "What is the capital of France?"}]
}'
일부 모델은 사고 과정 콘텐츠를 동반한 응답을 반환해요. 이 출력을 비활성화하려면 다음과 같이 파라미터를 설정하세요:
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Eco-Tech/Qwen3.5-27B-w8a8-mtp",
"messages": [{"role": "user", "content": "What is the capital of France?"}],
"chat_template_kwargs": {"enable_thinking": false}
}'
예상 출력에는 "Paris"가 포함되어야 해요.
멀티모달 Chat Completions
아래 예시의 이미지 URL은 외부 리소스(`raw.githubusercontent.com`)를 참조해요. 추론 시 이미지를 다운로드할 수 있도록 서버가 인터넷에 접근할 수 있는지 확인하세요. 대안으로 로컬에서 접근 가능한 URL이나 base64로 인코딩된 이미지 데이터를 사용해도 돼요.
curl http://127.0.0.1:30000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen3-VL-30B-A3B-Instruct",
"messages": [{
"role": "user",
"content": [
{"type": "image_url", "image_url": {"url": "https://raw.githubusercontent.com/sgl-project/sglang/main/examples/assets/example_image.png"}},
{"type": "text", "text": "Describe this image."}
]
}]
}'
더 알아보기 (Learn more)
