SGLang 빠른 시작: OpenAI API 를 통해 LLM 설치, 구성 및 제공

SGLang 로 오픈 모델을 빠르게 제공하세요.

Page content

SGLang 은 단일 GPU 에서 분산 클러스터에 이르기까지 저지연 및 고휘도 추론을 제공하도록 설계된 대규모 언어 모델 및 멀티모달 모델용 고성능 서비스 프레임워크입니다.

올라마 (Ollama), vLLM, llama-swap, LocalAI 및 관리형 클라우드 제공자를 포함한 자체 호스팅과 클라우드 LLM 호스팅 옵션의 광범위한 비교는 2026 년 LLM 호스팅 가이드 를 참조하세요.

기존 애플리케이션이 OpenAI API 형식에 연동되어 있다면, SGLang 은 채팅 및 완료 (completion) 용 OpenAI 호환 엔드포인트를 노출하여 최소한의 클라이언트 측 변경만으로 호스팅된 API 에서 자체 호스팅 모델로 마이그레이닝할 수 있기 때문에 특히 매력적입니다. 여러 백엔드 (llama.cpp, vLLM, SGLang 등) 간에 요청을 라우팅하고 핫스왑 및 TTL 기반 언로딩이 필요한 경우, llama-swap 은 단일 /v1 URL 을 유지하면서 요청에 따라 업스트림을 교체하는 투명한 프록시 레이어를 제공합니다.

sglang infographic

이 QuickStart 는 설치 (다양한 방법), 실제 구성 패턴, 그리고 작동 가능한 HTTP 서비스 및 오프라인 배치 추론 예제를 포함한 “설치 → 서비스 → 확인 → 통합 → 튜닝” 워크플로우를 안내합니다.

내장된 웹 UI 와 최대의 OpenAI API 드롭인 호환성을 갖춘 멀티모달 지원 (텍스트, 임베딩, 이미지, 오디오) 이 필요할 경우, LocalAI 는 더 넓은 기능 세트와 더 많은 모델 포맷 지원을 제공합니다.

고휘도 LLM 및 멀티모달 모델 서비스를 위한 SGLang 이란 무엇인가

핵심적으로 SGLang 은 효율적인 추론 및 확장 가능한 서비스를 위해 설계되었습니다. “고속 런타임” 스택에는 프refix 캐싱을 위한 RadixAttention, 오버헤드가 없는 CPU 스케줄러, 투기적 디코딩, 연속 배칭, 페이지된 어텐션, 여러 병렬 전략 (텐서, 파이프라인, 전문가, 데이터 병렬화), 구조화된 출력, 청크된 프리필 (chunked prefill), 그리고 여러 양자화 옵션 (예: FP4, FP8, INT4, AWQ, GPTQ) 이 포함됩니다.

이 프레임워크는 다양한 플랫폼 배포를 목표로 합니다: NVIDIA GPU, AMD GPU, Intel Xeon CPU, Google TPU, Ascend NPU 등.

PyPI 는 Python >= 3.10 을 요구합니다. 2026 년 3 월 20 일 기준으로 게시된 버전에는 0.5.9(2026 년 2 월 23 일 릴리스) 가 포함되어 있으며, 설치 시 현재 버전을 고정하거나 확인해야 합니다.

uv, pip, 소스 빌드 또는 Docker 를 사용하여 Linux GPU 호스트에 SGLang 설치 방법

설치 옵션에는 uv 또는 pip, 소스 빌드, Docker 이미지, Kubernetes 매니페스트, Docker Compose, SkyPilot, AWS SageMaker 가 포함됩니다. 대부분의 가이드는 일반적인 NVIDIA GPU 설정을 가정하며, 다른 가속기는 별도의 설정 노트를 가지고 있습니다.

Python 3.10+ 에서 uv 또는 pip 를 사용하여 SGLang 빠르게 설치

간단한 로컬 설치를 위해 uv가 일반적으로 가장 빠른 경로입니다:

pip install --upgrade pip
pip install uv
uv pip install sglang

CUDA 13 참고사항

