모델 로딩
모델 로딩 (Model Loading)
SGLang이 모델 가중치를 어떻게 불러올지 제어하는 방법을 설명합니다. 로드 포맷, 모델 로더 추가 설정, 멀티스레드 로딩, 프리페칭, 원격·스트리밍 로더를 다뤄요. --model-path가 서빙할 체크포인트를 고르고, --load-format과 아래 가중치 로딩 플래그들이 그 가중치를 메모리로 읽는 방식을 제어합니다.
출처: 문서
본문
SGLang이 모델 가중치를 불러오는 방식을 제어: 로드 포맷, 모델 로더 추가 설정, 멀티스레드 로딩, 프리페칭, 원격/스트리밍 로더.
--model-path가 서빙할 체크포인트를 선택하고, --load-format과 아래 가중치 로딩 플래그가 그 가중치를 메모리로 읽는 방식을 제어합니다. 클라우드 객체 스토리지(S3/GCS/Azure)에서 가중치를 스트리밍하려면 Loading Models from Object Storage를 참고하세요.
로딩이 어떻게 동작하는가 (How loading works)
SGLang은 --load-format에서 로더를 고르고, 체크포인트나 모델 경로에서 자동 탐지로 폴백합니다. 기본 auto 로더는 safetensors를 읽고 PyTorch .bin으로 폴백합니다.
python -m sglang.launch_server \
--model-path Qwen/Qwen3.6-35B-A3B \
--load-format auto
일부 포맷은 자동 탐지되어 auto를 오버라이드합니다:
- Mistral 네이티브 체크포인트는 탐지되어
mistral로 로드됨. .gguf모델 경로는 탐지되어gguf로 로드됨.- 객체 스토리지 URI(
s3://,gs://,az://)는runai_streamer로 로드됨. - 원격 URI는
remote로 로드됨.
로드 포맷 (Load formats)
--load-format으로 설정합니다:
| Format | Description |
|---|---|
auto |
기본. 가능하면 safetensors 로드, 아니면 PyTorch .bin 포맷으로 폴백. |
safetensors |
safetensors 포맷으로 가중치 로드. |
pt |
PyTorch .bin 포맷으로 가중치 로드. |
npcache |
PyTorch 포맷 가중치를 로드하고, 이후 로드를 빠르게 하기 위해 numpy 캐시 저장. .bin 체크포인트만 지원. |
dummy |
프로파일링용으로 가중치를 랜덤 값으로 초기화. |
sharded_state |
각 텐서 병렬 워커가 전체 체크포인트 대신 자신의 pre-sharded 샤드만 읽어, 대형 TP 모델에 빠른 로드 경로 제공. sharded 체크포인트 생성은 examples/runtime/engine/save_sharded_state.py 참고. |
fastsafetensors |
fastsafetensors 이터레이터로 safetensors 로드. |
layered |
가중치를 레이어별로 로드해, 다음 레이어가 로드되기 전에 레이어를 양자화할 수 있어 피크 메모리 엔벨로프를 낮춤. |
gguf |
GGUF 포맷으로 가중치 로드. .gguf 모델 경로에서 자동 탐지됨. |
bitsandbytes |
bitsandbytes 양자화로 가중치 로드. |
mistral |
Mistral 네이티브 포맷 체크포인트 로드. 해당 체크포인트에서 자동 탐지됨. |
flash_rl |
RL 훈련용으로 네이티브 SGLang FP8 양자화와 함께 BF16/FP16 체크포인트 로드. --rl-quant-profile 필요. |
runai_streamer |
SSD·공유 파일시스템·객체 스토리지에서 가중치 스트리밍. Loading Models from Object Storage 참고. |
remote |
원격 KV/파일시스템 커넥터에서 텐서 로드. 원격 URI에서 자동 탐지됨. |
remote_instance |
디스크 대신 다른 실행 중인 SGLang 인스턴스("seed")에서 네트워크로 가중치를 가져옴. --remote-instance-weight-loader-* 플래그로 구성. |
모델 로더 추가 설정 (Model loader extra config)
--model-loader-extra-config는 --load-format이 선택한 로더에 전달되는 JSON 문자열을 받습니다.
python -m sglang.launch_server \
--model-path Qwen/Qwen3.6-35B-A3B \
--model-loader-extra-config '{"enable_multithread_load": true, "num_threads": 16}'
| Load format | Key | Description | Default |
|---|---|---|---|
auto / safetensors / pt / npcache |
enable_multithread_load (bool) |
가중치 샤드를 순차 대신 스레드 풀로 읽음. --weight-loader-prefetch-checkpoints 설정 시 기본 비활성(프리페치 스레드와 I/O 오버서브스크립션 방지). 다시 선택하려면 true로 설정. |
true |
auto / safetensors / pt / npcache |
num_threads (int) |
멀티스레드 로딩 활성 시 워커 스레드 수. | 8 |
sharded_state |
pattern (str) |
랭크별 샤드의 파일명 패턴. | model-rank-{rank}-part-{part}.safetensors |
fastsafetensors |
enable_gds (bool) |
GPU Direct Storage 사용. gVisor 샌드박스처럼 호스트가 NVIDIA GPUDirect Storage 커널 드라이버를 제공하지 않으면 false로 설정. |
true |
bitsandbytes |
qlora_adapter_name_or_path (str) |
bitsandbytes 양자화된 base 가중치 위에 적용할 QLoRA 어댑터. | — |
runai_streamer |
distributed, concurrency, memory_limit |
스트리밍 제어. Loading Models from Object Storage 참고. | 링크 페이지 참고 |
가중치 로딩 성능 플래그 (Weight-loading performance flags)
--load-format과 무관하게 safetensors 가중치가 읽히는 방식을 조정하는 최상위 인자들.
| Flag | Description | Default |
|---|---|---|
--download-dir |
Hugging Face 모델 파일을 다운로드·캐시하는 데 사용되는 디렉토리. | HF 기본 |
--weight-loader-disable-mmap |
safetensors 로딩 중 mmap 비활성화. mmap이 느린 파일시스템에서 도움이 될 수 있음. | off |
--weight-loader-prefetch-checkpoints |
로딩 전에 체크포인트 파일을 OS 페이지 캐시로 프리페치. 각 랭크가 샤드의 일부를 프리페치해 공유 파일시스템(NFS/Lustre)의 총 네트워크 I/O를 N×체크포인트에서 1×체크포인트로 줄임. 네트워크 스토리지의 모델에 권장. 활성 시 기본적으로 멀티스레드 safetensors 로딩이 비활성(프리페치 스레드와 I/O 오버서브스크립션 방지). 멀티스레드 로딩을 유지하려면 --model-loader-extra-config에서 enable_multithread_load=true 설정(프리페치가 no-op인 로컬 NVMe에서처럼). |
off |
--weight-loader-prefetch-num-threads |
체크포인트 프리페치용 랭크당 스레드 수. | 4 |
--weight-loader-drop-cache-after-load |
각 샤드를 성공적으로 로드한 후 posix_fadvise(DONTNEED) 호출로 페이지 캐시를 해제. 표준 safetensors와 fastsafetensors 로더에서 지원. |
off |
--custom-weight-loader |
커스텀 가중치 로딩 함수의 import 경로, 예: my_package.weight_load_func. |
— |