CLI 참조

CLI 참조 (CLI Reference)

이 페이지는 SGLang Diffusion의 커맨드라인 인터페이스를 설명해요. sglang generate로 일회성 생성 작업을 실행하고 sglang serve로 영구 HTTP 서버를 시작할 수 있어요.

출처: 문서

본문

CLI는 일회성 생성을 위한 sglang generate 또는 영구 HTTP 서버 시작을 위한 sglang serve로 사용해요.

비-diffusers 모델용 오버레이 저장소 (Overlay repos for non-diffusers models)

--model-path가 지원되는 비-diffusers 소스 저장소를 가리키면, SGLang은 자체 호스팅 오버레이 저장소를 통해 이를 해석할 수 있어요.

SGLang은 먼저 내장 오버레이 레지스트리를 확인해요. 구체적인 내장 매핑은 CLI 표면을 바꾸지 않고 시간이 지나며 추가될 수 있어요.

오버라이드 예시:

export SGLANG_DIFFUSION_MODEL_OVERLAY_REGISTRY='{
  "Wan-AI/Wan2.2-S2V-14B": {
    "overlay_repo_id": "your-org/Wan2.2-S2V-14B-overlay",
    "overlay_revision": "main"
  }
}'

sglang generate \
  --model-path Wan-AI/Wan2.2-S2V-14B \
  --config configs/wan_s2v.yaml

오버레이 저장소는 완전한 diffusers 스타일/컴포넌트화 저장소여야 해요.

--model-path로서 오버레이 저장소 자체를 전달할 수도 있어요. 이 경우 _overlay/overlay_manifest.json을 포함해야 해요.

참고 사항:

  1. SGLANG_DIFFUSION_MODEL_OVERLAY_REGISTRY는 개발 및 디버깅용 선택적 오버라이드일 뿐이에요. JSON 객체 또는 JSON 파일 경로를 받으며, 현재 프로세스의 내장 항목을 확장하거나 대체할 수 있어요.
  2. 첫 로드 시 SGLang은:
    • 오버레이 저장소에서 오버레이 메타데이터를 내려받고
    • 원본 소스 저장소에서 필요한 파일을 내려받으며
    • ~/.cache/sgl_diffusion/materialized_models/ 아래에 로컬 표준 컴포넌트 저장소를 구축해요.
  3. 이후 로드에서는 materialized 로컬 저장소를 재사용해요. materialized 저장소가 런타임이 일반 컴포넌트화 모델 디렉터리로 로드하는 것이에요.

빠른 시작 (Quick Start)

Generate

sglang generate \
  --model-path Qwen/Qwen-Image \
  --prompt "A beautiful sunset over the mountains" \
  --save-output

Serve

sglang serve \
  --model-path Wan-AI/Wan2.1-T2V-1.3B-Diffusers \
  --num-gpus 4 \
  --ulysses-degree 2 \
  --ring-degree 2 \
  --port 30010

요청 및 응답 예시는 OpenAI-Compatible API를 참고해요.

Tip 전체 인자 목록은 sglang generate --help와 sglang serve --help를 사용해요. CLI 도움말 출력이 전체 플래그의 진실의 원천이에요.

공통 옵션 (Common Options)

