환경 변수
환경 변수 (Environment Variables)
이 문서는 SGLang의 런타임 동작을 구성하는 데 사용할 수 있는 다양한 환경 변수의 종합 목록이에요. 시간이 지나며 계속 갱신되도록 유지되고 있어요.
출처: 문서
본문
SGLang은 런타임 동작을 구성하기 위해 사용할 수 있는 다양한 환경 변수를 지원해요. 이 문서는 포괄적인 목록을 제공하고 시간이 지나며 계속 갱신되도록 유지돼요.
참고: 모든 SGLang 환경 변수의 정식 접두사는 SGLANG_이에요. 레거시 SGL_ 접두사는 더 이상 사용되지 않아요. 환경에 설정된 모든 SGL_* 변수는 import 시점에 SGLANG_* 동등 변수로 자동 재작성되고 폐기 경고가 표시되며, 이 별칭은 향후 릴리스에서 제거될 거예요. 일부 변수는 그 정식 이름 때문에 상류/벤더 접두사(예: MOONCAKE_*, ASCEND_*)를 유지해요.
일반 구성 (General Configuration)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_USE_MODELSCOPE |
ModelScope에서 모델 사용 활성화 | false |
SGLANG_HOST_IP |
서버 호스트 IP 주소 | 0.0.0.0 |
SGLANG_PORT |
서버 포트 | auto-detected |
SGLANG_LOGGING_CONFIG_PATH |
사용자 정의 로깅 구성 경로 | Not set |
SGLANG\_LOG\_REQUEST\_HEADERS |
--log-requests가 활성화될 때 로그할 추가 HTTP 헤더의 쉼표 구분 목록. 기본 x-smg-routing-key에 추가됨 |
Not set |
SGLANG\_HEALTH\_CHECK\_TIMEOUT |
헬스 체크 타임아웃(초) | 20 |
SGLANG\_EPLB\_HEATMAP\_COLLECTION\_INTERVAL |
각 레이어 및 GPU rank에서 선택된 물리 전문가 수의 메트릭을 수집하는 패스 간격. 0은 비활성 | 0 |
SGLANG\_EPLB\_P2P\_BATCH\_CHUNK\_SIZE |
EPLB 재균형 중 P2P 연산을 제출할 때 배치당 전문가 ID 수 (CUDA 및 ROCm). 더 작은 값은 NCCL/RCCL GPU 측 누적 hang을 방지하지만 오버헤드를 증가. >= num\_physical\_experts로 설정하면 단일 배치 제출. 폐기 별칭: SGLANG\_EPLB\_ROCM\_P2P\_BATCH\_CHUNK\_SIZE |
32 |
SGLANG\_FORWARD\_UNKNOWN\_TOOLS |
알려지지 않은 도구 호출을 버리는 대신 클라이언트로 전달 | false (알려지지 않은 도구 버림) |
SGLANG\_REQ\_WAITING\_TIMEOUT |
스케줄 전 큐에서 대기하는 요청의 타임아웃(초) | -1 |
SGLANG\_REQ\_RUNNING\_TIMEOUT |
디코드 배치에서 실행 중인 요청의 타임아웃(초) | -1 |
SGLANG\_CACHE\_DIR |
모델 가중치와 기타 데이터의 캐시 디렉터리. 또한 컴파일 커널 캐시의 기본 루트. 그 자체의 env 변수(TRITON_CACHE_DIR, TORCHINDUCTOR_CACHE_DIR, FLASHINFER_WORKSPACE_BASE, CUDA_CACHE_PATH, SGLANG_DG_CACHE_DIR)가 명시적으로 설정되지 않으면 Triton, Inductor, FlashInfer, CUDA 드라이버, DeepGEMM이 그 아래로 지정됨 |
\~/.cache/sglang |
SGLANG\_QWEN4\_PLE\_FILE\_DIR |
파일 백업 Qwen4-Exp PLE 테이블(--ple-offload-backend file)의 기본 디렉터리. 그 아래에 모델 경로당 하나의 하위 디렉터리 생성 |
{SGLANG_CACHE_DIR}/ple |
SGLANG\_QWEN4\_PLE\_FILE\_PREFETCH |
prefill 크기의 PLE gather가 파일 백업 테이블에서 읽으려는 행으로 페이지 캐시(posix_fadvise(WILLNEED))를 힌트 처리. 비활성화하려면 0 설정 |
1 |
SGLANG\_QWEN4\_PLE\_FILE\_SKIP\_DEVICE\_CHECK |
파일 백업 PLE 테이블을 사용하기 전 호스트 페이지 테이블을 통해 페이지 가능한 호스트 메모리를 읽는지 확인(cudaDevAttrPageableMemoryAccessUsesHostPageTables)하는 로드 시점 검사를 건너뜀. 쿼리할 수 없는 디바이스 전용 |
0 |
SGLANG\_QWEN4\_PLE\_FILE\_RSS\_BUDGET\_GB |
파일 백업 PLE 매핑의 상주 세트에 대한 캡(GiB). 행 폴트는 전체 페이지 캐시 folio를 매핑하므로 그 외에는 매핑이 전체 테이블로 기어가고 KV 풀 크기를 결정하는 자유 메모리를 소비. 캡을 넘으면 페이지는 MADV_DONTNEED로 드롭되고 페이지 캐시에 유지. 비활성화하려면 0 설정 |
8.0 |
SGLANG\_QWEN4\_PLE\_FILE\_RSS\_INTERVAL\_S |
파일 백업 PLE 매핑의 상주 세트가 SGLANG_QWEN4_PLE_FILE_RSS_BUDGET_GB와 비교되는 빈도 |
30.0 |
SGLANG\_CUTE\_AOT\_CACHE\_DIR |
프로세스 재시작 간 공유되는 영구 CuTe DSL AOT 객체의 신뢰 디렉터리. 아티팩트는 소스, 런타임 ABI, 호스트 플랫폼, 대상 GPU 아키텍처로 네임스페이스화. 컴파일을 프로세스 로컬로 유지하려면 빈 문자열로 설정. SGLang이 캐시된 객체 파일을 프로세스에 로드하므로 신뢰할 수 있는 사용자만 쓸 수 있는 디렉터리만 사용 | {{SGLANG_CACHE_DIR}}/cute\_aot |
SGLANG\_PREFETCH\_BLOCK\_SIZE\_MB |
워커가 mmap으로 가중치를 로드하기 전 OS 페이지 캐시를 워밍하는 순차 체크포인트 프리페치 읽기의 블록 크기 (MB) | 16 |
성능 튜닝 (Performance Tuning)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_ENABLE_TORCH_INFERENCE_MODE |
torch.inference\_mode 사용 여부 제어 |
false |
SGLANG_ENABLE_TORCH_COMPILE |
torch.compile 활성화 | false |
SGLANG_SET_CPU_AFFINITY |
CPU 친화도 설정 활성화 (종종 Docker 빌드에서 1로 설정) |
false |
SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN |
스케줄러가 더 긴 컨텍스트 길이 요청을 덮어쓸 수 있게 허용 (종종 Docker 빌드에서 1로 설정) |
false |
SGLANG_IS_FLASHINFER_AVAILABLE |
FlashInfer 가용성 검사 제어 | true |
SGLANG_FLASHINFER_AUTOTUNE_CACHE |
실행 간 SGLANG_CACHE_DIR의 지속 FlashInfer autotune 결과 재사용. 0은 매 시작 시 재-autotune 강제. 새 결과는 runs/<rank>.<timestamp>.json 형제 파일에 기록 (정식 캐시는 건드리지 않음) |
true |
SGLANG_SKIP_P2P_CHECK |
P2P(peer-to-peer) 접근 검사 건너뜀 | false |
SGLANG_CHUNKED_PREFIX_CACHE_THRESHOLD |
chunked prefix 캐싱 활성화 임계값 설정 | 8192 |
SGLANG_MAX_KV_CHUNK_CAPACITY |
DeepSeek MHA chunked prefix 캐시의 각 KV 청크 최대 토큰 수 | 131072 |
SGLANG_FUSED_MLA_ENABLE_ROPE_FUSION |
Fused Multi-Layer Attention에서 RoPE 융합 활성화 | 1 |
SGLANG_DISABLE_CONSECUTIVE_PREFILL_OVERLAP |
연속 prefill 배치의 오버랩 스케줄 비활성화 | false |
SGLANG_SCHEDULER_MAX_RECV_PER_POLL |
폴당 최대 요청 수 설정, 음수 값은 제한 없음 의미 | -1 |
SGLANG\_MAX\_NEW\_TOKENS\_LIMIT |
각 생성 요청의 max_new_tokens에 대한 서버 측 하드 제한. 더 요청하는 요청은 잘림. 미설정 또는 비양수 시 비활성 |
Not set |
SGLANG_DATA_PARALLEL_BUDGET_INTERVAL |
DPBudget 업데이트 간격 | 1 |
SGLANG_SCHEDULER_RECV_SKIPPER_WEIGHT_DEFAULT |
스케줄러 recv skipper 카운터의 기본 가중치 값 (forward 모드가 특정 모드와 일치하지 않을 때 사용). --scheduler-recv-interval > 1일 때만 활성. 카운터는 가중치를 축적하고 간격 임계값에 도달하면 요청 폴링을 트리거 |
1000 |
SGLANG_SCHEDULER_RECV_SKIPPER_WEIGHT_DECODE |
스케줄러 recv skipper의 decode forward 모드 가중치 증가. --scheduler-recv-interval과 함께 작동해 디코드 단계의 폴링 빈도 제어 |
1 |
SGLANG\_SCHEDULER\_RECV\_SKIPPER\_WEIGHT\_TARGET\_VERIFY |
스케줄러 recv skipper의 target verify forward 모드 가중치 증가. --scheduler-recv-interval과 함께 작동해 검증 단계의 폴링 빈도 제어 |
1 |
SGLANG_SCHEDULER_RECV_SKIPPER_WEIGHT_NONE |
스케줄러 recv skipper에서 forward 모드가 None일 때 가중치 증가. --scheduler-recv-interval과 함께 작동해 특정 forward 모드가 없을 때 폴링 빈도 제어 |
1 |
SGLANG_MM_BUFFER_SIZE_MB |
멀티모달 피처 해싱 최적화용 사전 할당 GPU 버퍼 크기 (MB). 양수 값으로 설정하면 더 빠른 해시 계산을 위해 피처를 GPU로 임시 이동한 다음 GPU 메모리를 절약하기 위해 CPU로 되돌림. 더 큰 피처가 GPU 해싱에서 더 이득. 비활성화하려면 0 설정 |
0 |
SGLANG_MM_PRECOMPUTE_HASH |
MultimodalDataItem의 해시 값 사전 계산 활성화 | false |
SGLANG_NCCL_ALL_GATHER_IN_OVERLAP_SCHEDULER_SYNC_BATCH |
오버랩 스케줄러에서 mlp sync batch 준비 시 gather에 NCCL 활성화 (이 플래그 없이는 gather에 gloo 사용) | false |
SGLANG_SYMM_MEM_PREALLOC_GB_SIZE |
메모리 단편화를 제한하기 위한 NCCL 대칭 메모리 풀용 사전 할당 GPU 버퍼 크기 (GB). 서버 인자 --enable-symm-mem이 설정된 경우에만 효과 |
-1 |
SGLANG\_SKIP\_SOFTMAX\_PREFILL\_THRESHOLD\_SCALE\_FACTOR |
flashinfer의 TRT-LLM prefill 어텐션용 skip-softmax 임계값 스케일 인자. None은 표준 어텐션 의미. https://arxiv.org/abs/2512.12087 참고 |
None |
SGLANG\_SKIP\_SOFTMAX\_DECODE\_THRESHOLD\_SCALE\_FACTOR |
flashinfer의 TRT-LLM decode 어텐션용 skip-softmax 임계값 스케일 인자. None은 표준 어텐션 의미. https://arxiv.org/abs/2512.12087 참고 |
None |
SGLANG\_USE\_SGL\_FA3\_KERNEL |
FlashAttention v3에 sgl-kernel 구현 사용 | true |
DeepGEMM 구성 (고급 최적화) (DeepGEMM Configuration)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_ENABLE_JIT_DEEPGEMM |
DeepGEMM 커널의 JIT(Just-In-Time) 컴파일 활성화 (DeepGEMM 패키지가 설치된 NVIDIA Hopper (SM90) 및 Blackwell (SM100) GPU에서 기본 활성. 비활성화하려면 "0" 설정) |
"true" |
SGLANG_JIT_DEEPGEMM_PRECOMPILE |
DeepGEMM 커널 사전 컴파일 활성화 | "true" |
SGLANG_JIT_DEEPGEMM_COMPILE_WORKERS |
병렬 DeepGEMM 커널 컴파일용 워커 수 | 4 |
SGLANG_IN_DEEPGEMM_PRECOMPILE_STAGE |
DeepGEMM 사전 컴파일 스크립트 중 사용되는 표시 플래그 | "false" |
SGLANG_DG_CACHE_DIR |
컴파일된 DeepGEMM 커널 캐싱 디렉터리 | {SGLANG_CACHE_DIR}/deep_gemm |
SGLANG\_DG\_USE\_NVRTC |
JIT 컴파일에 (Triton 대신) NVRTC 사용 (실험적) | "false" |
SGLANG\_USE\_DEEPGEMM\_BMM |
배치 행렬 곱셈 (BMM) 연산에 DeepGEMM 사용 | "false" |
SGLANG\_JIT\_DEEPGEMM\_FAST\_WARMUP |
워밍업 중 더 적은 커널 사전 컴파일, 워밍업 시간을 30분에서 3분 미만으로 단축. 런타임 중 성능 저하를 일으킬 수 있음 | "false" |
DeepEP 구성 (DeepEP Configuration)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_DEEPEP_NUM_MAX_DISPATCH_TOKENS_PER_RANK |
각 GPU의 최대 디스패치 토큰 수 | "128" |
SGLANG_FLASHINFER_NUM_MAX_DISPATCH_TOKENS_PER_RANK |
--moe-a2a-backend=flashinfer의 각 GPU 최대 디스패치 토큰 수 |
"1024" |
SGLANG\_FLASHINFER\_MEGAMOE\_COMBINE\_DTYPE |
FlashInfer NVFP4 MegaMOE 크로스-rank combine 유선 형식. 지원 값은 bf16, mxfp8, nvfp4. 양자화 형식은 SGLANG\_FLASHINFER\_MEGAMOE\_IN\_KERNEL\_FC2\_REDUCE=1와 호환되지 않음 |
"bf16" |
SGLANG\_FLASHINFER\_MEGAMOE\_MAX\_TOKENS\_PER\_RANK |
rank당 FlashInfer MegaMOE 대칭 워크스페이스 토큰 용량. 0 값은 런타임 토큰 한도에서 용량 파생 |
0 |
SGLANG\_FLASHINFER\_MEGAMOE\_IN\_KERNEL\_FC2\_REDUCE |
CuTe DSL MegaMOE 인커널 FC2 리덕션 사용. 워크스페이스 크기를 줄이고 대규모 배치 성능을 개선할 수 있지만 BF16 원자 누적은 비결정적. 양자화 combine dtype과 호환되지 않음 | "false" |
SGLANG_DEEPEP_LL_COMBINE_SEND_NUM_SMS |
단일 배치 오버랩이 활성화될 때 DeepEP combine에 사용되는 SM 수 | "32" |
SGLANG_BLACKWELL_OVERLAP_SHARED_EXPERTS_OUTSIDE_SBO |
GB200에서 단일 배치 오버랩이 활성화될 때 공유 전문가를 대체 스트림에서 실행. 이 플래그를 설정하지 않으면 공유 전문가와 down gemm이 DeepEP combine과 함께 오버랩 | "false" |
SGLANG_ENABLE_QWEN_DEEPEP_SHARED_OVERLAP |
DeepEP가 라우팅 전문가를 실행하는 동안 Qwen 공유 전문가를 대체 CUDA 스트림에서 실행 | "true" |
SGLANG\_DISABLED\_MODEL\_ARCHS |
자동 등록에서 비활성화할 모델 아키텍처의 쉼표 구분 목록 | Not set |
SGLANG\_SORT\_WEIGHT\_FILES |
로드 시점 I/O 최적화용 가중치 파일 순서 제어. -1은 정렬/스트래거링 비활성 (원래 순서). 0은 파일만 정렬. 0보다 큰 k 값은 더 나은 다중 rank I/O 동시성을 위해 계수 k로 rank별 순서를 정렬하고 스트래거 |
0 |
SGLANG\_RETURN\_ORIGINAL\_LOGPROB |
샘플링 후 값 대신 원래(pre-temperature) logprob 반환 | false |
SGLANG\_ENABLE\_COLOCATED\_BATCH\_GEN |
공동 배치 배치 생성을 활성화 | false |
SGLANG\_ENABLE\_MOE\_DEFERRED\_FINALIZE |
MoE finalize 단계를 다른 작업과 오버랩하도록 지연 | true |
SGLANG\_PATCH\_TOKENIZER |
all\_special\_tokens/all\_special\_ids를 캐시하도록 토크나이저 패치 (특히 Kimi tiktoken의 경우 높은 배치 크기에서 ITL이 그 외라면 악화될 수 있음) |
true |
SGLANG\_ENABLE\_LOGPROB\_CHUNK |
피크 메모리를 줄이기 위해 logits를 청크로 처리 | true |
SGLANG\_LOGPROB\_CHUNK\_SIZE |
logits-processor 청킹이 활성화될 때 사용되는 청크 크기 (토큰) | 2048 |
SGLANG\_FLASHINFER\_USE\_PAGED |
페이징 FlashInfer 어텐션 경로 사용 | false |
SGLANG\_FLASHINFER\_WORKSPACE\_SIZE |
FlashInfer 워크스페이스 크기(바이트) (기본 ≈ 384 MiB) | 402653184 |
SGLANG\_EAGER\_INPUT\_NO\_COPY |
eager forward에서 ForwardBatch 자체 텐서를 CUDA graph 버퍼 레지스트리에 복사하는 대신 래핑 (반복 디바이스-디바이스 복사 건너뜀) | false |
SGLANG\_DEEPGEMM\_SANITY\_CHECK |
DeepGEMM 커널에 추가 정합성 검사 실행 | false |
SGLANG\_DEEPGEMM\_PDL |
DeepGEMM 커널에 Programmatic Dependent Launch (PDL) 활성화 | true |
SGLANG\_PP\_PARALLEL\_DEEPGEMM\_WARMUP |
파이프라인 병렬 rank에 걸쳐 DeepGEMM 워밍업 병렬 실행 | false |
SGLANG\_DISABLE\_STATIC\_WATERFILL |
기본 정적 로컬 배치 경로 대신 런타임 EP all-reduce로 동적 Waterfill 강제 | false |
SGLANG\_NIXL\_EP\_BF16\_DISPATCH |
NIXL-EP 디스패치에 BF16 사용 | false |
SGLANG\_NIXL\_EP\_NUM\_MAX\_DISPATCH\_TOKENS\_PER\_RANK |
NIXL-EP용 GPU당 최대 디스패치 토큰 수 | 128 |
MORI 구성 (MORI Configuration)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_MORI\_DISPATCH\_DTYPE |
MoRI-EP 디스패치 양자화 유형 오버라이드. auto는 가중치 dtype에서 자동 감지. bf16/fp8/fp4는 모든 레이어에 지정 유형 강제 |
"auto" |
SGLANG\_MORI\_COMBINE\_DTYPE |
combine dtype: auto, bf16, fp8, fp4 또는 fp8\_direct\_cast |
"auto" |
MORI\_DISABLE\_AUTO\_XGMI |
활성 RDMA 디바이스가 없을 때 Mori가 동일 노드 PD disaggregation에 XGMI를 자동 사용하도록 허용하려면 0 설정 |
unset |
SGLANG\_MORI\_NUM\_MAX\_DISPATCH\_TOKENS\_PER\_RANK |
MORI-EP 버퍼 할당의 rank당 최대 디스패치 토큰 수 | 4096 |
SGLANG\_MORI\_DISPATCH\_INTER\_KERNEL\_SWITCH\_THRESHOLD |
InterNodeV1와 InterNodeV1LL 커널 유형 간 전환 임계값. SGLANG\_MORI\_NUM\_MAX\_DISPATCH\_TOKENS\_PER\_RANK이 이 임계값 이하이면 InterNodeV1LL 사용, 그 외 InterNodeV1 사용 |
256 |
SGLANG\_MORI\_PREALLOC\_MAX\_RECV\_TOKENS |
이 인자는 rank용으로 사전 할당된 토큰 양을 나타내는 SGLANG\_MORI\_NUM\_MAX\_DISPATCH\_TOKENS\_PER\_RANK을 유도. 유효 범위는 1부터 world_size*SGLANG_MORI_NUM_MAX_DISPATCH_TOKENS_PER_RANK까지. 기본 0은 최대 의미. 더 작은 값은 메모리 사용을 줄이지만 너무 작으면 버퍼 오버플로우 초래 |
0 |
SGLANG\_MORI\_MOE\_MAX\_INPUT\_TOKENS |
MoE 계산 전 디스패치 버퍼를 이만큼의 행으로 자름, 패딩 토큰의 커널 오버헤드 감소. 값은 실제 수신 토큰 수(totalRecvTokenNum)보다 크거나 같아야 함. 너무 작게 설정하면 잘못된 결과 초래. 0은 절단 비활성 (전체 버퍼 사용) |
0 |
SGLANG\_PPLX\_NUM\_MAX\_DISPATCH\_TOKENS\_PER\_RANK |
PPLX (--moe-a2a-backend pplx) NVSHMEM 버퍼 할당의 rank당 최대 디스패치 토큰 수. 최악의 경우 rank당 forward 토큰(rank당 prefill 청크 chunked\_prefill\_size / dp\_size, 또는 decode CUDA-graph 배치 크기)보다 크거나 같아야 함. 그렇지 않으면 서버가 시작 거부 |
128 |
SGLANG\_MORI\_QP\_PER\_TRANSFER |
전송 연산당 사용되는 RDMA Queue Pair (QP) 수 | 1 |
SGLANG\_MORI\_POST\_BATCH\_SIZE |
각 QP에 단일 배치로 게시되는 RDMA 작업 요청 수 | -1 |
SGLANG\_MORI\_NUM\_WORKERS |
RDMA 실행자 스레드 풀의 워커 스레드 수 | 1 |
DSA 백엔드 구성 (DeepSeek V3.2용) (DSA Backend Configuration)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_DSA\_FUSE\_TOPK |
topk logits 선택과 페이지 테이블에서 topk 인덱스 선택 연산 융합 | true |
SGLANG\_DSA\_TOPK\_FLASHINFER\_DETERMINISTIC |
--dsa-topk-backend=flashinfer 또는 --speculative-dsa-topk-backend=flashinfer일 때 결정적 FlashInfer topk 커널 사용 |
false |
SGLANG\_DSA\_TOPK\_FLASHINFER\_TIE\_BREAK |
--dsa-topk-backend=flashinfer 또는 --speculative-dsa-topk-backend=flashinfer일 때 FlashInfer DSA topk의 타이브레이크 모드: 미설정은 명시적 타이브레이킹 비활성, small은 동일 점수에서 더 작은 후보 인덱스 선호, large는 동일 점수에서 더 큰 후보 인덱스 선호. 이 변수를 설정하면 FlashInfer가 결정적 topk 사용 |
unset |
SGLANG\_DSA\_PREFILL\_DENSE\_ATTN\_KV\_LEN\_THRESHOLD |
현재 prefill 배치의 최대 kv len이 이 값을 초과하면 sparse mla 커널 적용, 그 외 dense MHA 구현으로 폴백. 기본은 모델의 index topk (DeepSeek V3.2는 2048) | 2048 |
SGLANG\_DSA\_TOPK\_BROADCAST |
실험적. 활성화 시 attention TP rank 0의 최종 NSA/DSA indexer top-k 결과를 다른 attention TP rank로 브로드캐스트. 일부 속도 비용으로 TP 어텐션 실행의 top-k 불일치 완화 가능 | false |
SGLANG\_MORI\_SEND\_AUX\_RDMA |
CPU 상주 AUX 데이터를 ZMQ TCP 대신 RDMA로 전송 | false |
SGLANG\_MORI\_TRANSFER\_SHARDS |
KV 전송을 배출하는 분할 동기 워커 스레드 수. 미결 전송도 상한 (기본 RDMA 송신 큐 스로틀) | 8 |
SGLANG\_MORI\_WAIT\_POLL\_MS |
전송 워커가 완료를 기다리는 동안 SLA를 확인하기 위해 깨어나는 폴 주기 (ms) | 1000 |
SGLANG\_MORI\_TRANSFER\_TIMEOUT\_MS |
KV 전송이 실패되기 전의 전송당 SLA (ms). 0은 SLA 비활성 |
0 |
SGLANG\_DSA\_HIP\_DISABLE\_PRESHUFFLE |
HIP DSA 경로에서 가중치 프리셔플 비활성화 | false |
SGLANG\_DSA\_MQA\_LOGITS\_FREE\_MEM\_FRACTION |
MQA-logits 단계가 DSA 경로에서 사용할 수 있는 자유 메모리 비율 | 0.2 |
메모리 관리 (Memory Management)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_DEBUG\_MEMORY\_POOL |
메모리 풀 디버깅 활성화 | false |
SGLANG\_CLIP\_MAX\_NEW\_TOKENS\_ESTIMATION |
메모리 계획을 위한 최대 새 토큰 추정 클립 | 4096 |
SGLANG\_DETOKENIZER\_MAX\_STATES |
디토크나이저 최대 상태 | 시스템 기반 기본값 |
SGLANG\_ENABLE\_TP\_MEMORY\_INBALANCE\_CHECK |
Tensor Parallel rank 간 메모리 불균형 검사 활성화 | true |
SGLANG\_MOONCAKE\_CUSTOM\_MEM\_POOL |
Mooncake용 사용자 정의 메모리 풀 유형 구성. NVLINK, BAREX, INTRA\_NODE\_NVLINK 지원. true로 설정하면 NVLINK 기본 설정 |
None |
모델별 옵션 (Model-Specific Options)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_USE\_AITER |
AITER 최적화 구현 사용 | false |
SGLANG\_ROCM\_USE\_MULTI\_STREAM |
DeepseekV2 MoE에서 공유 및 라우팅 전문가를 오버랩하도록 ROCm/AITER에서 alt CUDA/HIP 스트림 할당. HIP env GPU\_MAX\_HW\_QUEUES>=5 필요 (기본 4, HIP가 생성하는 HSA/ROCr HW 큐의 캡) 그래야 alt 스트림이 메인 스트림과 직렬화하는 대신 자체 큐를 얻음. --deepep-mode low\_latency와 짝지어 Mori의 AsyncLL 커널이 dispatch/combine을 복사 엔진으로 오프로드하고 CU를 확보하는 것이 가장 좋음 |
false |
SGLANG\_MOE\_PADDING |
MoE 패딩 활성화 (값이 1이면 패딩 크기 128 설정, 종종 Docker 빌드에서 1 설정) |
false |
SGLANG\_USE\_FUSED\_PARALLEL\_QKNORM |
어텐션 TP 크기 > 1일 때 CUDA의 MiniMax-M2.x에 융합 병렬 QK RMSNorm 커널 사용 | false |
SGLANG\_ENABLE\_STRICT\_MEM\_CHECK\_DURING\_BUSY |
스케줄러가 바쁠 때 엄격 메모리 검사 활성화 | 0 |
SGLANG\_ENABLE\_STRICT\_MEM\_CHECK\_DURING\_IDLE |
스케줄러가 유휴일 때 엄격 메모리 검사 활성화 | true |
SGLANG\_NATIVE\_MOVE\_KV\_CACHE |
KV 캐시 항목 이동에 네이티브 구현 사용 | false |
SGLANG\_USE\_BREAKABLE\_CUDA\_GRAPH |
런타임에 중단/재구축할 수 있는 breakable CUDA graph 사용 | false |
SGLANG\_MEMORY\_SAVER\_CUDA\_GRAPH |
릴리스/재개 메모리 세이버 아래에서 CUDA graph 허용 | false |
SGLANG\_GEMMA\_OUT\_OF\_PLACE\_POSITION\_MUTATION |
Gemma 모델에 out-of-place 위치 변형 사용 | false |
SGLANG\_MAMBA\_CONV\_DTYPE |
Mamba 컨볼루션 상태 dtype | bfloat16 |
SGLANG\_MAMBA\_SSM\_DTYPE |
Mamba SSM 상태 dtype (미설정 시 모델 dtype 기본) | Not set |
SGLANG\_EMBEDDINGS\_SPARSE\_HEAD |
임베딩 모델용으로 노출할 sparse-임베딩 헤드 이름 | Not set |
SGLANG\_DSV4\_FP4\_EXPERTS |
DeepSeek V4 전문가가 FP4를 사용하는지 여부. FP4-대-FP8 변환 DeepSeek V4 체크포인트를 사용할 때 false 설정 |
true |
SGLANG\_DSV4\_REASONING\_EFFORT |
요청이 설정하지 않을 때 DeepSeek V4 채팅 인코더의 기본 reasoning\_effort. preview 프로파일은 high와 max 수용, 공식 프로파일은 low, high, max 수용. 프로파일은 번들 인코더에서 감지. --json-model-override-args '{"dsv4\_reasoning\_effort\_profile":"official"}'로 오버라이드 |
"" |
SGLANG\_DSV41\_REASONING\_EFFORT |
요청이 설정하지 않을 때 DeepSeek-V4.1 채팅 인코더의 기본 reasoning\_effort: low, high, xhigh, max 중 하나 또는 [1, 100]의 정수 예산. 미설정은 인코더 기본 high |
"" |
SGLANG\_DSV4\_USE\_BF16\_KV\_QUANT\_SOURCE |
DeepSeek V4의 경우 FP32 레지스터 대신 BF16 반올림 값에서 SWA FP8 KV 캐시 양자화. 이는 트레이너 측 QAT와 DSA prefill-CP 경로와 일치하며, 추가 BF16 KV materialization과 별도 캐시 저장 커널 비용 발생 | false |
양자화 (Quantization)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_INT4\_WEIGHT |
INT4 가중치 양자화 활성화 | false |
SGLANG\_FORCE\_FP8\_MARLIN |
다른 FP8 커널이 있어도 FP8 MARLIN 커널 강제 사용 | false |
SGLANG\_NVFP4\_CKPT\_FP8\_GEMM\_IN\_ATTN |
DeepSeek NVFP4 체크포인트 실행 시 q\_b\_proj를 BF16에서 FP8로 양자화 |
false |
SGLANG\_MOE\_NVFP4\_DISPATCH |
moe 디스패치에 nvfp4 사용 (flashinfer_cutlass 또는 flashinfer_cutedsl moe runner 백엔드) | "false" |
SGLANG\_FLASHINFER\_NVFP4\_PER\_TOKEN\_ACTIVATION |
직렬화 modelopt\_fp4 체크포인트에 FlashInfer TRT-LLM 또는 CuTe DSL v2 (A2A 없음 또는 FlashInfer A2A) 토큰당 FP32 활성화 스케일링 활성화. 체크포인트 활성화 스케일은 1로 취급 |
false |
SGLANG\_FLASHINFER\_CUTEDSL\_NVFP4\_W4A16 |
NVIDIA SM100-family GPU (SM100/SM103)에서 FlashInfer CuTe DSL NVFP4 가중치와 함께 BF16 활성화 및 출력 사용. 직렬화 dense linear 레이어는 --fp4-gemm-backend flashinfer\_cutedsl로 이 모드 사용. MoE 레이어는 --moe-runner-backend flashinfer\_cutedsl로 사용. MoE 경로는 A2A 없음 또는 FlashInfer A2A로 온라인 가중치 양자화와 직렬화 ModelOpt NVFP4 가중치 지원, SGLANG\_FLASHINFER\_MOE\_FUSED\_FINALIZE 존중 |
false |
SGLANG\_FLASHINFER\_MOE\_FUSED\_FINALIZE |
FlashInfer의 융합 원자 CUTLASS 및 CuTe DSL MoE finalize 사용. 더 나은 수치 정확성을 위해 기본 비활성. 더 공격적인 성능을 위해 1 설정. 결정적 추론은 이를 false로 오버라이드 |
false |
FLASHINFER\_NVFP4\_4OVER6 |
NVFP4 토큰당 활성화 및 온라인 NVFP4 MoE 가중치 양자화 경로에 FlashInfer NVFP4 4over6 스케일링 활성화 | false |
FLASHINFER\_NVFP4\_4OVER6\_E4M3\_USE\_256 |
FlashInfer NVFP4 4over6 스케일링의 E4M3 스케일 최대값으로 256 사용, 그 외 448 사용 |
false |
SGLANG\_NVFP4\_CKPT\_FP8\_NEXTN\_MOE |
DeepSeek NVFP4 체크포인트 실행 시 nextn 레이어의 moe를 BF16에서 FP8로 양자화 | false |
SGLANG\_QUANT\_ALLOW\_DOWNCASTING |
로딩 중 가중치 dtype 다운캐스트 허용 (예: fp32 → fp16). 기본적으로 SGLang은 양자화 사용 시 이런 다운캐스트 거부 | false |
SGLANG\_FP8\_IGNORED\_LAYERS |
FP8 양자화 중 무시할 레이어 이름의 쉼표 구분 목록. 예: model.layers.0,model.layers.1.,qkv\_proj |
"" |
SGLANG\_FP4\_IGNORED\_LAYERS |
modelopt\_fp4 또는 nvfp4\_online의 온라인 FP4 변환에서 제외할 레이어 이름의 쉼표 구분 목록. 예: model.layers.40,model.layers.41 |
"" |
SGLANG\_HUMMING\_ONLINE\_QUANT\_CONFIG |
Humming 온라인 가중치 양자화용 JSON 객체 또는 JSON 파일 경로. 레이어에 체크포인트 양자화 구성이 없으면 이 구성이 로드된 fp16/bf16 가중치를 어떻게 양자화할지 Humming에 알려줌. 체크포인트에 이미 Humming 구성이 있으면 로딩 중 이 스키마로 재양자화하도록 "force\_requant": true 추가. 일반 키는 dtype/weight\_dtype, scale\_dtype, group\_size, scale\_type, ignored\_layers, ignore, modules\_to\_not\_convert 포함 |
None |
SGLANG\_HUMMING\_INPUT\_QUANT\_CONFIG |
Humming 입력 활성화 양자화용 JSON 객체 또는 JSON 파일 경로. 가중치 스키마와 독립적으로 Humming 커널에 전달되는 활성화 dtype 및 스케일 그룹을 제어. 예: {'{"dtype": "float8e4m3"}'}은 Humming 입력을 FP8 E4M3으로 양자화 |
None |
SGLANG\_HUMMING\_USE\_F16\_ACCUM |
Humming compute/tuning 구성에서 FP16 누적 사용. FP16 누적을 지원하는 Humming dtype 조합(예: float16 출력의 fp16 또는 FP8 E4M3 활성화)에서만 의미. 기본 누적기 동작은 false로 유지 |
false |
SGLANG\_HUMMING\_MOE\_GEMM\_TYPE |
표준 디스패치 및 DeepEP normal 디스패치용 Humming MoE GEMM 경로 선택. indexed는 top-k 전문가 id를 직접 사용하고 미설정 또는 알 수 없는 값의 폴백. grouped는 Humming grouped-contiguous GEMM에 매핑. DeepEP low-latency 디스패치는 내부적으로 grouped-masked GEMM을 사용하고 이 셀렉터를 사용하지 않음 |
"" (indexed) |
분산 컴퓨팅 (Distributed Computing)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_BLOCK_NONZERO_RANK_CHILDREN |
0이 아닌 rank 자식 프로세스 차단 제어 | 1 |
SGLANG_IS_FIRST_RANK_ON_NODE |
현재 프로세스가 노드의 첫 rank인지 표시 | "true" |
SGLANG_PP_LAYER_PARTITION |
파이프라인 병렬 레이어 파티션 명세 | Not set |
SGLANG_ONE_VISIBLE_DEVICE_PER_PROCESS |
분산 컴퓨팅용 프로세스당 하나의 가시 디바이스 설정 | false |
SGLANG\_RAY\_BUNDLE\_INDICES |
Ray 액터 배치용 쉼표 구분 번들 인덱스 (예: "0,1,2,3"). world_size와 일치해야 함. 사용자 정의 배치 그룹에서 세밀한 GPU 할당 가능 |
Not set |
SGLANG\_CPU\_QUANTIZATION |
CPU 측 양자화 활성화 | false |
SGLANG\_USE\_DYNAMIC\_MXFP4\_LINEAR |
linear 레이어에 동적 MXFP4 양자화 사용 | false |
USE\_TRITON\_W8A8\_FP8\_KERNEL |
Triton W8A8 FP8 커널 사용 | false |
SGLANG\_USE\_MESSAGE\_QUEUE\_BROADCASTER |
프로세스 간 텐서 브로드캐스트용 공유 메모리 메시지 큐 브로드캐스터 사용 | true |
SGLANG\_DISTRIBUTED\_INIT\_METHOD\_OVERRIDE |
torch.distributed.init\_process\_group가 사용하는 init 방법 오버라이드. MASTER\_ADDR/MASTER\_PORT로 외부 생성 TCPStore를 사용하려면 env:// 설정 |
Not set |
SGLANG\_TCP\_STORE\_PORT |
torch.distributed TCPStore 포트 | 29600 |
SGLANG\_SYNC\_TOKEN\_IDS\_ACROSS\_TP |
텐서 병렬 rank 간 샘플링 토큰 id 동기화 | false |
PD Disaggregation — 스테이징 버퍼 (이기종 TP) (Staging Buffer)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_DISAGG\_STAGING\_BUFFER |
이기종 TP KV 전송용 GPU 스테이징 버퍼 활성화. prefill과 decode가 다른 TP/attention-TP 크기를 사용할 때 필요. 비-MLA 모델 (예: GQA, MHA) 전용 | false |
SGLANG\_DISAGG\_STAGING\_POOL\_SIZE\_MB |
decode 측 링 버퍼 풀 총 크기 (MB). 모든 prefill rank의 RDMA 데이터를 수신하는 공유 버퍼. 더 큰 값은 더 높은 동시성 지원 | 4096 |
SGLANG\_STAGING\_USE\_TORCH |
스테이징 연산에 Triton 융합 커널 대신 PyTorch gather/scatter 폴백 강제 사용. 디버깅에 유용 | false |
테스트 및 디버깅 (내부/CI) (Testing & Debugging)
이 변수들은 주로 내부 테스트, 지속적 통합, 디버깅에 사용돼요.
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_IS\_IN\_CI |
CI 환경에서 실행 중인지 표시 | false |
SGLANG\_IS\_IN\_CI\_AMD |
AMD CI 환경에서 실행 중인지 표시 | false |
SGLANG\_TEST\_RETRACT |
retract decode 테스트 활성화 | false |
SGLANG\_TEST\_RETRACT\_NO\_PREFILL\_BS |
SGLANG_TEST_RETRACT 활성 시 배치 크기가 SGLANG_TEST_RETRACT_NO_PREFILL_BS를 초과하면 prefill 수행 안 함 | 2 \*\* 31 |
SGLANG\_RECORD\_STEP\_TIME |
프로파일링용 스텝 시간 기록 | false |
SGLANG\_TEST\_REQUEST\_TIME\_STATS |
요청 시간 통계 테스트 | false |
SGLANG\_DEBUG\_SYMM\_MEM |
NCCL 통신 연산에 전달되는 텐서가 대칭 메모리 풀에 할당됐는지 확인하는 디버그 검사 활성화. 풀에 없는 텐서에 대한 스택 트레이스로 경고 (rank 0만) 기록 | false |
SGLANG\_KERNEL\_API\_LOGLEVEL |
크래시 디버그 커널 API 로깅 제어. 0은 로깅 비활성, 1은 API 이름, 3은 텐서 메타데이터, 5는 텐서 통계 추가, 10은 호출 전 덤프 스냅샷도 작성 |
0 |
SGLANG\_KERNEL\_API\_LOGDEST |
크래시 디버그 커널 API 로그 대상. stdout, stderr 또는 파일 경로 사용. %i는 프로세스 PID로 대체 |
stdout |
SGLANG\_KERNEL\_API\_DUMP\_DIR |
레벨-10 커널 API 입력/출력 덤프 출력 디렉터리. %i는 프로세스 PID로 대체 |
sglang\_kernel\_api\_dumps |
SGLANG\_KERNEL\_API\_DUMP\_INCLUDE |
레벨-10 덤프에 포함할 커널 API 이름의 쉼표 구분 와일드카드 패턴 | Not set |
SGLANG\_KERNEL\_API\_DUMP\_EXCLUDE |
레벨-10 덤프에서 제외할 커널 API 이름의 쉼표 구분 와일드카드 패턴 | Not set |
프로파일링 및 벤치마킹 (Profiling & Benchmarking)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG_TORCH_PROFILER_DIR |
PyTorch 프로파일러 출력 디렉터리 | /tmp |
SGLANG_PROFILE_WITH_STACK |
PyTorch 프로파일러용 with_stack 옵션 (bool) 설정 (스택 트레이스 캡처) |
true |
SGLANG_PROFILE_RECORD_SHAPES |
PyTorch 프로파일러용 record_shapes 옵션 (bool) 설정 (형태 기록) |
true |
SGLANG_OTLP_EXPORTER_SCHEDULE_DELAY_MILLIS |
트레이싱 활성화 시 BatchSpanProcessor.schedule_delay_millis 구성 | 500 |
SGLANG_OTLP_EXPORTER_MAX_EXPORT_BATCH_SIZE |
트레이싱 활성화 시 BatchSpanProcessor.max_export_batch_size 구성 | 64 |
SGLANG_TRACE_ASYNC |
비동기 트레이싱 활성화: 스팬 생성을 ZMQ를 통해 전용 exporter 프로세스로 오프로드, 추론 핫 경로의 OTel 오버헤드 감소 | false |
SGLANG_TRACE_ASYNC_FLUSH_THRESHOLD |
exporter 프로세스로 자동 플러시 전 버퍼링된 트레이스 연산 수 | 100 |
SGLANG\_PROFILE\_V2 |
v2 프로파일러 구현 사용 | false |
SGLANG\_DETECT\_SLOW\_RANK |
집합 연산 중 뒤처지는 rank 감지 및 보고 | false |
SGLANG\_ENABLE\_RANK\_CONSENSUS\_CHECKER |
PP/TP-rank 발산 검사. 발산 발생 시 서버 종료. 서버 hang 문제 해결에 도움 | False |
SGLANG\_FORCE\_SHUTDOWN |
종료 시 즉시 프로세스 그룹 종료 강제 | false |
SGLANG\_PYSPY\_DUMP\_BEFORE\_CRASH |
크래시 전 모든 프로세스의 py-spy 스택 덤프 캡처 | true |
SGLANG\_CUDA\_COREDUMP |
CUDA coredump 생성 활성화 (필요한 CUDA\_\* env 변수 자동 주입) |
false |
SGLANG\_CUDA\_COREDUMP\_DIR |
CUDA coredump 디렉터리. 미설정 시 CI에서 RUNNER\_TEMP, 그 외 /tmp로 해석 |
Not set |
SGLANG\_CUDA\_COREDUMP\_BEFORE\_CRASH |
크래시 전 CUDA coredump 트리거 | true |
SGLANG\_CUDA\_COREDUMP\_BEFORE\_CRASH\_WAIT\_SECS |
종료 전 CUDA coredump 완료 대기 초 | 60.0 |
저장소 및 캐싱 (Storage & Caching)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_WAIT\_WEIGHTS\_READY\_TIMEOUT |
가중치 대기 타임아웃 기간 | 120 |
SGLANG\_DISABLE\_OUTLINES\_DISK\_CACHE |
Outlines 디스크 캐시 비활성화 | false |
SGLANG\_USE\_CUSTOM\_TRITON\_KERNEL\_CACHE |
더 낮은 오버헤드를 위해 SGLang의 사용자 정의 Triton 커널 캐시 구현 사용 (CUDA에서 자동 활성화) | false |
SGLANG\_HICACHE\_DECODE\_OFFLOAD\_STRIDE |
decode 측 증가 KV 캐시 오프로드 스트라이드. --page-size의 배수로 내림 반올림 (최소 --page-size). 미설정/무효/<=0이면 --page-size로 폴백 |
Not set (--page-size 사용) |
SGLANG\_HICACHE\_NIXL\_USE\_DIRECT\_IO |
캐시 파일을 열 때 파일 기반 NIXL 백엔드(POSIX, GDS, GDS_MT, 3FS)에 O\_DIRECT 활성화 (OS 페이지 캐시 우회, 메모리 압력 감소 및 NVMe 처리량 향상). --hicache-storage-backend-extra-config의 {'{"use_direct_io": false}'}로도 비활성화 가능. 현재 OS에서 O\_DIRECT를 사용할 수 없으면 경고와 함께 버퍼 I/O로 폴백 |
true |
SGLANG\_HUGEPAGE\_SIZE |
호스트 KV 캐시 할당 (HiCache / disaggregation offload)에 huge page 사용. 유효 값: 2MB (MAP\_HUGE\_2MB로 2 MiB 페이지) 또는 1GB (MAP\_HUGE\_1GB로 1 GiB 페이지). 호스트 OS에 huge page 사전 할당 필요 (/proc/sys/vm/nr\_hugepages 또는 /sys/kernel/mm/hugepages). 할당 실패 시 할당자는 경고를 기록하고 자동으로 일반 페이지 크기 mmap으로 폴백 |
Not set (OS 기본 페이지 크기 사용) |
SGLANG\_HICACHE\_HF3FS\_CONFIG\_PATH |
HiCache HF3FS 백엔드 구성 파일 경로 | Not set |
SGLANG\_HICACHE\_FILE\_BACKEND\_STORAGE\_DIR |
HiCache 파일 백엔드 저장소 디렉터리 | Not set |
SGLANG\_HICACHE\_FILE\_BACKEND\_MAX\_SIZE |
HiCache 파일 백엔드 LRU 축출 최대 크기 (SI/IEC 접미사 수용, 0은 축출 비활성) |
Not set (축출 꺼짐) |
SGLANG\_HICACHE\_FILE\_BACKEND\_EVICTION\_RATIO |
파일 백엔드 최대 크기에 도달했을 때 축출해 내려갈 대상 비율 | 0.9 |
SGLANG\_HICACHE\_FILE\_BACKEND\_MIN\_FREE\_SPACE |
파일 백엔드 볼륨에 유지할 최소 여유 공간 (SI/IEC 접미사 수용) | 0 |
SGLANG\_HICACHE\_NIXL\_BACKEND\_STORAGE\_DIR |
HiCache NIXL 백엔드 저장소 디렉터리 | Not set |
함수 호출 / 도구 사용 (Function Calling / Tool Use)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_TOOL\_STRICT\_LEVEL |
도구 호출 파싱 및 검증의 엄격도 수준 제어. Level 0: 꺼짐 - 엄격 검증 없음 Level 1: 함수 엄격 - 모든 도구에 구조적 태그 제약 활성화 (어느 것도 strict=True가 아니어도) Level 2: 파라미터 엄격 - 모든 도구에 엄격 파라미터 검증 강제, 모두 strict=True 설정인 것처럼 취급 |
0 |
SGLANG\_DEFAULT\_THINKING |
기본으로 모델 사고/추론 출력 활성화 | false |
SGLANG\_MAX\_THINK\_TOKENS |
사고 토큰 캡. 음수는 무제한, 0 이상은 수 캡 |
-1 |
로깅 및 관측성 (Logging & Observability)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_LOG\_GC |
Python 가비지 컬렉션 일시정지 로그 | false |
SGLANG\_LOG\_FORWARD\_ITERS |
각 forward 반복 로그 | false |
SGLANG\_LOG\_MS |
밀리초 단위 스텝별 타이밍 로그 | false |
SGLANG\_LOG\_REQUEST\_EXCEEDED\_MS |
처리 시간이 이 밀리초를 초과하는 요청 로그. -1은 비활성 |
-1 |
SGLANG\_LOG\_SCHEDULER\_STATUS\_TARGET |
주기적 스케줄러 상태 로깅 대상 (예: 파일 경로) | "" |
SGLANG\_LOG\_SCHEDULER\_STATUS\_INTERVAL |
스케줄러 상태 로그 라인 간 간격 (초) | 60.0 |
제약 디코딩 (문법) (Constrained Decoding)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_GRAMMAR\_POLL\_INTERVAL |
비동기 문법 컴파일 폴 간격 (초) | 0.005 |
SGLANG\_GRAMMAR\_MAX\_POLL\_ITERATIONS |
문법 컴파일이 멈춘 것으로 처리되기 전 최대 폴 반복 | 10000 |
스케줄러 및 배칭 (Scheduler & Batching)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_INIT\_NEW\_TOKEN\_RATIO |
메모리 계획용 초기 새 토큰 비율 | 0.7 |
SGLANG\_MIN\_NEW\_TOKEN\_RATIO\_FACTOR |
감쇠 후 새 토큰 비율의 바닥 인자 | 0.14 |
SGLANG\_NEW\_TOKEN\_RATIO\_DECAY\_STEPS |
새 토큰 비율이 감쇠되는 스텝 수 | 600 |
SGLANG\_RETRACT\_DECODE\_STEPS |
retract 결정 시 앞을 보는 디코드 스텝 수 | 20 |
SGLANG\_EMPTY\_CACHE\_INTERVAL |
디바이스 캐시를 비우는 간격 (초). 긴 서빙 기간 동안 메모리가 축적되면 설정. -1은 비활성 |
-1 |
SGLANG\_FORCE\_STREAM\_INTERVAL |
비스트리밍 요청의 경우 N 디코드 토큰마다 중간 출력 배치를 토크나이저 관리자로 플러시 (정확한 TTFT 벤치마킹을 위해 1로 낮춤) |
50 |
SGLANG\_DYNAMIC\_CHUNKING\_SMOOTH\_FACTOR |
동적 prefill 청킹용 평활화 인자 | 0.75 |
SGLANG\_SWA\_EVICTION\_INTERVAL\_MULTIPLIER |
sliding-window-attention 축출 간격에 적용되는 배수 | 1.0 |
SGLANG\_RADIX\_FORCE\_MISS |
radix 캐시 미스 강제 (디버깅/벤치마킹) | false |
SGLANG\_SCHEDULER\_SKIP\_ALL\_GATHER |
스케줄러 all-gather 단계 건너뜀 | false |
SGLANG\_ENABLE\_WAR\_BARRIER |
CUDA가 감지되지 않아도 (예: AMD/ROCm) 오버랩 스케줄러에 write-after-read 배리어 강제 활성화. CUDA에서는 항상 활성화 | false |
SGLANG\_PP\_SKIP\_PURE\_CHUNKED\_OUTPUT\_COMM |
파이프라인 병렬에서 배치가 전부 비최종 chunked-prefill 요청이면 출력 send/recv 건너뜀 | false |
SGLANG\_KILLPG\_ON\_SCHEDULER\_EXCEPTION |
스케줄러가 예외를 발생시키면 전체 프로세스 그룹 종료 | false |
SGLANG\_REQUEST\_STATE\_WAIT\_TIMEOUT |
토크나이저 관리자 요청 상태 대기 타임아웃 (초) | 4 |
PD Disaggregation (런타임) (PD Disaggregation)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_DISAGGREGATION\_THREAD\_POOL\_SIZE |
KV 전송용 스레드 풀 크기. 런타임에 CPU 수에서 계산된 값으로 기본 설정 | Not set (런타임에 계산) |
SGLANG\_DISAGGREGATION\_QUEUE\_SIZE |
disaggregation 전송 큐 크기 | 4 |
SGLANG\_DISAGGREGATION\_BOOTSTRAP\_TIMEOUT |
disaggregation bootstrap 핸드셰이크 타임아웃 (초) | 300 |
SGLANG\_DISAGGREGATION\_WAITING\_TIMEOUT |
KV 전송을 기다리는 요청 타임아웃 (초) | 300 |
SGLANG\_DISAGGREGATION\_HEARTBEAT\_INTERVAL |
disaggregation 하트비트 간격 (초) | 5.0 |
SGLANG\_DISAGGREGATION\_HEARTBEAT\_MAX\_FAILURE |
피어가 죽은 것으로 간주되기 전 허용되는 연속 하트비트 실패 | 2 |
SGLANG\_DISAGGREGATION\_ZMQ\_SEND\_TIMEOUT |
prefill 피어에 대한 decode의 ZMQ 소켓 전송 타임아웃 (초). 정상 전송이 기본값을 초과하면 올림 | 1 |
SGLANG\_DISAGGREGATION\_BOOTSTRAP\_ENTRY\_CLEANUP\_INTERVAL |
오래된 bootstrap 항목 정리 간격 (초) | 120 |
SGLANG\_DISAGGREGATION\_NIXL\_BACKEND |
disaggregation용 NIXL 전송 백엔드 | UCX |
SGLANG\_DISAGGREGATION\_NIXL\_BACKEND\_PARAMS |
NIXL 백엔드에 전달되는 JSON 파라미터 | {'{}'} |
SGLANG\_DISAGGREGATION\_ALL\_CP\_RANKS\_TRANSFER |
모든 context-parallel rank가 KV 전송에 참여 | false |
SGLANG\_DISAGGREGATION\_FORCE\_QUERY\_PREFILL\_DP\_RANK |
라우팅을 위해 prefill DP rank 쿼리 강제 | false |
SGLANG\_DISAGGREGATION\_NUM\_PRE\_ALLOCATE\_REQS |
decode 워커용 req\_to\_token\_pool의 추가 슬롯 (max\_num\_reqs가 32보다 클 때 유효), 더 많은 KV 전송이 decode와 오버랩되게 함 |
0 |
Mooncake KV 저장소 및 전송 (Mooncake KV Store & Transfer)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_HICACHE\_MOONCAKE\_CONFIG\_PATH |
HiCache Mooncake 저장소 구성 파일 경로 | Not set |
SGLANG\_HICACHE\_MOONCAKE\_REUSE\_TE |
HiCache 연산 간 Mooncake 전송 엔진 재사용 | true |
SGLANG\_MOONCAKE\_SEND\_AUX\_TCP |
Mooncake AUX 데이터를 TCP로 전송 | false |
SGLANG\_ENABLE\_FAILED\_SESSION\_PROBE |
복구를 위해 실패한 Mooncake 세션 프로브 | false |
SGLANG\_FAILED\_SESSION\_PROBE\_INTERVAL\_S |
실패 세션 프로브 간 간격 (초) | 30.0 |
MOONCAKE\_MASTER |
Mooncake 마스터 주소 | Not set |
MOONCAKE\_CLIENT |
Mooncake 클라이언트 식별자 | Not set |
MOONCAKE\_LOCAL\_HOSTNAME |
Mooncake에 알리는 로컬 호스트 이름 | localhost |
MOONCAKE\_TE\_META\_DATA\_SERVER |
Mooncake 전송 엔진 메타데이터 서버 | P2PHANDSHAKE |
MOONCAKE\_GLOBAL\_SEGMENT\_SIZE |
Mooncake 전역 세그먼트 크기 | 4gb |
MOONCAKE\_PROTOCOL |
Mooncake 전송 프로토콜 | rdma |
MOONCAKE\_DEVICE |
Mooncake RDMA 디바이스 | "" |
MOONCAKE\_MASTER\_METRICS\_PORT |
Mooncake 마스터 메트릭 포트 | 9003 |
MOONCAKE\_CHECK\_SERVER |
시작 시 Mooncake 서버 연결 확인 | false |
MOONCAKE\_STANDALONE\_STORAGE |
Mooncake를 독립 저장소 모드로 실행 | false |
MOONCAKE\_ENABLE\_SSD\_OFFLOAD |
Mooncake에서 SSD offload 활성화 | false |
MOONCAKE\_OFFLOAD\_FILE\_STORAGE\_PATH |
Mooncake SSD offload 파일 저장소 경로 | Not set |
ENABLE\_ASCEND\_TRANSFER\_WITH\_MOONCAKE |
Mooncake를 통한 Ascend NPU 전송 활성화 | false |
ASCEND\_NPU\_PHY\_ID |
Mooncake 전송에 사용되는 물리 Ascend NPU id. -1은 자동 감지 |
-1 |
어텐션 및 커널 (Attention & Kernels)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_TRITON\_DECODE\_ATTN\_STATIC\_KV\_SPLITS |
Triton decode-어텐션 커널에 정적 KV 분할 사용 | false |
SGLANG\_MUSA\_FA3\_FORCE\_UPDATE\_METADATA |
MThreads MUSA에서 FA3 메타데이터 업데이트 강제 | false |
SGLANG\_SKIP\_SGL\_KERNEL\_VERSION\_CHECK |
sgl-kernel 버전 호환성 검사 건너뜀 | false |
결정적 추론 (Deterministic Inference)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_ENABLE\_DETERMINISTIC\_INFERENCE |
결정적 추론 활성화 (고정 reduction/accumulation 순서) | false |
SGLANG\_USE\_1STAGE\_ALLREDUCE |
AMD에서 1-스테이지 all-reduce 커널 사용 (결정적, 고정 누적 순서). 미설정 시 결정적 추론이 켜지면 자동 활성화 | false |
SGLANG\_FLASHINFER\_PREFILL\_SPLIT\_TILE\_SIZE |
결정적 어텐션용 FlashInfer prefill split-tile 크기 | 4096 |
SGLANG\_FLASHINFER\_DECODE\_SPLIT\_TILE\_SIZE |
결정적 어텐션용 FlashInfer decode split-tile 크기 | 2048 |
SGLANG\_TRITON\_PREFILL\_TRUNCATION\_ALIGN\_SIZE |
결정적 어텐션용 Triton prefill 절단 정렬 크기 | 4096 |
SGLANG\_TRITON\_DECODE\_SPLIT\_TILE\_SIZE |
결정적 어텐션용 Triton decode split-tile 크기 | 256 |
추측 디코딩 및 오버랩 (Speculative Decoding & Overlap)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_ENABLE\_OVERLAP\_PLAN\_STREAM |
현재 스텝과 오버랩하도록 별도 스트림에서 다음 스텝 계획 (Overlap Spec V2) | false |
SGLANG\_SPEC\_SKIP\_ZERO\_STEP\_DRAFT\_EXTEND |
adaptive spec이 steps=0일 때 draft_extend 건너뜀. draft forward는 절약하지만 draft KV는 오래됨 | false |
SGLANG\_NGRAM\_FORCE\_GREEDY\_VERIFY |
n-gram 추측 경로에 greedy 검증 강제 | false |
SGLANG\_SANITIZE\_NAN\_LOGITS |
샘플링 커널 전 NaN logits 정리 및 제한된 경고 발생 | true |
EPLB (전문가 병렬 부하 분산) (Expert Parallel Load Balancing)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_EXPERT\_DISTRIBUTION\_RECORDER\_DIR |
전문가 분포 기록자 출력 디렉터리 | /tmp |
SGLANG\_LOG\_EXPERT\_LOCATION\_METADATA |
전문가 위치 메타데이터 로그 | false |
SGLANG\_EXPERT\_LOCATION\_UPDATER\_LOG\_INPUT |
전문가 위치 업데이터 입력 로그 | false |
SGLANG\_EXPERT\_LOCATION\_UPDATER\_LOG\_METRICS |
전문가 위치 업데이터 메트릭 로그 | false |
AMD 및 ROCm
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_USE\_AITER\_AG |
AITER all-gather 구현 사용 | true |
SGLANG\_USE\_AITER\_UNIFIED\_ATTN |
AITER 통합 어텐션 커널 사용 | false |
SGLANG\_USE\_AITER\_FP8\_PER\_TOKEN |
AITER FP8 토큰당 양자화 사용 | false |
SGLANG\_AITER\_HONOR\_EXPLICIT\_MEM\_FRACTION |
컨텍스트 길이 8192 초과 AITER에서 명시적으로 전달된 --mem-fraction-static을 그대로 사용, 비정적 어텐션 워크스페이스 예약을 위해 0.85로 스케일링하는 대신. 예약을 건너뛰면 장기 컨텍스트 서빙이 OOM할 수 있음. 스케일된 비율이 모델 가중치를 담기에 너무 작을 때만 설정 |
false |
SGLANG\_USE\_AITER\_MOE\_GU\_ITLV |
AITER MoE gate/up 타일 레이아웃 선택: true는 인터리브, false는 분리 레이아웃 |
true |
SGLANG\_AITER\_FUSE\_RMSNORM\_PAD |
MoE 블록 전에 residual-add + RMSNorm + zero-pad 트리플렛을 AITER Triton 커널로 융합 (TP=1, post-attention layernorm 경로 전용) | false |
SGLANG\_AITER\_KV\_CACHE\_LAYOUT |
AITER MHA KV 캐시 물리 레이아웃: nhd 또는 vectorized\_5d (pa_decode_gluon 가능SHUFFLE 레이아웃) |
nhd |
SGLANG\_ROCM\_FUSED\_DECODE\_MLA |
ROCm에서 융합 decode MLA 커널 사용 | false |
SGLANG\_ROCM\_DISABLE\_LINEARQUANT |
ROCm에서 linear 레이어 양자화 비활성화 | false |
SGLANG\_ROCM\_K3\_FUSE\_KDA\_INPROJ |
ROCm의 Kimi-K3: KDA `[f_a | b]꼬리를 넓은[q,k,v,g]` projection에 접어 전체 입력 projection을 하나의 GEMM으로. 비양자화 가중치에만 적용, 그 외 분리 projection으로 폴백 |
SGLANG\_ROCM\_K3\_FUSE\_KDA\_INPROJ\_MAX\_TOKENS |
SGLANG\_ROCM\_K3\_FUSE\_KDA\_INPROJ 적용을 중단하고 분리 projection이 실행되는 토큰 수. 병합 형태는 projection이 대역폭 바운드일 때만 더 빠름 |
256 |
NPU (Ascend)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_NPU\_DISABLE\_ACL\_FORMAT\_WEIGHT |
NPU에서 ACL 형식 가중치 변환 비활성화 | false |
SGLANG\_NPU\_USE\_MULTI\_STREAM |
NPU에서 다중 스트림 사용 | false |
SGLANG\_NPU\_USE\_MLAPO |
NPU에서 MLAPO 경로 사용 | false |
SGLANG\_NPU\_FORWARD\_NATIVE\_GELUTANH |
네이티브 gelu-tanh 활성화 forward 사용 (Skywork-Reward-Gemma-2-27B-v0.2용) | false |
SGLANG\_NPU\_FORWARD\_NATIVE\_GEMMA\_RMS\_NORM |
네이티브 Gemma RMSNorm forward 사용 (Skywork-Reward-Gemma-2-27B-v0.2용) | false |
SGLANG\_USE\_AG\_AFTER\_QLORA |
더 나은 DeepSeek V3.2 성능을 위해 QLoRA 후까지 all-gather 지연 | false |
SGLANG\_EXPERIMENTAL\_LORA\_OPTI |
실험적 TRT-LLM LoRA 고속 경로의 마스터 스위치. 꺼지면 모든 세밀한 opt 스위치가 false로 읽힘 | false |
SGLANG\_ZBAL\_LOCAL\_MEM\_SIZE |
ZBAL (zero-buffer accelerate library) 경로 로컬 메모리 크기 (NPU 전용) | 0 |
SGLANG\_ZBAL\_BOOTSTRAP\_URL |
ZBAL 경로 부트스트랩 URL (NPU 전용) | "" |
Apple Silicon (MLX / MPS)
이 변수들은 SRT MLX 백엔드를 구성해요. SGLang Diffusion은 PyTorch MPS를 사용하고 이들을 읽지 않아요.
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_USE\_MLX |
Apple Silicon에서 MLX 백엔드 사용 | false |
SGLANG\_MLX\_USE\_CUSTOM\_ROPE |
MLX에서 커스텀 RoPE 커널 사용 | false |
SGLANG\_MLX\_FUSE\_SWIGLU |
MLX에서 SwiGLU 활성화 융합 | false |
SGLANG\_MLX\_CLEAR\_CACHE\_STEPS |
mx.clear\_cache() 호출 간 디코드 스텝 수. 0은 캐시 정리 비활성 |
256 |
멀티모달 (VLM)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_VLM\_CACHE\_SIZE\_MB |
VLM 피처 캐시 크기 (MB) | 100 |
SGLANG\_IMAGE\_MAX\_PIXELS |
리사이즈 전 이미지당 최대 픽셀 수 | 12845056 |
SGLANG\_RESIZE\_RESAMPLE |
이미지 리사이즈 시 사용되는 리샘플링 필터 (예: bilinear, bicubic) |
"" |
SGLANG\_MM\_SKIP\_COMPUTE\_HASH |
멀티모달 항목 해시 계산 건너뜀 | false |
SGLANG\_MM\_AVOID\_RETOKENIZE |
사전 토크나이즈된 (list[int]) 멀티모달 프롬프트의 경우 재토크나이즈 드리프트를 피하기 위해 사용자 원본 토큰 보존 | true |
SGLANG\_VIT\_ENABLE\_CUDA\_GRAPH |
비전 인코더 (ViT)를 CUDA graph로 캡처 | false |
SGLANG\_USE\_CUDA\_IPC\_TRANSPORT |
멀티모달 항목 텐서에 CUDA IPC 전송 사용 | false |
SGLANG\_USE\_IPC\_POOL\_HANDLE\_CACHE |
CUDA IPC 멀티모달 피처 전송이 선택되면 기존 바운드 풀에 대한 매핑 재사용. CUDA IPC 전송을 활성화하거나 다른 풀을 예약하지 않음 | true |
SGLANG\_MM\_FEATURE\_CACHE\_MB |
멀티모달 피처 캐시 크기 (MB) | 1024 |
SGLANG\_MM\_ITEM\_MEM\_POOL\_RECYCLE\_INTERVAL\_SEC |
멀티모달 항목 메모리 풀 재활용 간격 (초) | 0.05 |
인코더 / EPD (멀티모달 disaggregation)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_ENCODER\_MM\_RECEIVER\_MODE |
EPD 경로가 사용하는 인코더 수신기 선택: http 또는 grpc |
http |
SGLANG\_ENCODER\_GRPC\_TIMEOUT\_SECS |
인코더 통신 gRPC 타임아웃 (초) | 60 |
SGLANG\_ENCODER\_RECV\_TIMEOUT |
인코더 수신 타임아웃 (초) | 180.0 |
SGLANG\_ENCODER\_SEND\_TIMEOUT |
인코더 전송 타임아웃 (초) | 180.0 |
SGLANG\_ENCODER\_HTTP\_TIMEOUT |
인코더 HTTP 타임아웃 (초) | 1800.0 |
SGLANG\_ENCODER\_REQ\_TIMEOUT |
인코더 요청당 타임아웃 (초) | 180.0 |
SGLANG\_ENCODER\_DISPATCH\_MIN\_ITEMS |
인코더가 배치를 디스패치하기 전 최소 항목 | 2 |
SGLANG\_ENCODER\_MAX\_BATCH\_SIZE |
최대 인코더 배치 크기 | 8 |
SGLANG\_ENCODER\_PREPROC\_WORKERS |
인코더 전처리 워커 수 | 8 |
SGLANG\_ENCODER\_IMAGE\_PROCESSOR\_USE\_GPU |
이미지 프로세서를 GPU에서 실행 | false |
SGLANG\_ENCODER\_BOOTSTRAP\_HEALTH\_CHECK\_INTERVAL |
EncoderBootstrapServer 헬스 체크 간격 (초). 0은 비활성 |
10.0 |
SGLANG\_ENCODER\_BOOTSTRAP\_HEALTH\_CHECK\_TIMEOUT |
EncoderBootstrapServer 헬스 체크 타임아웃 (초) | 2.0 |
SGLANG\_EMBEDDING\_POOL\_SIZE\_MB |
Mooncake EPD 전송용 영구 수신 측 GPU 임베딩 풀 크기 (MB). 0은 비활성 (요청당 등록/등록 해제) |
4096 |
SGLANG\_ENCODER\_DP\_WORKER\_MAX\_INFLIGHT |
인코더 DP 워커당 최대 진행 중 요청 | 64 |
SGLANG\_BACKUP\_PORT\_BASE |
elastic-EP 백업 포트 기본 포트 | 10000 |
HTTP 및 gRPC 서버
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_TIMEOUT\_KEEP\_ALIVE |
HTTP keep-alive 타임아웃 (초) | 5 |
SGLANG\_UVICORN\_WORKER\_HEALTHCHECK\_TIMEOUT |
Uvicorn 다중 프로세스 감독자의 워커당 헬스 체크 간격 (초) | 10 |
SGLANG\_ENABLE\_HEALTH\_ENDPOINT\_GENERATION |
/health 엔드포인트가 검사의 일부로 생성을 실행 |
true |
SGLANG\_WARMUP\_TIMEOUT |
워밍업 forward 배치가 이보다 오래 걸리면 서버가 hang을 방지하기 위해 크래시. -1은 비활성. 커널 JIT 사전 컴파일을 수용하려면 증가 (예: 1800) |
-1 |
SGLANG\_GRPC\_PORT |
네이티브 gRPC 서버 포트 | Not set |
SGLANG\_GRANIAN\_PARENT\_PID |
Granian HTTP/2 워커 감독자 부모 PID | Not set |
NUMA 및 CPU
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_NUMA\_BIND\_V2 |
NUMA 바인딩 구현 선택. true는 사전 실행 numactl 래퍼 사용, false는 워커 프로세스에서 바인딩. 이 변수는 NUMA 바인딩을 활성화/비활성화하지 않음 |
true |
SGLANG\_AUTO\_NUMA\_BIND |
--numa-node가 지정되지 않으면 각 NVIDIA GPU의 로컬 NUMA 노드를 자동 감지하고 그 워커를 바인딩. 워커를 바인딩하지 않으려면 false 설정. 명시적 --numa-node가 우선 |
true |
SGLANG\_CRASH\_ON\_NUMA\_BIND\_FAILURE |
경고 대신 NUMA 바인딩 실패 시 크래시 | false |
메트릭 (Metrics)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_ENABLE\_METRICS\_DEVICE\_TIMER |
디바이스 타이머 기반 메트릭 활성화 | false |
SGLANG\_ENABLE\_METRICS\_DP\_ATTENTION |
데이터 병렬 어텐션 메트릭 활성화 | false |
외부 모델 (External Models)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_EXTERNAL\_MODEL\_PACKAGE |
외부 모델 구현을 제공하는 Python 패키지 | "" |
SGLANG\_EXTERNAL\_MM\_MODEL\_ARCH |
외부 멀티모달 모델 아키텍처 이름 | "" |
SGLANG\_EXTERNAL\_MM\_PROCESSOR\_PACKAGE |
외부 멀티모달 프로세서를 제공하는 Python 패키지 | "" |
플러그인 시스템 (Plugin System)
| 환경 변수 | 설명 | 기본값 |
|---|---|---|
SGLANG\_PLATFORM |
로드할 플랫폼 플러그인 이름 | "" |
SGLANG\_PLUGINS |
로드할 플러그인의 쉼표 구분 목록 | "" |