체크포인트 엔진 통합

체크포인트 엔진 통합 (Checkpoint Engine Integration)

SGLang의 체크포인트 엔진(chECKPOINT engine) 통합은 분산 체크포인트 로딩 시스템으로 모델 가중치를 효율적으로 불러오는 방법을 제공합니다. 여러 프로세스와 노드에 걸쳐 가중치 로딩을 병렬화해, 특히 대형 모델과 멀티 노드 환경에서 모델 로딩 시간을 크게 줄여줘요.

출처: 문서

본문

개요 (Overview)

체크포인트 엔진 통합을 통해 SGLang은:

• 여러 프로세스로 가중치를 병렬 로딩
• 여러 노드에 가중치 로딩을 분산해 유효 디스크 대역폭 증가
• CUDA graph 캡처 같은 다른 초기화 작업과 가중치 로딩을 겹침(overlap)
• 단일 노드와 멀티 노드 배포 모두 지원

설치 (Installation)

먼저 체크포인트 엔진 패키지를 설치하세요:

pip install 'checkpoint-engine[p2p]'

아키텍처 (Architecture)

시스템은 두 가지 주요 컴포넌트로 구성됩니다:

1. SGLang 서버: --checkpoint-engine-wait-weights-before-ready 플래그로 실행되어, 준비(ready) 전에 가중치를 기다림
2. 체크포인트 엔진 워커 (Checkpoint Engine Workers): (torchrun이 관리하는) 별도 프로세스로 모델 가중치를 로드·배포

체크포인트 엔진은 파라미터 서버 아키텍처를 사용하며 다음을 지원합니다:

• Broadcast 모드: 로딩 프로세스에서 추론 프로세스로 가중치를 브로드캐스트
• P2P 모드: 프로세스 간 직접 피어투피어 가중치 전송
• All 모드: broadcast와 P2P 방식의 조합

사용 예시 (Usage Examples)

단일 노드 설정 (Single Node Setup)

터미널 1 — SGLang 서버 시작:

python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --tp 8 \
    --load-format dummy \
    --checkpoint-engine-wait-weights-before-ready

터미널 2 — 체크포인트 엔진 실행:

sglang 엔트리포인트 사용:

python -m sglang.srt.checkpoint_engine.update \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

torchrun 직접 사용:

torchrun --nproc-per-node 8 \
    examples/checkpoint_engine/update.py \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

멀티 노드 설정 (Multi-Node Setup, 2 Nodes)

노드 0 (Node 0):

SGLang 서버 시작:

python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --tp 8 \
    --load-format dummy \
    --checkpoint-engine-wait-weights-before-ready \
    --host [IP]

체크포인트 엔진 실행:

sglang 엔트리포인트 사용(권장):

python -m sglang.srt.checkpoint_engine.update \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

torchrun 직접 사용:

torchrun --nproc-per-node 8 \
    --nnodes 2 \
    --node-rank 0 \
    --master-addr [IP] \
    --master-port 29500 \
    examples/checkpoint_engine/update.py \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

노드 1 (Node 1):

SGLang 서버 시작:

python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --tp 8 \
    --load-format dummy \
    --checkpoint-engine-wait-weights-before-ready \
    --host [IP]

체크포인트 엔진 실행:

sglang 엔트리포인트 사용(권장):

python -m sglang.srt.checkpoint_engine.update \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

torchrun 직접 사용:

torchrun --nproc-per-node 8 \
    --nnodes 2 \
    --node-rank 1 \
    --master-addr [IP] \
    --master-port 29500 \
    examples/checkpoint_engine/update.py \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 8

텐서 병렬(TP=16) 멀티 노드 설정

노드 0 (Node 0):

SGLang 서버 시작:

python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --tp 8 \
    --load-format dummy \
    --checkpoint-engine-wait-weights-before-ready \
    --host [IP] \
    --dist-init-addr [IP]:9120 \
    --nnodes 2 \
    --node-rank 0