모델 및 런타임 (Model and runtime)

  • --model-path {MODEL}: 모델 경로 또는 Hugging Face 모델 ID
  • --served-model-name {NAME}: 서빙 API가 노출하는 안정적인 모델 이름. 설정 시 --model-id로, 그렇지 않으면 --model-path로 기본 설정
  • --model-variant {NAME}: 하나의 모델 저장소가 여러 가중치 파티션을 포함할 때 로드할 의미론적 체크포인트 변형. 파이프라인은 로드 전에 이 안정 이름을 저장소 레이아웃에 매핑해요. 예: MiniMax-H3은 fl2va와 ref2va, 또는 명시적 병합 트랜스포머 가중치를 가진 hybrid를 수용해 세 작업 모두를 서빙해요(H3 쿡북 참고). 이것은 요청의 task와 달리 서버/로드 시점 선택이에요.
  • --minimax-h3-adaln-cache-path {FILE}: 고급 MiniMax-H3 전용 추론 캐시. 체크포인트의 AdaLN projection 가중치를 미리 계산된 출력으로 대체하며, 캐시에 포함된 정확한 FP32 timestep 플랜의 요청만 수용해요. 비양자화 가중치와 일치하는 모델 변형이 필요해요.
  • --minimax-h3-adaln-online {true,false}: 24.2 GiB의 adaln_proj 가중치를 상주시키는 대신 체크포인트에서 주문형으로 MiniMax-H3 AdaLN 출력을 재구축해요. 모든 스텝 수나 스케줄과 작동해요. 비양자화 네이티브 레이아웃 체크포인트를 요구해요. 구축된 플랜은 플랜별 LRU 축출과 기본적으로 pinned-host 캐시가 있는 GPU 슬랩에 있어, 이전에 본 스케줄이 체크포인트를 다시 읽는 대신 PCIe로 다시 교환돼요.
  • --minimax-h3-adaln-plan-width {N}: 온라인 슬랩 크기 조정이 되는 가장 넓은 timestep 플랜(기본 4는 모든 작업을 커버. t2va는 2, fl2va는 3 필요).
  • --minimax-h3-adaln-host-cache-gb {GB}: 구축된 AdaLN 플랜을 캐싱하는 rank당 pinned 호스트 메모리(기본 8, 0은 비활성화). 50-스텝 스케줄은 약 0.9 (t2va) / 1.33 (fl2va) / 1.77 (ref2va) GB가 필요해요. 용량 초과 플랜 집합은 단순히 재계산해요. 전문가 탈출 해치(GPU 슬롯 수, 실험적 fp32 재구축)는 SGLANG_DIFFUSION_MINIMAX_H3_ADALN_* 환경 변수예요.
  • --model-subfolder {PATH}: 모델 저장소 안의 컴포넌트 하위 폴더에 대한 고급 직접 오버라이드. 파이프라인이 의미론적 라우팅을 노출하면 --model-variant를 선호해요. 둘 다 제공되면 동일한 가중치 파티션으로 해석되어야 해요.
  • --lora-path {PATH} 및 --lora-nickname {NAME}: 로컬 경로, Hugging Face 저장소/하위 폴더 또는 정확한 Hub 파일 URL에서 LoRA 어댑터 로드
  • --lora-weight-name {FILE}: 여러 LoRA 리비전을 포함한 저장소에서 하나의 어댑터 파일 선택. Hub 다운로드는 해당 파일 + JSON 메타데이터로 필터링되므로 미사용 가중치는 내려받지 않아요.
  • --lora-alpha {N}: 단일 파일 어댑터가 레이어별 alpha 텐서와 adapter_config.json을 모두 생략할 때 훈련 alpha를 공급. 어댑터가 이미 alpha 메타데이터를 기록하면 설정하지 말아요.
  • PEFT adapter_config.json 시맨틱은 명명된 어댑터 슬롯, RSLoRA, 레이어별 alpha_pattern에 자동 적용돼요. DoRA 같은 지원되지 않는 보조 파라미터나 런타임 동작이 필요한 어댑터는 일반 LoRA 수학을 조용히 사용하는 대신 가중치 주입 전에 실패해요.
  • --lora-merge-mode {auto|merge|dynamic}: LoRA 적용 방식 선택. auto는 일반 가중치를 정적으로 병합하고 전체 gather 피크를 피하기 위해 FSDP-샤딩 가중치에 동적 LoRA를 사용해요.
  • --num-gpus {N}: 사용할 GPU 수
  • --performance-mode {manual|auto|speed|memory} / --mode: 지연 시간/처리량과 메모리 기본값 프리셋. auto가 기본이며 선택된 GPU 헤드룸과 워크로드 유형에서 상주를 분배해요: 이미지 DiT는 45 GiB 임계값 이상에서 상주하고, 비디오 DiT 배치는 모델별로 유지돼요. 검증된 DiT-offload 대체 경로에만 FSDP를 사용해요. speed는 모델별 배포 구성이 검증 후 옵트인하지 않는 한 torch.compile을 비활성 상태로 유지해요. --enable-torch-compile true를 전달해 명시적으로 활성화할 수 있어요. 성능 관련 서버 인자를 명시적 사용자 제어 아래 두려면 manual을 사용해요. 명시적 offload, FSDP, 병렬 처리 플래그가 모든 모드에서 우선해요.
  • --direct-gpu-weight-loading {true|false}: 완전한 체크포인트 state dict를 GPU에 구축하여 비양자화, GPU 상주, TP=1 DiT에 직접 GPU 로딩을 옵트인. 호환 텐서는 추가 GPU 복사 없이 파라미터 저장소가 되고, 변환이 필요한 텐서는 여전히 임시 할당이 필요할 수 있어요. 기본적으로 비활성. 시작 시간과 피크 GPU 메모리는 모델별이므로 배포 전에 대상 모델을 벤치마크해요. DiT CPU/layerwise offload 및 FSDP와는 호환되지 않아요.
  • --tp-size {N}: 텐서 병렬 처리 크기. 파이프라인에 따라 DiT, 하나 이상의 인코더, 또는 둘 다를 샤딩할 수 있어요.
  • --sp-degree {N}: 시퀀스 병렬 처리 크기
  • --dp-size {N} (별칭 --data-parallel-size): 데이터 병렬 복제본 수. 각 복제본은 num_gpus / N GPU에서 자체 ingress를 가진 엔진의 완전한 사본이에요. 생성 요청은 복제본에 라운드로빈되고, 실시간 세션은 상태를 가진 복제본에 고정되며, 제어 작업(가중치, LoRA, 메모리 점유, 종료)은 모든 복제본에 적용돼요. 다른 병렬 축과 결합돼요 (num_gpus = dp × cfg × tp × sp). 모놀리식 서빙 전용.
  • --ulysses-degree {N} 및 --ring-degree {N}: USP 병렬 처리 제어
  • --kv-gather-degree {N}: 어텐션 내부에서 행을 분할하고 Ulysses all-to-all 대신 하나의 K/V all-gather(쿼리는 로컬 유지)로 교환하는 시퀀스 병렬 정도. 비-인과 어텐션 전용. 아직 --ulysses-degree/--ring-degree와는 조합되지 않아요. SP 정도를 명시적으로 설정하지 않으면 sp_degree=2는 기본으로 kv_gather_degree=2(측정된 이득 구역)가 되고 더 높은 정도는 Ulysses로 기본 설정돼요. 그 자동 할당에서 gather 경로를 호출할 수 없는 어텐션은 Ulysses 교환으로 폴백할 수 없고, 명시적 정도는 저하 대신 실패해요.
  • --enable-cfg-parallel {true|false}: CFG 병렬 처리 활성화 또는 명시적 비활성화. CFG를 비활성화한 요청은 CFG-병렬 서버에서도 유효하지만, 추가 CFG rank는 단일 활성 브랜치를 중복 재계산해요.
  • --encoder-parallel {auto|fold|dp|replicate}: 네이티브 인코더가 각 DiT 복제본의 GPU를 사용하는 방식. auto는 이득이 될 만큼 넓게 네이티브 텍스트/이미지 인코더를 TP-폴딩하고, 참여할 수 있을 때 명시적으로 지원되는 네이티브 텍스트 인코더에 배치 DP를 선택하며, 그 외에는 기존 인코더 TP 레이아웃을 유지해요. fold는 차원이 허용될 때 네이티브 텍스트/이미지 인코더를 전체 복제본에 분할. dp는 지원되는 네이티브 텍스트 인코더 복사본에 배치 인코드를 분할하고 인코더 TP와 조합. replicate는 폴딩과 배치 DP를 비활성화. 인코더 집합 연산은 --dp-size 복제본을 절대 넘지 않아요. Encoder Parallelism 참고.
  • --warmup-mode {off|request|server}: sglang serve의 시작 워밍업 제어. off는 워밍업을 건너뛰고, request는 요청 경로를 준비하며, server는 트래픽 서빙 전에 완전한 합성 서버 워밍업을 실행
  • --enable-torch-compile {true|false}: 네이티브 확산 핫 경로 컴파일. 워밍업 모드가 구성되지 않으면 첫 실제 요청이 컴파일 지연을 지불하지 않도록 서버 워밍업도 활성화해요.
  • --offload-during-compile {true|false}: 컴파일 워밍업이 활성일 때 DiT 가중치를 임시 레이어별 offload하고 상주 비-DiT 컴포넌트를 오프디바이스로 이동시켜 max-autotune이 더 타이트한 메모리 GPU에 맞게 해요. 실제 트래픽 전에 구성된 서빙 상주가 복원돼요. 기존 layerwise offload, Cache-DiT 또는 FSDP에서 건너뜀.
  • --enable-breakable-cuda-graph {true|false}: 지원되는 DiT forward를 breakable CUDA graph 세그먼트로 캡처해 실행 오버헤드를 줄여요. 각 해상도가 별도로 캡처되므로 모든 서빙 해상도에 --warmup-resolutions이 필요해요. lossless 그래프 캡처 중에 없던 요청 범위 DiT 융합을 장착할 extra-high 또는 high 요청은 거부돼요. VAE 전용 요청 게이팅 경로는 호환으로 유지돼요.
  • --bcg-text-buckets {N...}: breakable CUDA graph 캡처/재생 재사용을 위한 프롬프트 길이 패딩 버킷.
  • --attention-backend {BACKEND}: 네이티브 SGLang 및 diffusers 파이프라인의 어텐션 백엔드
  • --enable-attention-backend-autotune {true|false}: SGLang 네이티브 파이프라인에서 각 레이어의 첫 충분히 큰 입력에서 호환 어텐션 백엔드를 벤치마크하고, 수치적으로 호환되고 측정 가능하게 빠른 경우에만 백엔드를 유지해요. 기본 비활성이며 현재 SM90 및 SM12x에서 검증됨. 명시적 --attention-backend, 컴포넌트 오버라이드, 모델 필수 백엔드는 절대 대체되지 않아요.
  • --component-attention-backends {MAP}: 컴포넌트별 어텐션 백엔드 오버라이드. 예: text_encoder=torch_sdpa,transformer=fa
  • --attention-backend-config {CONFIG}: 어텐션 백엔드 구성
  • --srt-encoder-url {HTTPADDRESS}: GLM-Image 같은 모델용 AR 모델이 있는 SGLang srt 서버 주소. Models with AR Stage 참고.
  • --srt-encoder-timeout {SECONDS}: SGLang 인코더 서버에 대한 HTTP 요청 타임아웃(초)
  • --srt-encoder-connection-timeout {SECONDS}: SGLang 인코더 서버에 대한 TCP 연결 타임아웃(초)
  • --scheduler-rpc-timeout {SECONDS}: 스케줄러 큐 시간을 포함한 내부 스케줄러 RPC에 대한 선택적 end-to-end 데드라인. 기본적으로 설정되지 않아 유효한 장기 실행 및 큐잉된 비디오 작업이 전송 계층에 의해 실패하지 않아요. 배포가 바운드 요청 데드라인을 요구할 때만 설정해요. 호출자 취소와 서버 종료는 그것 없이도 유효해요.
  • --enable-trace: 확산 스케줄러와 워커 단계에 대한 OpenTelemetry 트레이스 내보내기.
  • --otlp-traces-endpoint {HOST:PORT}: --enable-trace와 함께 사용하는 OTLP 수집기 엔드포인트 (기본값: localhost:4317).
  • --otlp-service-name {NAME}: 내보낸 트레이스에 붙는 service.name. 해석 순서는 이 플래그, OTEL_SERVICE_NAME, 그 다음 sglang-diffusion.
  • --enable-metrics: /metrics에서 Prometheus 메트릭 노출 (기본: 비활성). 역할과 DP 복제본별로 분리된 요청 수, 큐 시간, 호스트 측 단계 타이밍과 LoRA 상태를 포함해요. 메트릭 시맨틱과 disaggregated 스크래핑은 Production metrics 참고.
  • --pe-server-url {HTTPADDRESS}: PE 모델(예: ERNIE-Image)을 호스팅하는 SGLang 서버의 URL. Models with Prompt Enhancement 참고.

