서버 인자

서버 인자 (Server Arguments)

SGLang 서버가 모델을 어떻게 로드하고, 어느 GPU에 어떻게 나누고, 메모리를 얼마나 쓸지를 정하는 게 바로 서버 인자예요. 배포할 때 서버 동작과 성능을 컨트롤하는 CLI 인자 목록을 이 문서에서 정리해 봤어요.

출처: SGLang 공식 문서 — Server Arguments

이 인자들은 터미널에서 python3 -m sglang.launch_server --help로도 직접 확인할 수 있어요. 모델 선택, 병렬 처리 정책, 메모리 관리, 최적화 기법 같은 핵심 측면을 모두 조정할 수 있어요.

흔한 실행 명령

설정 파일 사용하기

인자를 YAML 파일로 관리하면 번거로움을 덜 수 있어요. --config로 설정 파일을 지정하면 되고, CLI 인자가 설정 파일의 값을 덮어써요.

# Create 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

# Launch server with config file
python -m sglang.launch_server --config config.yaml

텐서 병렬 (Tensor Parallelism)

멀티 GPU 텐서 병렬을 쓰려면 --tp 2를 추가해요. "peer access is not supported between these two devices" 에러가 나면 실행 명령에 --enable-p2p-check를 추가해요.

python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --tp 2

데이터 병렬 (Data Parallelism)

멀티 GPU 데이터 병렬은 --dp 2로 켜요. 메모리가 충분하다면 데이터 병렬이 throughput에 더 좋아요. 텐서 병렬과 함께 쓸 수도 있어요. 아래 명령은 총 4개 GPU를 쓰는 예시예요. 데이터 병렬에는 SGLang Model Gateway를 권장해요.

python -m sglang_router.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --dp 2 --tp 2

메모리 관련

서빙 중 메모리 부족(out-of-memory)이 나면 KV cache 풀의 메모리 사용을 줄여 보는 게 첫 번째 방법이에요. --mem-fraction-static을 더 작게 설정하면 돼요.

python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --mem-fraction-static 0.7

긴 프롬프트의 prefill 중 OOM이 나면 chunked prefill 크기를 줄여 봐요.

python -m sglang.launch_server --model-path meta-llama/Meta-Llama-3-8B-Instruct --chunked-prefill-size 4096

도커나 Kubernetes로 실행할 때는 프로세스 간 통신용 공유 메모리 설정이 필요해요. 도커는 --shm-size, Kubernetes는 /dev/shm 크기 업데이트를 확인해요.

양자화

fp8 가중치 양자화는 fp16 체크포인트에 --quantization fp8를 추가하거나, fp8 체크포인트를 인자 지정 없이 바로 로드하면 돼요. fp8 KV cache 양자화는 --kv-cache-dtype fp8_e4m3 또는 --kv-cache-dtype fp8_e5m2로 켜요.

결정적 추론 (Deterministic Inference)

결정적 추론과 배치 불변 연산을 켜려면 --enable-deterministic-inference를 추가해요. 자세한 내용은 결정적 추론 문서에 있어요.

미디어 도메인 제한

멀티모달 서버가 신뢰할 수 없는 클라이언트의 요청을 받는다면 --allowed-media-domains로 원격 이미지·비디오·오디오 URL을 제한할 수 있어요. SGLang은 초기 URL과 모든 리다이렉트 대상 URL을 정확한 호스트명 허용 목록과 대조해요. 원격 미디어 다운로드는 기본 64 MiB로 제한되며, 더 큰 신뢰 미디어가 필요하면 --media-url-max-file-size-mb로 조정해요.

python -m sglang.launch_server \
  --model-path Qwen/Qwen2.5-VL-7B-Instruct \
  --allowed-media-domains upload.wikimedia.org raw.githubusercontent.com

--allowed-media-domains가 없으면 하위 호환을 위해 모든 도메인의 HTTP(S) 미디어가 허용돼요. 그 구성을 신뢰할 수 없는 사용자에게 노출하지 마세요. 로컬 경로와 data: URL은 도메인 허용 목록의 적용을 받지 않아요.

MLA 모델의 디코드 컨텍스트 병렬

MLA 모델을 위한 디코드 컨텍스트 병렬은 --dcp-size N으로 켜요. 자세한 내용은 Decode Context Parallelism 문서를 참고해요.

커스텀 채팅 템플릿

모델이 Hugging Face 토크나이저에 채팅 템플릿이 없으면 커스텀 채팅 템플릿을 지정할 수 있어요. 토크나이저에 명명된 템플릿이 여러 개면(예: 'default', 'tool_use') --hf-chat-template-name tool_use로 하나를 고를 수 있어요.

다중 노드 텐서 병렬

다중 노드에서 텐서 병렬을 실행하려면 --nnodes 2를 추가해요. 노드당 GPU 2개인 2개 노드에서 TP=4를 돌리고 싶다면, 첫 노드의 호스트명을 sgl-dev-0, 사용 가능한 포트를 50000으로 잡고 아래 명령을 쓰면 돼요. 데드락이 나면 --disable-cuda-graph를 추가해 보는 것도 방법이에요.

# Node 0
python -m sglang.launch_server \
  --model-path meta-llama/Meta-Llama-3-8B-Instruct \
  --tp 4 \
  --dist-init-addr sgl-dev-0:50000 \
  --nnodes 2 \
  --node-rank 0

# Node 1
python -m sglang.launch_server \
  --model-path meta-llama/Meta-Llama-3-8B-Instruct \
  --tp 4 \
  --dist-init-addr sgl-dev-0:50000 \
  --nnodes 2 \
  --node-rank 1

torch.compile

(참고: 이 기능은 유지보수가 중단된 상태라 에러를 낼 수 있어요.)

torch.compile 가속은 --enable-torch-compile로 켜요. 작은 모델을 작은 배치 크기로 돌릴 때 빨라져요. 기본적으로 캐시 경로는 /tmp/torchinductor_root에 있고, 환경 변수 TORCHINDUCTOR_CACHE_DIR로 커스터마이즈할 수 있어요. 자세한 내용은 PyTorch 공식 문서와 torch.compile 캐시 문서를 참고해요.

인자 카테고리

전체 인자는 아래 범주로 정리돼요. 각 범주 안의 개별 인자와 기본값은 공식 문서 표와 server_args.py에서 확인할 수 있어요.

  • 모델과 토크나이저 (Model and tokenizer): --model-path, --tokenizer-path 등 모델·토크나이저 선택
  • 병렬 처리 (Parallelism): --tp, --dp, --nnodes, --node-rank 등 텐서·데이터 병렬과 다중 노드 설정
  • 메모리 관리 (Memory): --mem-fraction-static, --chunked-prefill-size, --max-total-num-tokens 등 KV cache와 메모리 정책
  • 성능 최적화 (Optimization): --cuda-graph-max-bs, --disable-cuda-graph, --enable-torch-compile 등 추론 가속
  • 양자화 (Quantization): --quantization, --kv-cache-dtype 등
  • 샘플링과 채팅: --sampling-defaults, --chat-template, --hf-chat-template-name 등
  • 관측성 (Observability): --enable-metrics, --log-requests 등

더 알아보기 (Learn more)