체크포인트 엔진 실행:

sglang 엔트리포인트 사용(권장):

python -m sglang.srt.checkpoint_engine.update \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 16

torchrun 직접 사용:

torchrun --nproc-per-node 8 \
    --nnodes 2 \
    --node-rank 0 \
    --master-addr [IP] \
    --master-port 29500 \
    examples/checkpoint_engine/update.py \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 16

노드 1 (Node 1):

SGLang 서버 시작:

python -m sglang.launch_server \
    --model-path Qwen/Qwen3-8B \
    --tp 8 \
    --load-format dummy \
    --checkpoint-engine-wait-weights-before-ready \
    --host [IP] \
    --dist-init-addr [IP]:9120 \
    --nnodes 2 \
    --node-rank 1

체크포인트 엔진 실행:

sglang 엔트리포인트 사용(권장):

python -m sglang.srt.checkpoint_engine.update \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 16

torchrun 직접 사용:

torchrun --nproc-per-node 8 \
    --nnodes 2 \
    --node-rank 1 \
    --master-addr [IP] \
    --master-port 29500 \
    examples/checkpoint_engine/update.py \
    --update-method broadcast \
    --checkpoint-path /path/to/Qwen/Qwen3-8B/ \
    --inference-parallel-size 16

구성 옵션 (Configuration Options)

SGLang 서버 옵션

• --load-format dummy: 초기 로딩에 dummy 포맷 사용(다른 작업과 겹침 가능)
• --checkpoint-engine-wait-weights-before-ready: 준비되기 전에 체크포인트 엔진이 가중치를 제공할 때까지 대기
• --host: 멀티 노드 환경용 호스트 주소
• --dist-init-addr: 텐서 병렬을 위한 분산 초기화 주소

체크포인트 엔진 옵션

• --update-method: 가중치 업데이트 방식 (broadcast, p2p, or all)
• --checkpoint-path: 모델 체크포인트 디렉토리 경로
• --inference-parallel-size: 추론 병렬 프로세스 수
• --endpoint: SGLang 서버 엔드포인트 (기본: http://localhost:19730)
• --checkpoint-name: 체크포인트 이름 (기본: my-checkpoint-iter-0)
• --save-metas-file: 체크포인트 메타데이터를 저장할 파일
• --load-metas-file: 체크포인트 메타데이터를 로드할 파일
• --uds: 통신용 Unix domain socket 경로
• --weight-version: 가중치 버전 식별자

성능 이점 (Performance Benefits)

체크포인트 엔진은 두 가지 주요 측면에서 상당한 시간 절약을 제공합니다:

1. 멀티 노드 로딩 (Multi-node Loading): 각 노드는 디스크에서 가중치의 일부만 로드해 유효 디스크 대역폭을 효과적으로 늘립니다. 참여 노드가 많을수록 가속이 커져요. 예비 테스트에 따르면 H20-3e에서 두 노드로 DeepSeek-R1을 로드할 때 20초 가속이 확인되었습니다.

2. 단일 프로세스 최적화 (Single Process Optimization): dummy 포맷을 사용하면 디스크→CPU 전송을 CUDA graph 캡처와 다른 초기화 작업과 겹칠 수 있어 추가적인 시간 절약이 됩니다.

문제 해결 (Troubleshooting)

• 체크포인트 엔진 패키지 설치 확인: pip install 'checkpoint-engine[p2p]'
• 멀티 노드 환경에서 노드 간 네트워크 연결 확인
• 체크포인트 경로에 유효한 모델 파일이 있는지 확인
• SGLang 서버와 체크포인트 엔진 간 연결 오류 로그 모니터링
• 디버깅이 필요하면 --sleep-time 파라미터로 지연 추가

참고자료 (References)

• Checkpoint Engine Repository

더 알아보기 (Learn more)

• Checkpoint Engine 저장소