샘플링 및 출력 (Sampling and output)

  • --prompt {PROMPT} 및 --negative-prompt {PROMPT}
  • --image-path {PATH} [{PATH} ...]: image-to-video 또는 image-to-image 생성을 위한 입력 이미지
  • --num-inference-steps {STEPS} 및 --seed {SEED}
  • --num-outputs-per-prompt {N} / --num-outputs {N}: 각 프롬프트에 여러 출력 생성. 스칼라 시드는 seed + output_index로 확장.
  • --quality {lossless,extra-high,high}: 누적 요청 수준 최적화 등급. lossless(기본)는 선택된 배포의 참조 경로와 모든 무조건적 비트 정확 대체를 유지. extra-high는 요청 게이팅된 DiT/VAE 커널 융합만 추가. 등급 자체로 sparse, caching 또는 다른 근사 경로를 활성화하지 않아요. high는 완전한 extra-high 집합을 포함하고 모델 소유 근사 최적화도 활성화할 수 있어요. 별도로 구성된 양자화, 어텐션 또는 캐싱 옵션은 여전히 적용돼요. 지원 및 검증 제약은 모델별.
  • skip_softmax_params (온라인 요청 전용): 호환되는 FA self-attention 레이어에 손실 있는 BLASST/Skip-Softmax 어텐션을 명시적으로 활성화. Attention Backends 참고.
  • --height {HEIGHT}, --width {WIDTH}, --num-frames {N}, --fps {FPS}
  • --output-path {PATH}, --output-file-name {NAME}, --save-output, --return-frames

