SGLang 설치

SGLang 설치

SGLang은 여러 방법으로 설치할 수 있어요. 이 문서는 주로 일반적인 NVIDIA GPU 플랫폼을 기준으로 설명하며, 다른 플랫폼은 AMD GPU, Apple Metal, Intel Xeon CPU, Google TPU, NVIDIA Jetson, Ascend NPU, Intel XPU 전용 페이지를 참고해요.

사전 요구사항: Python 3.10 이상.

방법 1: pip 또는 uv로 설치

설치 속도를 위해 uv를 추천해요.

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow sglang

SGLang의 일부 의존성은 PyPI에 프리릴리스만 올라와 있어요. --prerelease=allow 없이 uv 0.12.0 미만을 쓰면 조용히 SGLang 0.5.9가 설치돼요. uv 0.12.0 이후 버전에선 이 플래그가 무해한 no-op이에요.

기본 CUDA 메이저 버전은 13이에요. CUDA 12 환경에서 설치하려면 아래 명령을 사용해요.

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow sglang
uv pip install --force-reinstall torch==2.13.0 torchaudio==2.11.0 torchvision --index-url https://download.pytorch.org/whl/cu129
uv pip install --force-reinstall sglang-kernel --index-url https://docs.sglang.ai/whl/cu129/
uv pip install --force-reinstall sgl-deep-gemm --index-url https://docs.sglang.ai/whl/cu129/ --no-deps

나이틀리 빌드

다음 안정 릴리스 전에 최신 기능과 수정 사항을 쓰고 싶다면 나이틀리 빌드를 설치해요. 나이틀리 휠은 main 브랜치에서 빌드돼 SGLang 휠 인덱스에 올라가요. --extra-index-url로 인덱스를 추가하고, --prerelease=allow를 --index-strategy unsafe-best-match와 함께 써서 PyPI와 함께 나이틀리 버전을 고려하게 해요.

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow --index-strategy unsafe-best-match --extra-index-url https://docs.sglang.ai/whl/cu130/ sglang

CUDA 12에서 나이틀리를 설치하려면 인덱스를 cu129로 바꿔요.

pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow --index-strategy unsafe-best-match --extra-index-url https://docs.sglang.ai/whl/cu129/ sglang

흔한 문제 빠른 해결

• OSError: CUDA_HOME environment variable is not set 오류가 나면:
  1. export CUDA_HOME=/usr/local/cuda-<your-cuda-version>로 CUDA 설치 루트를 지정해요.
  2. 또는 먼저 FlashInfer 설치 문서를 따라 FlashInfer를 설치한 뒤 SGLang을 설치해요.

방법 2: 소스에서 설치

# 마지막 릴리스 브랜치를 사용
git clone -b v0.5.18 https://github.com/sgl-project/sglang.git
cd sglang

# python 패키지 설치
pip install --upgrade pip
pip install -e "python"

SGLang을 개발하려면 dev docker 이미지를 쓰는 게 편해요. docker 컨테이너 설정을 참고하세요. 이미지는 lmsysorg/sglang:dev예요.

방법 3: Docker로 설치

Docker 이미지는 Docker Hub의 lmsysorg/sglang에서 받을 수 있어요. 아래 <secret> 자리엔 Hugging Face 허브 토큰을 넣어요.

latest와 dev는 변경 가능한(mutable) 태그예요. latest는 항상 최신 안정 릴리스를 가리키고, dev는 main에서 매일 다시 빌드되며 빌드/개발 도구를 포함해요. 시간이 지나면 덮어써지므로 재현 가능한 배포를 위해선 불변 버전 태그를 고정하세요 — 예: lmsysorg/sglang:v0.5.18.

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

프로덕션 배포에선 빌드 도구와 개발 의존성을 제외한 runtime 변형(약 40% 축소)을 사용해요.

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest-runtime \
    python3 -m sglang.launch_server --model-path meta-llama/Llama-3.1-8B-Instruct --host 0.0.0.0 --port 30000

나이틀리 docker 이미지는 여기에서 찾을 수 있어요.

SGLang은 기본적으로 CUDA 13 환경을 포함해요. CUDA 12 환경에서 실행하려면 -cu12 또는 -cu129 접미사가 붙은 이미지(예: lmsysorg/sglang:latest-cu129, lmsysorg/sglang:dev-cu12)를 사용해요.