CUDA 13 의 경우 Docker 를 사용하면 호스트 측 PyTorch/CUDA 불일치를 피할 수 있습니다. Docker 를 사용하지 않는 경우: CUDA 13 PyTorch 빌드를 설치한 후 sglang을 설치하고, 다음에 게시된 휠 릴리스에서 일치하는 sglang-kernel 휠을 설치하세요 (버전이 스택과 일치해야 함).

# 1) CUDA 13 지원 PyTorch 설치 (필요에 따라 X.Y.Z 교체)
uv pip install torch==X.Y.Z torchvision torchaudio --index-url https://download.pytorch.org/whl/cu130

# 2) SGLang 설치
uv pip install sglang

# 3) 일치하는 CUDA 13 sglang-kernel 휠 설치 (X.Y.Z 교체)
uv pip install "https://github.com/sgl-project/whl/releases/download/vX.Y.Z/sglang_kernel-X.Y.Z+cu130-cp310-abi3-manylinux2014_x86_64.whl"

Docker Hub 이미지를 사용하여 SGLang 설치 및 실행

컨테이너 배포 또는 호스트 CUDA/PyTorch 페어링을 우회하려면 게시된 Docker Hub 이미지를 사용하세요. 일반적인 docker run은 Hugging Face 캐시를 마운트하고 게이트드 모델을 풀링할 때 HF_TOKEN을 전달합니다.

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

프로덕션 스타일 이미지의 경우, **latest-runtime**은 빌드 도구와 개발 종속성을 제거하여 기본 latest 변종보다 이미지가 훨씬 작게 유지됩니다.

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

소스 및 기타 배포 방법에서 설치

SGLang 에 대해 개발하거나 로컬 패치를 적용하려면 릴리스 브랜치를 복제하고 편집 가능 모드에서 Python 패키지를 설치하세요:

git clone -b v0.5.9 https://github.com/sgl-project/sglang.git
cd sglang

pip install --upgrade pip
pip install -e "python"

오케스트레이션의 경우, 저장소에는 Kubernetes 매니페스트 (단일 및 다중 노드) 와 최소한의 Docker Compose 레이아웃이 포함되어 있어 커스텀 와이링을 시작하기 전 합리적인 출발점이 됩니다.

YAML 설정 파일 및 환경 변수를 사용하여 SGLang 서버 인자 구성 방법

SGLang 구성은 서버 인자와 환경 변수에 의해 주도됩니다. 플래그에는 모델 선택, 병렬화, 메모리 및 최적화 노브가 포함되어 있으며, 전체 목록은 python3 -m sglang.launch_server --help에서 확인할 수 있습니다.

환경 변수는 SGL_와 SGLANG_ 두 개의 접두사를 사용합니다 (많은 플래그가 CLI 또는 env 형식 모두를 받아들이며, launch_server --help에서 매핑을 보여줍니다).

일부 일반적인 환경 변수에는 SGLANG_HOST_IP와 SGLANG_PORT와 같은 호스트 및 포트 제어 변수가 포함됩니다.

재현 가능한 SGLang 서버 실행을 위한 YAML 설정 파일 사용

반복 가능한 배포와 짧은 명령 줄을 위해 --config로 YAML 파일을 전달합니다. 둘 다 동일한 옵션을 설정할 경우 CLI 인자가 파일의 값을 덮어씁니다.

# config.yaml 생성
cat > config.yaml << 'EOF'
model-path: meta-llama/Meta-Llama-3-8B-Instruct
host: 0.0.0.0
port: 30000
tensor-parallel-size: 2
enable-metrics: true
log-requests: true
EOF

# 설정 파일로 서버 시작
python -m sglang.launch_server --config config.yaml

기억해야 할 몇 가지 구성 및 튜닝 필수 사항:

SGLang 의 --model-path는 로컬 폴더 또는 Hugging Face 저장소 ID 를 가리킬 수 있어, 서비스 코드를 변경하지 않고도 로컬 가중치와 허브 호스팅 모델 간을 쉽게 전환할 수 있습니다.

멀티 GPU 환경에서는 --tp로 텐서 병렬화를 활성화하세요. 시작 시 “peer access is not supported between these two devices” 오류가 발생하면 --enable-p2p-check를 추가하세요.

서비스 중 OOM(메모리 부족) 이 발생하면 --mem-fraction-static을 더 작은 값으로 줄여 KV 캐시 압력을 낮추세요 (기본값은 0.9).