프레임 보간과 업스케일링은 Post-Processing 참고.

양자화 (Quantization)

컴포넌트 체크포인트 경로는 별도로 선택되므로 DiT 정밀도를 바꾸는 것이 프롬프트 임베딩을 조용히 바꾸지 않아요. 컴포넌트 범위 형태는 model_index.json의 컴포넌트 키 또는 네이티브 파이프라인의 등록된 모듈 이름에 대한 정식 인터페이스예요:

의도 정식 옵션 편의 별칭 동작
컴포넌트 교체 --component-paths.<component> {MODEL} --<component>-path {MODEL} 교체 컴포넌트의 구성과 가중치 로드
가중치만 교체 --component-weights-paths.<component> {WEIGHTS} --<component>-weights-path {WEIGHTS} 기본 컴포넌트 구성 유지, 가중치만 교체
컴포넌트 정밀도 선택 --component-precisions.<component> {DTYPE} — 로더가 지원하는 정확한 파라미터 및 실행 dtype 사용
적격 컴포넌트 직접 로드 --component-direct-gpu-weight-loading.<component> 없음 해당 컴포넌트의 감사된 직접-GPU 로더 사용. 상주해야 함
비양자화 컴포넌트 온라인 양자화 --component-quantizations.<component> {METHOD} --<component>-quantization {METHOD} 해당 컴포넌트 네이티브 로더가 지원하는 방법 적용
선택 컴포넌트 레이어 비양자화 유지 --component-quantization-ignored-layers.<component> {PATTERN...} 없음 컴포넌트 로컬 무시 레이어 패턴을 온라인 양자화기에 전달

예를 들어, 어떤 교체 텍스트 인코더 구성도 별도의 단일 파일 체크포인트와 다음과 같이 짝지을 수 있어요:

--component-paths.text_encoder COMPONENT_REPO_OR_DIRECTORY \
--component-weights-paths.text_encoder WEIGHTS_FILE_OR_REPO_FILE

트랜스포머 전용 --transformer-weights-path 철자는 기본 DiT에 대해 계속 지원돼요. --component-weights-paths.transformer로 기계적으로 대체하지 말아요: 컴포넌트 범위 형태는 실제 컴포넌트 이름이 필요하며, 이는 파이프라인별이에요. --quantization은 트랜스포머 로더가 추론한 방법을 오버라이드할 때만 사용하고, 온라인 양자화 중 일치하는 트랜스포머 레이어를 비양자화로 유지하려면 --quantization-ignored-layers를 사용해요.

네이티브 텍스트 인코더의 경우:

  • --component-paths.text_encoder {MODEL}는 텍스트 인코더 체크포인트를 교체하고, --text-encoder-path {MODEL}는 더 짧은 별칭이에요
  • --component-quantizations.text_encoder {METHOD}는 비양자화 네이티브 인코더에 지원되는 온라인 양자화를 적용해요. 선택 레이어가 비양자화로 유지되어야 하면 --component-quantization-ignored-layers.text_encoder {PATTERN...}와 짝지어요
  • 양자화 메타데이터는 해당 체크포인트에서 자동 감지돼요. 네이티브 로더는 모델 이름 허용 목록 없이 호환 직렬화 형식을 수용하고, 필요한 양자화 레이어를 구성하지 않는 구현을 거부해요.

동일한 계약이 모든 가중치 컴포넌트에 적용돼요: 경로 라우팅은 일반적이고, 양자화된 materialization은 능력 기반이에요. 현재 materializer가 일반 state dict를 기대하는 네이티브 보조 로더는 모델 구성 전에 지원되지 않는 양자화 메타데이터를 거부해요. 현재 컴포넌트 매트릭스는 Quantized Component Repositories 참고. 모델 쿡북은 게시된 모델별 체크포인트 예시의 진실의 원천이에요. 예: 모든 H3 소스와 정확한 오버레이는 하나의 MiniMax-H3 compatibility table에 보관돼요.

정확한 정밀도 오버라이드는 능력 기반이에요. 네이티브 텍스트 및 이미지 인코더, 표준 VAE 컴포넌트, 네이티브 일반-state 컴포넌트는 이를 지원하고, 다른 컴포넌트 로더는 실행 단계가 준수하지 않을 dtype을 수용하는 대신 옵션을 거부해요.

