환경 변수
환경 변수 (Environment Variables)
이 페이지는 SGLang Diffusion의 동작을 환경 변수로 구성하는 방법을 설명해요. 런타임, 플랫폼별, 양자화, 캐싱 가속화, 클라우드 저장소, CUDA 크래시 디버깅 관련 변수들을 정리해요.
출처: 문서
본문
런타임 (Runtime)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_EXTERNAL\_MODEL\_PACKAGE |
not set | 트리 외부 확산 파이프라인과 컴포넌트 모델을 등록하는 설치된 패키지. 패키지는 모든 프로세스에서 한 번 가져옴 |
SGLANG\_DIFFUSION\_PLATFORM\_OVERRIDE |
not set | cpu, cuda, rocm, mps, npu, musa 또는 설치된 sglang.multimodal\_gen.platforms 진입점 이름 선택. XPU는 자동 전용으로 유지. 미설정 시 SGLang Diffusion은 내장 플랫폼을 시도하기 전에 설치된 플랫폼 플러그인을 감지 |
SGLANG\_PLUGINS |
not set | 설치된 sglang.multimodal\_gen.plugins 훅의 쉼표 구분 허용 목록. 미설정 시 발견된 모든 확산 훅이 로드 |
SGLANG\_DIFFUSION\_TARGET\_DEVICE |
cuda |
추론 대상 디바이스 (cuda, rocm, xpu, npu, musa, mps, cpu) |
SGLANG\_DIFFUSION\_ATTENTION\_BACKEND |
not set | env 변수로 어텐션 백엔드 오버라이드 (예: fa, torch\_sdpa, sage\_attn) |
SGLANG\_DIFFUSION\_ATTENTION\_CONFIG |
not set | 어텐션 백엔드 구성 파일 경로 (JSON/YAML) |
SGLANG\_DIFFUSION\_STAGE\_LOGGING |
false | 단계별 타이밍 로그 활성화 |
SGLANG\_DIFFUSION\_SERVER\_DEV\_MODE |
false | 디버깅용 개발 전용 HTTP 엔드포인트 활성화 |
SGLANG\_DIFFUSION\_TORCH\_PROFILER\_DIR |
not set | torch profiler 트레이스 디렉터리 (절대 경로). 설정 시 프로파일링 활성화 |
SGLANG\_DIFFUSION\_CACHE\_ROOT |
\~/.cache/sgl\_diffusion |
캐시 파일 루트 디렉터리 |
SGLANG\_DIFFUSION\_CONFIG\_ROOT |
\~/.config/sgl\_diffusion |
구성 파일 루트 디렉터리 |
SGLANG\_DIFFUSION\_LOGGING\_LEVEL |
INFO |
기본 로깅 수준 |
SGLANG\_DIFFUSION\_IPC\_A2A |
true |
적격한 동일 호스트, peer 접근 가능 TP1 + 2-rank Ulysses 그룹에 CUDA-IPC all-to-all 활성화. 지원되지 않는 토폴로지는 NCCL로 폴백. NCCL을 강제하려면 0 설정 |
SGLANG\_DIFFUSION\_IPC\_A2A\_TIMEOUT\_MS |
10000 |
peer 대기 타임아웃(밀리초). 이는 hang 방지책이지 스텝별 예산이 아님. layerwise offload 같은 알려진 긴 정지에만 올림 |
SGLANG\_DIFFUSION\_IPC\_A2A\_MAX\_BUFFERS |
16 |
최대 캐시된 IPC 스테이징 버퍼 형태 쌍. 다중 해상도 서빙에서 영구 스테이징 메모리를 제한하기 위해 캡 |
SGLANG\_USE\_RUNAI\_MODEL\_STREAMER |
true | 모델 로딩에 Run:AI model streamer 사용 |
SGLANG\_KITCHEN\_INT8\_MAX\_ROWS |
8192 |
kitchen\_int8 융합 GEMM당 최대 활성화 행. 행 분할 비활성화하려면 0 설정 |
SGLANG\_KITCHEN\_INT8\_MIN\_SPLIT\_N |
8192 |
kitchen\_int8이 큰-M GEMM을 분할하기 전 최소 출력 피처. 좁은 출력은 단일 호출로 유지 |
플랫폼별 (Platform-Specific)
Apple MPS
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_USE\_MLX |
not set | SRT 전용: MLX 서빙 백엔드 활성화. PyTorch MPS를 사용하는 SGLang Diffusion에는 영향 없음 |
ROCm (AMD GPU)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_USE\_ROCM\_VAE |
false | ROCm 성능 향상을 위해 VAE에 AITer GroupNorm 사용 |
SGLANG\_USE\_ROCM\_CUDNN\_BENCHMARK |
false | ROCm의 VAE conv 레이어에 MIOpen 자동 튜닝 활성화 |
양자화 (Quantization)
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_DIFFUSION\_FLASHINFER\_FP4\_GEMM\_BACKEND |
not set | 확산 NVFP4용 선택적 FlashInfer FP4 GEMM 백엔드 오버라이드. 미설정 시 SGLang은 flashinfer\_trtllm 기본 설정 |
SGLANG\_DIFFUSION\_ENABLE\_W8A8\_FP8\_GEMM |
false | 확산 weight-only FP8 linear에서 융합 W8A8 FP8 GEMM의 실험적 옵트인. 비활성 시 FP8 가중치는 matmul 전 계산 dtype으로 역양자화. 활성화 시 활성화를 FP8로 동적 양자화하며 출력 품질이 바뀔 수 있음 |
SGLANG\_DIFFUSION\_ENABLE\_MXFP8\_ATTENTION |
false | 지원되는 비-인과 self-attention 레이어에 Ascend MXFP8 FA 활성화. 온라인 MXFP8Config와 오프라인 ModelSlim W8A8\_MXFP8 체크포인트에 적용. 지원되지 않는 호출은 일반 어텐션 경로를 계속 사용 |
SGLANG\_DIFFUSION\_MXFP8\_FA\_HEAD\_CHUNK\_SIZE |
4 | 각 Ascend MXFP8 FA 호출이 처리하는 최대 어텐션 헤드 수. 작은 청크는 큰 워크로드 성능을 높일 수 있지만 커널 실행을 추가. 최적 값은 모델과 입력 형태에 따라 다름. 헤드 분할 비활성화하려면 0 설정 |
캐싱 가속화 (Caching Acceleration)
이 변수들은 Diffusion Transformer (DiT) 모델의 캐싱 가속화를 구성해요. SGLang은 여러 캐싱 전략을 지원하며 개요는 caching documentation을 참고해요.
Cache-DiT 구성 (Cache-DiT Configuration)
자세한 구성은 cache-dit documentation 참고.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG_CACHE_DIT_ENABLED |
false | Cache-DiT 가속화 활성화 |
SGLANG_CACHE_DIT_FN |
1 | 항상 계산할 처음 N개 블록 |
SGLANG_CACHE_DIT_BN |
0 | 항상 계산할 마지막 N개 블록 |
SGLANG_CACHE_DIT_WARMUP |
4 | 캐싱 전 워밍업 스텝 |
SGLANG_CACHE_DIT_RDT |
0.24 | 잔차 차이 임계값 |
SGLANG_CACHE_DIT_MC |
3 | 최대 연속 캐시 스텝 |
SGLANG_CACHE_DIT_TAYLORSEER |
false | TaylorSeer 캘리브레이터 활성화 |
SGLANG_CACHE_DIT_TS_ORDER |
1 | TaylorSeer 순서 (1 또는 2) |
SGLANG_CACHE_DIT_DMD |
false | DMD (Dynamic Mode Decomposition) 캘리브레이터 활성화 (TaylorSeer와 상호 배타) |
SGLANG_CACHE_DIT_DMD_HISTORY |
6 | DMD 스냅샷 창 길이 (5-6 일반적. 균등 간격 스냅샷 >= 4 필요, 그렇지 않으면 DMD는 TaylorSeer로 폴백) |
SGLANG_CACHE_DIT_DMD_RANK |
0 | DMD SVD 절단 순위 (0 = 자동) |
SGLANG_CACHE_DIT_DMD_RIDGE |
1e-8 | 역 특이값에 추가되는 DMD Tikhonov 정규화 |
SGLANG_CACHE_DIT_DMD_SVD_PRECISION |
medium | DMD SVD 정밀도 (low/medium/high) |
SGLANG_CACHE_DIT_SCM_PRESET |
none | SCM 프리셋 (none/slow/medium/fast/ultra) |
SGLANG_CACHE_DIT_SCM_POLICY |
dynamic | SCM 캐싱 정책 |
SGLANG_CACHE_DIT_SCM_COMPUTE_BINS |
not set | 커스텀 SCM compute bins |
SGLANG_CACHE_DIT_SCM_CACHE_BINS |
not set | 커스텀 SCM cache bins |
Cache-DiT 보조 트랜스포머 (Cache-DiT Secondary Transformer)
이중 트랜스포머 모델(예: 고/저 노이즈 전문가가 있는 Wan2.2)의 경우 이 변수들이 보조 트랜스포머의 캐싱을 구성해요. 각각 미설정 시 기본 대응 변수로 폴백해요.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_CACHE\_DIT\_SECONDARY\_FN |
(from primary) | 항상 계산할 처음 N개 블록 |
SGLANG\_CACHE\_DIT\_SECONDARY\_BN |
(from primary) | 항상 계산할 마지막 N개 블록 |
SGLANG\_CACHE\_DIT\_SECONDARY\_WARMUP |
(from primary) | 캐싱 전 워밍업 스텝 |
SGLANG\_CACHE\_DIT\_SECONDARY\_RDT |
(from primary) | 잔차 차이 임계값 |
SGLANG\_CACHE\_DIT\_SECONDARY\_MC |
(from primary) | 최대 연속 캐시 스텝 |
SGLANG\_CACHE\_DIT\_SECONDARY\_TAYLORSEER |
(from primary) | TaylorSeer 캘리브레이터 활성화 |
SGLANG\_CACHE\_DIT\_SECONDARY\_TS\_ORDER |
(from primary) | TaylorSeer 순서 (1 또는 2) |
SGLANG\_CACHE\_DIT\_SECONDARY\_DMD |
(from primary) | DMD 캘리브레이터 활성화 (TaylorSeer와 상호 배타) |
SGLANG\_CACHE\_DIT\_SECONDARY\_DMD\_HISTORY |
(from primary) | DMD 스냅샷 창 길이 |
SGLANG\_CACHE\_DIT\_SECONDARY\_DMD\_RANK |
(from primary) | DMD SVD 절단 순위 (0 = 자동) |
SGLANG\_CACHE\_DIT\_SECONDARY\_DMD\_RIDGE |
(from primary) | DMD Tikhonov 정규화 항 |
SGLANG\_CACHE\_DIT\_SECONDARY\_DMD\_SVD\_PRECISION |
(from primary) | DMD SVD 정밀도 (low/medium/high) |
클라우드 저장소 (Cloud Storage)
이 변수들은 생성된 이미지와 비디오를 자동 업로드하기 위한 S3 호환 클라우드 저장소를 구성해요.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG_CLOUD_STORAGE_TYPE |
not set | 클라우드 저장소 활성화를 위해 s3로 설정 |
SGLANG_S3_BUCKET_NAME |
not set | S3 버킷 이름 |
SGLANG_S3_ENDPOINT_URL |
not set | 커스텀 엔드포인트 URL (MinIO, OSS 등용) |
SGLANG_S3_REGION_NAME |
us-east-1 | AWS 지역 이름 |
SGLANG_S3_ACCESS_KEY_ID |
not set | AWS Access Key ID |
SGLANG_S3_SECRET_ACCESS_KEY |
not set | AWS Secret Access Key |
CUDA 크래시 디버깅 (CUDA Crash Debugging)
이 변수들은 확산 CUDA 커널 호출 경계 주변의 커널 API 로깅과 선택적 입력/출력 덤프를 활성화해요. illegal memory access, device-side assert, 커스텀 커널의 형태 불일치 같은 CUDA 크래시를 추적할 때 유용해요.
| 환경 변수 | 기본값 | 설명 |
|---|---|---|
SGLANG\_KERNEL\_API\_LOGLEVEL |
0 |
크래시 디버그 커널 API 로깅 제어. 1은 API 이름, 3은 텐서 메타데이터, 5는 텐서 통계 추가, 10은 덤프 스냅샷도 작성 |
SGLANG\_KERNEL\_API\_LOGDEST |
stdout |
크래시 디버그 커널 API 로그 대상. stdout, stderr 또는 파일 경로 사용. %i는 프로세스 PID로 대체 |
SGLANG\_KERNEL\_API\_DUMP\_DIR |
sglang\_kernel\_api\_dumps |
레벨-10 커널 API 덤프 출력 디렉터리. %i는 프로세스 PID로 대체 |
SGLANG\_KERNEL\_API\_DUMP\_INCLUDE |
not set | 레벨-10 덤프에 포함할 커널 API 이름의 쉼표 구분 와일드카드 패턴 |
SGLANG\_KERNEL\_API\_DUMP\_EXCLUDE |
not set | 레벨-10 덤프에서 제외할 커널 API 이름의 쉼표 구분 와일드카드 패턴 |