[SGLang] Server Args: 300+ 서버 인자 완전 가이드

들어가며

SGLang 서버의 동작은 ServerArgs 데이터클래스의 300개 이상의 인자로 제어된다. 모델 로딩, 양자화, 메모리 관리, 스케줄링, 어텐션 백엔드, LoRA, 분산 추론 등 모든 설정이 여기에 집약된다. 이 포스트에서는 주요 카테고리별 핵심 인자를 정리한다.

구조도

ServerArgs (dataclass)
├── 모델 & 토크나이저    ── model_path, tokenizer_path, load_format, ...
├── HTTP 서버           ── host, port, ssl_*, ...
├── 양자화 & 데이터 타입 ── dtype, quantization, kv_cache_dtype, ...
├── 메모리 & 스케줄링    ── mem_fraction_static, chunked_prefill_size, ...
├── 런타임 옵션          ── device, tp_size, pp_size, random_seed, ...
├── 로깅 & 메트릭        ── log_level, enable_metrics, enable_trace, ...
├── API                 ── api_key, chat_template, reasoning_parser, ...
├── 데이터 병렬          ── dp_size, load_balance_method, ...
├── LoRA               ── enable_lora, max_lora_rank, lora_paths, ...
├── 커널 백엔드          ── attention_backend, sampling_backend, ...
└── Speculative         ── speculative_algorithm, num_speculative_steps, ...

핵심 카테고리 분석

모델 & 토크나이저

model_path: str                    # 모델 경로 (필수)
tokenizer_path: Optional[str] = None
load_format: str = "auto"          # auto, safetensors, gguf, ...
trust_remote_code: bool = False
context_length: Optional[int] = None  # None이면 config에서 파생
model_impl: str = "auto"           # auto, sglang, transformers

load_format은 14가지 포맷을 지원한다: auto, pt, safetensors, gguf, bitsandbytes, sharded_state, layered 등이다.

양자화

quantization: Optional[str] = None
kv_cache_dtype: str = "auto"       # auto, fp8_e5m2, ...
enable_fp32_lm_head: bool = False

지원하는 양자화 방식은 22가지가 넘는다.

QUANTIZATION_CHOICES = [
    "awq", "fp8", "mxfp8", "gptq", "marlin", "gptq_marlin",
    "awq_marlin", "bitsandbytes", "gguf", "modelopt",
    "modelopt_fp8", "modelopt_fp4", "w8a8_int8", "w8a8_fp8",
    "moe_wna16", "qoq", "w4afp8", "mxfp4", ...
]

메모리 & 스케줄링

mem_fraction_static: Optional[float] = None   # GPU 메모리 중 KV 캐시 비율
max_running_requests: Optional[int] = None
chunked_prefill_size: Optional[int] = None     # Chunked Prefill 크기
max_prefill_tokens: int = 16384
schedule_policy: str = "fcfs"                  # fcfs, lof, random, ...
page_size: Optional[int] = None               # KV 캐시 페이지 크기

커널 백엔드

어텐션 백엔드만 17가지를 지원한다.

ATTENTION_BACKEND_CHOICES = [
    "triton", "torch_native", "flex_attention", "nsa",
    "cutlass_mla", "fa3", "fa4", "flashinfer", "flashmla",
    "trtllm_mla", "trtllm_mha", "dual_chunk_flash_attn",
    "aiter", "wave",
    "intel_amx", "ascend", "intel_xpu",
]

MoE 관련 백엔드도 다양하다.

MOE_RUNNER_BACKEND_CHOICES = [
    "auto", "deep_gemm", "triton", "triton_kernel",
    "flashinfer_trtllm", "flashinfer_cutlass", "flashinfer_cutedsl",
    "cutlass",
]

분산 추론

tp_size: int = 1                   # Tensor Parallel 크기
pp_size: int = 1                   # Pipeline Parallel 크기
dp_size: int = 1                   # Data Parallel 크기
attn_cp_size: int = 1              # Attention Context Parallel 크기
moe_dp_size: int = 1               # MoE Data Parallel 크기
nnodes: int = 1                    # 멀티 노드 수

로깅 & Observability

enable_metrics: bool = False        # Prometheus 메트릭 활성화
enable_trace: bool = False          # OpenTelemetry 추적 활성화
otlp_traces_endpoint: str = "localhost:4317"
show_time_cost: bool = False
decode_log_interval: int = 40      # 디코드 로그 간격

Speculative Decoding

speculative_algorithm: Optional[str] = None  # eagle, eagle3, ...
num_speculative_steps: int = 5
speculative_eagle_topk: int = 8
speculative_num_draft_tokens: int = 64

튜닝 가이드 핵심 설정

설정	기본값	튜닝 방향
mem_fraction_static	None (자동)	높일수록 KV 캐시 많음, OOM 주의
chunked_prefill_size	None (자동)	높으면 Prefill 빠름, Decode 지연 가능
max_running_requests	None (자동)	동시 요청 수 제한
tp_size	1	모델이 GPU 1개에 안 들어가면 증가
attention_backend	None (자동)	MLA 모델은 flashmla/cutlass_mla 추천
page_size	None (자동)	NPU에서는 128 기본

관련 포스트

• Model Configuration 시스템: 모델 설정 관리
• Observability: 추적, 메트릭, 프로파일링 인프라

참고

• 소스 코드: python/sglang/srt/server_args.py
• SGLang 공식 문서: sgl-project.github.io