Direct-GPU 로딩도 능력 기반이에요. 기존 --direct-gpu-weight-loading은 기본 DiT 경로로 유지돼요. 컴포넌트 형태는 현재 CUDA에서 표준 네이티브 vae 및 video_vae state dict를 지원해요. 각 safetensors 텐서를 완전한 CPU state dict를 구축하는 대신 상주 모듈로 직접 스트리밍해요. 커스텀 Diffusers auto_map 클래스, 양자화 체크포인트, tied state 항목, 컴포넌트-offload 또는 layerwise-offload 배치를 거부해요.

컴포넌트 오버라이드는 로컬 컴포넌트 디렉터리, 독립 Hub 저장소, 또는 owner/repo/subfolder로 작성된 Hub 컴포넌트 하위 폴더를 수용해요. 트랜스포머 및 네이티브 인코더 로더의 경우 명시적 가중치 파일 이름은 기본 컴포넌트 구성을 유지하고 가중치만 교체해요. 선택된 파일 형식은 여전히 해당 로더가 지원해야 해요.

지원되는 실시간 인과 비디오 모델의 경우 --kv-cache-quant {off|int4|int2}는 트랜스포머 가중치 양자화와 독립적으로 완료된 KV-캐시 청크를 압축해요. 손실이 있고 기본적으로 비활성.

런타임과 모델 범위는 Realtime and Causal Video Models, 지원되는 양자화 패밀리와 예시는 Quantization 참고.

요청 로깅 (Request logging)

  • --log-requests: 모든 요청의 사용자 측 필드 로그 (기본값: False). 상세도는 --log-requests-level이 결정.
  • --log-requests-level &#123;0|1|2|3&#125;: 요청 로깅 상세도 (기본값: 2). 0: 메타데이터 로그 (request id). 1: 메타데이터와 샘플링 구성 (seed, steps, guidance, resolution, frames, fps, ...). 2: 메타데이터, 샘플링 구성과 프롬프트 (2 KiB로 절단). 3: 메타데이터, 샘플링 구성과 전체 프롬프트.
  • --log-requests-format &#123;text|json&#125;: 요청 로깅 형식 (기본값: text). text는 사람이 읽을 수 있고, json은 구조화된 JSON 라인을 출력.
  • --log-requests-target &#123;TARGET...&#125;: 요청 로깅 대상. 콘솔 출력에 stdout, 파일 출력에 디렉터리 경로. 여러 대상을 지정할 수 있어요. 예: --log-requests-target stdout /my/log/dir.

구성 파일 (Configuration Files)

--config로 JSON 또는 YAML 구성을 로드해요. 커맨드라인 플래그가 구성 파일의 값을 오버라이드해요.

sglang generate --config config.yaml

예시:

model_path: FastVideo/FastHunyuan-diffusers
prompt: A beautiful woman in a red dress walking down a street
output_path: outputs/
num_gpus: 2
sp_degree: 2
tp_size: 1
num_frames: 45
height: 720
width: 1280
num_inference_steps: 6
seed: 1024
fps: 24
precision: bf16
vae_precision: fp16
vae_tiling: true
vae_sp: true
enable_torch_compile: false

HunyuanVideo와 FastHunyuan은 기본적으로 tiled VAE decode를 사용해 다중 GPU 실행이 공간 샤드 디코드를 선택하는 대신 VAE 타일을 분배해요. HunyuanVideo의 지원되는 960×544×77 형태에서 공간 샤드 디코드는 또 다른 49.61 GiB 인과 마스크를 요청하기 전에 rank당 99.8 GiB를 소비할 수 있어요. FastHunyuan의 기본 1280×720×125 형태에서 마스크만 197.75 GiB를 요구해요. --vae-config.parallel-decode-mode로 정책을 여전히 오버라이드할 수 있지만, spatial과 spatial_shard는 더 작은 검증된 형태에만 사용해야 해요.

Generate

sglang generate는 단일 생성 작업을 실행하고 작업이 끝나면 종료해요.

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --text-encoder-cpu-offload \
  --pin-cpu-memory \
  --num-gpus 4 \
  --ulysses-degree 2 \
  --ring-degree 2 \
  --prompt "A curious raccoon" \
  --save-output \
  --output-path outputs \
  --output-file-name "a-curious-raccoon.mp4"

Note HTTP 서버 전용 인자는 sglang generate에서 무시돼요.

지원되는 네이티브 파이프라인에서 SGLANG_CACHE_DIT_ENABLED=true로 Cache-DiT를 활성화해요. DiT layerwise offload와 함께 실행할 수 있고 FSDP와는 실행할 수 없어요. diffusers 백엔드에서는 --backend diffusers --cache-dit-config ...를 사용해요. Cache-DiT 참고.

지원되는 이미지 파이프라인에서 breakable CUDA graph는 --enable-breakable-cuda-graph로 활성화할 수 있지만, 워밍업이 일치하는 그래프 시그니처를 캡처하도록 모든 서빙 해상도를 --warmup-resolutions에 선언해야 해요.

LongCat-Image는 이 경로로 지원돼요. 그 DiT는 항상 고정 512-토큰 프롬프트 본문을 소비하므로 다른 프롬프트 길이가 모델별 패딩 없이 같은 그래프를 재사용해요. 1024x1024 배포에는:

sglang serve --model-path meituan-longcat/LongCat-Image \
  --enable-breakable-cuda-graph \
  --warmup-resolutions 1024x1024 \
  --enable-torch-compile false \
  --port 30010

SANA-Video는 고정 형태 서빙에 같은 경로를 지원해요. 기본 텍스트 단계가 고정 300-토큰 프롬프트 형태를 내므로 런타임은 일반 텍스트 버킷으로 패딩하지 않고 프롬프트 길이에 걸쳐 하나의 그래프를 재사용해요. BCG도 서빙 프레임 수가 워밍업과 일치해야 해요. 예시는 모델의 기본 81-프레임 시그니처를 캡처해요:

sglang serve \
  --model-path Efficient-Large-Model/SANA-Video_2B_480p_diffusers \
  --enable-breakable-cuda-graph \
  --warmup-resolutions 832x480 \
  --enable-torch-compile false \
  --port 30010

컴포넌트 상주 (Component Residency)

각 네이티브 파이프라인 컴포넌트에 하나의 런타임 상주 모드를 할당하려면 --component-residency COMPONENT=MODE을 사용해요:

sglang generate \
  --model-path Wan-AI/Wan2.1-T2V-1.3B-Diffusers \
  --component-residency all=resident text_encoder=layerwise-offload vae=component-offload \
  --prompt "A quiet city street after rain"

사용 가능한 모드:

  • resident: 완전한 컴포넌트를 가속기에 유지.
  • component-offload: 사용 사이에 완전한 컴포넌트를 CPU에 유지하고, 각 선언된 사용 전에 가속기로 이동 후 다시 CPU로.
  • snapshot-offload: 완전한 컴포넌트가 GPU에서 실행되는 동안 CPU 파라미터 저장소를 유지. 사용이 끝나면 GPU 가중치를 다시 복사하는 대신 CPU 파라미터를 복원. 변경 가능한 버퍼는 여전히 CPU로 이동.
  • layerwise-offload: 컴포넌트 가중치를 CPU에 유지하고 실행 중 선언된 레이어를 스트리밍.

셀렉터는 model_index.json의 정확한 로드된 컴포넌트 키(예: transformer_2, audio_vae, connectors)와 일치해요. dit, text_encoder, image_encoder, vae 그룹 셀렉터와 all도 사용 가능해요. 정확한 키는 일치하는 그룹을 오버라이드하고, 그룹은 all을 오버라이드해요. 일치하는 정식 셀렉터가 없는 컴포넌트는 명시적 레거시 설정 또는 자동/모델 기본값을 유지해요.

기존 --dit-cpu-offload, --text-encoder-cpu-offload, --image-encoder-cpu-offload, --vae-cpu-offload, --cpu-offload-components 옵션은 계속 지원돼요. 새 옵션과 레거시 옵션은 혼합될 수 있어요: --component-residency는 일치하는 컴포넌트에서만 이기고, 일치하지 않는 레거시 설정은 유효하게 유지돼요. 레거시 layerwise 셀렉터는 같은 컴포넌트의 레거시 component-offload 셀렉터보다 우선해요. 명시적 --dit-layerwise-offload false는 DiT를 상주하게 하고, --dit-cpu-offload true 또는 --component-residency dit=component-offload 같은 다른 명시적 DiT 셀렉터가 다른 모드를 선택하지 않으면요.

Layerwise 선택은 엄격해요. layerwise-offload로 선택된 네이티브 가중치 컴포넌트는 레이어 구조를 선언해야 해요. 그렇지 않으면 모드를 조용히 바꾸는 대신 지원되지 않는 컴포넌트 이름으로 시작이 실패해요. 명시적 비-상주 배치도 요청 시 컴포넌트 사용 선언을 요구하므로, 파이프라인이 관리하지 않는 모듈을 조용히 선택할 수 없어요. FSDP는 상주 컴포넌트에만 적용돼요. Diffusers 백엔드는 파이프라인 전역 all=resident와 all=component-offload만 지원해요.

스냅샷 오프로드 (Snapshot offload)

호스트와 디바이스 메모리가 분리된 NVIDIA CUDA GPU에서 반복 가중치 D2H 전송을 피하려면 --component-residency vae=snapshot-offload를 명시적으로 선택해요. 기존 기본값과 component-offload 동작은 변경되지 않아요.

스냅샷 오프로드는 GPU 실행 중 완전한 호스트 사본을 유지해요. --pin-cpu-memory가 활성(기본)이면 layerwise offload와 워커당 호스트 핀 예산을 공유해요. Layerwise 초기화가 먼저 허용량을 요구하고, 스냅샷 가중치가 나머지를 사용해요. 공유 파라미터 저장소는 한 번 핀되어 요청 간 재사용되고, 해제 시 허용량이 반환돼요. 핀은 cgroup 한도를 포함한 현재 호스트 헤드룸도 확인해요.

예산에 맞지 않거나 핀이 비활성화된 가중치는 기존 CPU 저장소를 유지해요. 체크포인트 mmap은 핀, dtype 변환 또는 가중치 변형이 사본을 만들지 않는 한 파일 지원으로 유지돼요. 페이지 가능한 H2D는 더 느릴 수 있고, 핀은 원본과 핀된 저장소 모두에 잠시 공간이 필요해요. 이 예산은 새 핀 가중치 할당을 제한하지, 총 프로세스 RAM이나 CUDA 호스트 할당자 캐시를 제한하지 않아요. 실제 호스트 저장소와 워크로드로 반복 요청을 벤치마크해요. D2H 회피가 end-to-end 속도 향상을 보장하지는 않아요.

전체 컴포넌트는 여전히 GPU에 맞아야 해요. 디노이징 스텝에 걸쳐 모든 레이어를 유지하는 layerwise offload와 달리, 스냅샷 오프로드는 레이어 구조 선언을 요구하지 않고 트랜스포머 블록 외부의 파라미터도 커버해요. 가중치 업데이트, LoRA 병합/병합 해제, sleep은 변형 또는 해제 전에 CPU 가중치를 복원해요. FSDP 관리 컴포넌트, 공유 메모리 GPU, breakable CUDA graph가 있는 스냅샷 오프로드 DiT는 지원되지 않아요.