방법 4: Kubernetes로 설치

엔터프라이즈급 LLM 관리·서빙을 위한 Kubernetes 오퍼레이터인 OME를 확인해요.

1. 단일 노드 서빙(모델이 GPU 한 노드에 들어갈 때): kubectl apply -f docker/k8s-sglang-service.yaml을 실행해 llama-31-8b를 예시로 k8s deployment와 service를 만들어요.
2. 멀티 노드 서빙(DeepSeek-R1처럼 여러 GPU 노드가 필요한 큰 모델): LLM 모델 경로와 인자를 필요에 따라 수정한 뒤 kubectl apply -f docker/k8s-sglang-distributed-sts.yaml을 실행하여 두 노드 statefulset과 서빙 service를 만들어요.

방법 5: docker compose로 설치

서비스로 운영할 계획이라면 이 방법이 권장돼요. 더 나은 방법은 k8s-sglang-service.yaml을 쓰는 것이에요.

1. compose.yml을 로컬로 복사해요.
2. 터미널에서 docker compose up -d를 실행해요.

방법 6: SkyPilot로 Kubernetes 또는 클라우드에서 실행

Kubernetes나 12개 이상의 클라우드에 배포하려면 SkyPilot을 사용할 수 있어요.

1. SkyPilot을 설치하고 Kubernetes 클러스터 또는 클라우드 접근을 설정해요: SkyPilot 문서 참고.
2. 한 줄 명령으로 자체 인프라에 배포하고 HTTP API 엔드포인트를 받아요.

# sglang.yaml
envs:
  HF_TOKEN: null

resources:
  image_id: docker:lmsysorg/sglang:latest
  accelerators: A100
  ports: 30000

run: |
  conda deactivate
  python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 30000

# 아무 클라우드나 Kubernetes 클러스터에 배포. 특정 클라우드를 고르려면 --cloud <cloud> 사용.
HF_TOKEN=<secret> sky launch -c sglang --env HF_TOKEN sglang.yaml

# HTTP API 엔드포인트 가져오기
sky status --endpoint 30000 sglang

3. 오토스케일링과 장애 복구로 더 확장하고 싶다면 SkyServe + SGLang 가이드를 확인해요.

방법 7: AWS SageMaker에서 실행

SGLang을 AWS SageMaker에 배포하려면 AWS SageMaker Inference를 확인해요.

AWS는 SGLang 컨테이너를 정기 보안 패치와 함께 지원해요. 사용 가능한 SGLang 컨테이너는 AWS SGLang DLCs에서 확인해요. 미리 빌드된 SGLang Deep Learning Container를 직접 빌드 없이 배포하려면 Amazon SageMaker AI를 보세요.

자체 컨테이너로 모델을 호스팅하려면:

1. sagemaker.Dockerfile과 serve 스크립트로 docker 컨테이너를 빌드해요.
2. 컨테이너를 AWS ECR에 푸시해요.
3. SageMaker 서빙용 모델을 배포해요. deploy_and_serve_endpoint.py 참고, sagemaker-python-sdk도 확인해요.
   • 기본적으로 SageMaker의 모델 서버는 python3 -m sglang.launch_server --model-path opt/ml/model --host 0.0.0.0 --port 8080로 실행돼요.
   • serve 스크립트는 SM_SGLANG_ 접두사의 환경변수를 --input-argument 형태로 변환해 python3 -m sglang.launch_server에 전달해요.

공통 참고사항

• FlashInfer가 기본 어텐션 커널 백엔드이며 sm75 이상만 지원해요. T4, A10, A100, L4, L40S, H100 등 sm75+ 기기에서 FlashInfer 관련 문제가 생기면 --attention-backend triton --sampling-backend pytorch로 다른 커널을 쓰고 GitHub 이슈를 열어요.
• flashinfer를 로컬로 재설치하려면 pip3 install --upgrade flashinfer-python --force-reinstall --no-deps를 실행하고 rm -rf ~/.cache/flashinfer로 캐시를 지워요.

출처: SGLang 설치

더 알아보기 (Learn more)

• 빠른 시작: 설치 후 첫 서버 실행 흐름
• 네이티브 API: 서버 엔드포인트 전체 목록