긴 프롬프트의 프리필 중 OOM 이 발생하면 --chunked-prefill-size를 낮추세요.

OpenAI 호환 SGLang 서버 실행 및 OpenAI Python 클라이언트에서 호출 방법

실용적인 “성공 경로” 워크플로우는 다음과 같습니다:

  1. SGLang 설치 (uv/pip 또는 Docker).
  2. 선택한 모델과 포트로 서버 시작.
  3. OpenAI 호환 엔드포인트를 통한 기본 서비스 확인.
  4. OpenAI SDK 의 base_url을 로컬 서버로 지시하여 애플리케이션 통합.
  5. 실제 트래픽이 있는 후 서버 인자로 처리량 및 메모리 튜닝.

OpenAI SDK 를 사용하여 SGLang 에 로컬 채팅 완료 요청 보내기

OpenAI 호환 사용 시 두 가지 세부 사항이 중요합니다:

서버는 OpenAI HTTP 표면 (surface) 을 구현하며, 토크나이저가 제공하는 경우 Hugging Face 채팅 템플릿을 자동으로 적용합니다. 필요시 시작 시 --chat-template로 오버라이드하세요.

OpenAI 클라이언트를 서버의 /v1 접두사 (base_url → http://<host>:<port>/v1) 로 지시한 후, 평소와 같이 client.chat.completions.create(...)를 호출합니다.

서버는 다음 엔트리포인트 중 하나로 시작합니다: python -m sglang.launch_server는 여전히 작동하지만, **sglang serve**가 선호되는 CLI 입니다.

# 권장 CLI 엔트리포인트
sglang serve --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

# 여전히 지원됨
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

그런 다음 OpenAI Python 클라이언트를 사용하여 호출합니다:

import openai

client = openai.Client(base_url="http://127.0.0.1:30000/v1", api_key="None")

response = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "3 개 국가와 수도를 나열하세요."}],
    temperature=0,
    max_tokens=64,
)

print(response.choices[0].message.content)

SGLang 오프라인 엔진 API 및 네이티브 엔드포인트를 사용한 배치 추론 실행 방법

SGLang 은 구축하는 내용에 따라 여러 “API 표면"을 지원합니다:

/generate 엔드포인트는 로우레벨 런타임 API 입니다. 채팅 템플릿과 일반적인 클라이언트 생태계를 자동으로 처리하고 싶다면 /v1/... OpenAI 호환 라우트를 선호하세요.

HTTP 서버 없이 **오프라인 엔진 (Offline Engine)**은 프로세스 내에서 추론을 실행합니다: 배치 작업 및 커스텀 서비스에 적합합니다. 동기/비동기 및 스트리밍/비스트리밍 조합을 지원하므로 호출 패턴에 맞는 모드를 선택하세요.

네이티브 /generate 엔드포인트 사용 예제

최소 패턴: 서버를 실행한 후 temperature와 max_new_tokens(및 필요한 기타 샘플링 필드) 를 포함하여 /generate에 POST 합니다.

import requests

response = requests.post(
    "http://localhost:30000/generate",
    json={
        "text": "프랑스의 수도는",
        "sampling_params": {
            "temperature": 0,
            "max_new_tokens": 32,
        },
    },
)

print(response.json())

temperature = 0은 탐욕적 샘플링 (greedy sampling) 이며, 더 높은 값은 다양성을 증가시킵니다.

프로세스 내 배치 추론을 위한 오프라인 엔진 API 사용 예제

일반적인 흐름: sgl.Engine(model_path=...)를 구성하고, 프롬프트 배치에 대해 llm.generate(...)를 실행한 후 **llm.shutdown()**을 호출하여 GPU 및 기타 리소스를 해제합니다.

import sglang as sgl

llm = sgl.Engine(model_path="qwen/qwen2.5-0.5b-instruct")

prompts = [
    "간결한 자기소개 작성.",
    "프refix 캐싱이 무엇인지 한 단락으로 설명하세요.",
]

sampling_params = {"temperature": 0.2, "top_p": 0.9}

outputs = llm.generate(prompts, sampling_params)
for prompt, output in zip(prompts, outputs):
    print("PROMPT:", prompt)
    print("OUTPUT:", output["text"])
    print()

llm.shutdown()