Layerwise 오프로드 튜닝 (Layerwise Offload Tuning)

컴포넌트가 GPU 메모리에 편안히 맞지 않을 때 layerwise offload를 사용해요. 호환 옵션 --dit-layerwise-offload와 --layerwise-offload-components는 계속 사용 가능하고(--layerwise-offload-modules는 별칭), 새 배포는 모드를 직접 선택할 수 있어요:

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --component-residency transformer=layerwise-offload text_encoder=layerwise-offload \
  --dit-offload-prefetch-size 0 \
  --prompt "A quiet city street after rain"

호환 옵션 --layerwise-offload-components에 전달된 값은 transformer, text_encoder, image_encoder, vae, condition_image_encoder, spatial_upsampler, vocoder 같은 로드된 컴포넌트 키와 일치해야 해요. 그 default 그룹은 텍스트 인코더, 이미지 인코더, VAE를 선택해요. all로 모든 layerwise-offload 가능 컴포넌트를 선택해요.

--dit-offload-prefetch-size, --dit-layerwise-resident-layers, --dit-layerwise-residency-policy, --dit-layerwise-residency-lifetime 같은 Layerwise 튜닝 옵션은 계속 스트리밍 레이어 작업 집합을 제어해요. layerwise offload는 지연 시간을 늘릴 수 있으므로 메모리 문제를 해결하는 가장 작은 컴포넌트 집합을 선호해요. DiT layerwise offload는 Cache-DiT와 함께 실행할 수 있어요: 건너뛴 블록은 스트리밍되지 않고, 건너뛴 후 첫 레이어는 sync-load할 수 있어요. Cache-DiT는 FSDP와 여전히 호환되지 않아요.

이 네 가지는 모든 스트리밍 컴포넌트의 기본을 설정해요. 한 컴포넌트에 자체 값을 주려면 component=value 형태를 사용하고, JSON도 수용해요:

sglang serve --model-path <MODEL> \
  --layerwise-offload-components dit,text_encoder \
  --layerwise-prefetch-size text_encoder=2 \
  --layerwise-resident-layers transformer=4 \
  --layerwise-residency-policy transformer=strided \
  --layerwise-residency-lifetime transformer=permanent

component=value 맵은 로드된 컴포넌트의 이름 — transformer, text_encoder, video_vae — 을 취하지 그룹 별칭을 취하지 않아요. --layerwise-offload-components는 dit를 이해하지만 --layerwise-resident-layers dit=4는 어떤 컴포넌트와도 일치하지 않고 조용히 무시돼요.

  • --layerwise-prefetch-size: 몇 레이어를 미리 가져올지. 분수 값은 스택의 몫이고, >= 1은 절대 수. 더 깊은 프리페치는 스테이징 버퍼 비용으로 계산과 더 많은 전송을 겹칩니다.
  • --layerwise-resident-layers: 스트리밍 대신 GPU에 몇 레이어를 유지할지. 분수 값은 스택의 몫. 상주 레이어는 요청당 여러 번 레이어를 실행하는 컴포넌트 — 디노이즈 스텝에 걸친 DiT, 잠재 청크에 걸친 비디오 VAE — 에 비용을 지불하고, 텍스트 인코더처럼 요청당 한 번 실행하는 컴포넌트에는 아무것도 하지 않아요.
  • --layerwise-residency-policy: leading은 첫 레이어를 유지하고, strided는 전송이 하나의 버스트로 도착하지 않도록 스택에 퍼뜨려요.
  • --layerwise-residency-lifetime: 상주 레이어가 얼마나 오래 유지되는지. forward(기본)는 컴포넌트가 요청에 대해 레이어 실행을 시작할 때 배치하고 끝나면 해제하므로, 요청당 한 번 전송되고 호스트 메모리에 사본을 유지해요. permanent는 로드 시 배치하고 호스트 사본을 유지하지 않으며 해제하지 않아요: 서버 수명 동안 한 번 전송.

항목이 없는 컴포넌트는 그룹 기본값을 유지하므로, 하나가 설정되기 전까지 이 옵션을 추가해도 아무것도 바뀌지 않아요. 이 모든 것은 VRAM을 전송과 교환해요. 수명은 누구의 VRAM인지 결정해요: forward에서는 실행 중인 컴포넌트만 상주 레이어를 보유하므로 피크는 가장 큰 단일 컴포넌트 집합이고, permanent에서는 모든 컴포넌트의 상주 레이어가 동시에 GPU에 있으므로 피크가 그 합이에요. 합이 활성화와 함께 맞으면 permanent를 선택해요 — 사본이 보유했을 pinned 호스트 메모리도 해제해요 — 맞지 않으면 forward를 선택해요. 어느 것이든 올리기 전에 측정해요.

Serve

sglang serve는 HTTP 서버를 시작하고 반복 요청을 위해 모델을 로드 상태로 유지해요.

sglang serve \
  --model-path Wan-AI/Wan2.1-T2V-1.3B-Diffusers \
  --text-encoder-cpu-offload \
  --pin-cpu-memory \
  --num-gpus 4 \
  --ulysses-degree 2 \
  --ring-degree 2 \
  --port 30010

헬스 엔드포인트 (Health endpoints)

SGLang Diffusion은 프로세스 활력과 추론 준비 상태를 분리해요:

엔드포인트 성공 조건 권장 사용
GET /liveness HTTP 서버가 요청을 수용 중. 서버 워밍업 중에도 200 유지 Kubernetes liveness probe
GET /health 서버가 정상 추론 트래픽 준비. 서버 기반 합성 워밍업 실행 중 503, 완료 후 200 시작 및 준비 probe
GET /health_generate /health의 호환 별칭. 현재 SGLang Diffusion에서 생성 요청을 발행하지 않음 기존 통합 전용

/health는 서버 기반 워밍업만 게이트해요. --warmup-mode off 또는 --warmup-mode request에서는 HTTP 서버가 시작되면 200을 반환해요. 이 모드들은 컴파일 또는 기타 첫 요청 작업이 완료됐다고 약속하지 않아요. 서버 기반 워밍업이 실패하면 서버는 준비 보고 대신 종료해요.

/health를 liveness probe로 사용하지 말아요: 긴 서버 워밍업은 타당하게 여러 분 동안 503으로 유지할 수 있어요.

클라우드 저장소 (Cloud Storage)

SGLang Diffusion은 생성 후 이미지와 비디오를 S3 호환 객체 저장소에 업로드할 수 있어요.

export SGLANG_CLOUD_STORAGE_TYPE=s3
export SGLANG_S3_BUCKET_NAME=my-bucket
export SGLANG_S3_ACCESS_KEY_ID=your-access-key
export SGLANG_S3_SECRET_ACCESS_KEY=your-secret-key
export SGLANG_S3_ENDPOINT_URL=https://minio.example.com

전체 저장소 옵션 집합은 Environment Variables 참고.

컴포넌트 경로 오버라이드 (Component Path Overrides)

--<component>-path로 vae, transformer, text_encoder 같은 개별 파이프라인 컴포넌트를 오버라이드해요.

sglang serve \
  --model-path black-forest-labs/FLUX.2-dev \
  --vae-path fal/FLUX.2-Tiny-AutoEncoder

컴포넌트 키는 모델의 model_index.json의 키 또는 네이티브 파이프라인의 등록된 모듈 이름과 일치해야 해요. 경로는 Hugging Face repo ID 또는 완전한 컴포넌트 디렉터리여야 해요.

경로 선택과 양자화 체크포인트 지원은 별개의 능력이에요. 사전 양자화 컴포넌트 저장소는 양자화 메타데이터를 운반해야 하고, 선택된 로더가 그 직렬화 형식을 지원해야 해요. 네이티브 plain-state 로더는 fail-closed하고, 라이브러리 관리 컴포넌트는 해당 Transformers 또는 Diffusers 지원을 상속해요. 트랜스포머 전용 --quantization 플래그는 컴포넌트 체크포인트의 형식을 선택하지 않아요. 그들의 메타데이터가 선택해요. Quantized Component Repositories 참고.

컴포넌트 어텐션 백엔드 오버라이드 (Component Attention Backend Overrides)

한 파이프라인 컴포넌트가 전역 --attention-backend과 다른 네이티브 어텐션 백엔드가 필요할 때 --component-attention-backends를 사용해요.

sglang generate \
  --model-path Lightricks/LTX-2.3 \
  --attention-backend fa \
  --component-attention-backends text_encoder=torch_sdpa

컴포넌트 키는 text_encoder, text_encoder_2, transformer, transformer_2, connectors 같은 파이프라인 모듈 키와 일치해야 해요. 컴포넌트 오버라이드는 해당 컴포넌트가 구성되는 동안 전역 --attention-backend보다 우선하고, 컴포넌트가 이를 충족할 수 없으면 실패해요. 네이티브 컴포넌트는 첫 사용까지 백엔드 선택을 명시적으로 연기할 수 있고, 고정 어텐션이 있는 컴포넌트는 오버라이드를 거부해요. Sparse self-attention 백엔드는 cross-attention 레이어에 호환 dense 백엔드를 사용해요. 전역 백엔드는 DiT 컴포넌트에서 엄격하게 유지되고, 보조 컴포넌트는 호환 백엔드로 폴백할 수 있어요. Diffusers 백엔드는 전역 백엔드 패스스루만 지원해요.

점으로 구분된 CLI 항목을 전달할 수도 있어요:

sglang generate \
  --model-path <MODEL_PATH_OR_ID> \
  --component-attention-backends.text_encoder torch_sdpa \
  --component-attention-backends.transformer fa

Diffusers 백엔드 (Diffusers Backend)

네이티브 SGLang 구현이 없거나 모델이 커스텀 파이프라인 클래스를 요구할 때 --backend diffusers로 기본 diffusers 파이프라인을 강제해요.

주요 옵션 (Key Options)

인자 값 설명
--backend auto, sglang, diffusers 네이티브 SGLang 선택, 네이티브 강제, 또는 diffusers 강제
--attention-backend flash, \_flash\_3\_hub, sage, xformers, native diffusers 파이프라인용 어텐션 백엔드
--trust-remote-code flag 커스텀 파이프라인 클래스가 있는 모델에 필요
--vae-tiling 및 --vae-slicing flag VAE 디코드의 메모리 사용량을 낮춤
--dit-precision 및 --vae-precision fp16, bf16, fp32 정밀도 제어
--enable-torch-compile flag torch.compile 활성화
--cache-dit-config {PATH} diffusers 파이프라인용 Cache-DiT 구성

예시 (Example)

sglang generate \
  --model-path AIDC-AI/Ovis-Image-7B \
  --backend diffusers \
  --trust-remote-code \
  --attention-backend flash \
  --prompt "A serene Japanese garden with cherry blossoms" \
  --height 1024 \
  --width 1024 \
  --num-inference-steps 30 \
  --save-output \
  --output-path outputs \
  --output-file-name ovis_garden.png

CLI에 노출되지 않은 파이프라인별 인자는 구성 파일의 diffusers_kwargs로 전달해요.

더 알아보기