Docker로 개발하기

Docker로 개발하기 (Development Guide Using Docker)

SGLang을 직접 수정해서 개발하거나 디버깅해야 할 때, 온갖 의존성을 로컬에 설치하기보다는 도커 컨테이너 안에서 작업하는 게 훨씬 편해요. 이 페이지는 VSCode 원격 터널부터 dev container, 수동 컨테이너 실행, 디버거, 프로파일링까지 SGLang을 도커로 개발하는 전체 흐름을 강사 목소리로 안내해 드릴게요. 명령어와 코드는 원문 그대로 보존했어요.

출처: 공식문서 - Development Guide Using Docker

원격 호스트에서 VSCode 설정하기

(선택 사항 — sglang dev container를 로컬에서 실행할 생각이라면 이 단계는 건너뛰어도 돼요.)

원격 호스트에서 VSCode에서 code를 다운로드하고 쉘에서 code tunnel을 실행하세요.

예시

wget https://vscode.download.prss.microsoft.com/dbazure/download/stable/fabdb6a30b49f79a7aba0f2ad9df9b399473380f/vscode_cli_alpine_x64_cli.tar.gz
tar xf vscode_cli_alpine_x64_cli.tar.gz

# https://code.visualstudio.com/docs/remote/tunnels
./code tunnel

로컬 머신에서 VSCode의 F1을 누르고 "Remote Tunnels: Connect to Tunnel"를 선택하세요.

Docker 컨테이너 설정하기

옵션 1. VSCode에서 기본 dev container를 자동으로 사용하기

sglang 레포지토리 루트 폴더에는 .devcontainer 폴더가 있어서, VSCode가 dev container 안에서 자동으로 시작되게 해 줘요. 이 VSCode 확장에 대해 더 자세히 알고 싶다면 VSCode 공식 문서 Developing inside a Container를 읽어보세요.

Figure 1: VSCode 공식 문서 Developing inside a Container에서 가져온 다이어그램.

이걸 활성화하려면 다음만 하면 돼요.

Visual Studio Code를 실행하고 VSCode dev container 확장을 설치하세요.
F1을 누르고 "Dev Container: Open Folder in Container."를 입력해 선택하세요.
머신에 있는 sglang 로컬 레포 경로를 입력하고 엔터를 누르세요.

dev container에서 처음 열 때는 docker pull과 build 때문에 시간이 더 걸릴 수 있어요. 성공하면 화면 왼쪽 아래 상태 표시줄에 dev container 안에 있다는 표시가 떠요.

이제 VSCode 터미널에서 sglang.launch_server를 실행하거나 F5로 디버깅을 시작하면, sglang 서버가 dev container 안에서 여러분의 모든 로컬 변경 사항이 자동 반영된 채로 시작돼요.

옵션 2. 컨테이너를 수동으로 시작하기 (고급)

다음 시작 명령은 SGLang 팀이 내부 개발용으로 쓰는 예시예요. 특히 모델 가중치 다운로드를 위해 디렉터리 매핑을 필요에 따라 수정하거나 추가해도 되는데, 이렇게 하면 서로 다른 도커 컨테이너가 같은 모델을 반복 다운로드하는 걸 막을 수 있어요.

❗️ RDMA에 대한 주의

--network host와 --privileged는 RDMA가 필요로 해요. RDMA가 필요 없다면 빼도 되지만, 있어도 해롭진 않아요. 그래서 아래 명령어에서 이 두 플래그를 기본으로 켜둔 거예요.
RoCE를 쓴다면 NCCL_IB_GID_INDEX를 설정해야 할 수 있어요. 예를 들어 export NCCL_IB_GID_INDEX=3.

# Change the name to yours
docker run -itd --shm-size 32g --gpus all -v <volumes-to-mount> --ipc=host --network=host --privileged --name sglang_dev lmsysorg/sglang:dev /bin/zsh
docker exec -it sglang_dev /bin/zsh

마운트하면 유용한 볼륨은 다음과 같아요.

Huggingface 모델 캐시: 모델 캐시를 마운트하면 도커가 재시작될 때마다 다시 다운로드하는 걸 피할 수 있어요. Linux에서 기본 위치는 ~/.cache/huggingface/예요.
SGLang 레포지토리: SGLang 로컬 레포의 코드 변경 사항이 .devcontainer에 자동으로 동기화돼요.

예시 1: 로컬 캐시 폴더 /opt/dlami/nvme/.cache는 마운트하되 SGLang 레포는 마운트하지 않는 경우예요. 로컬 코드 변경 사항을 직접 devcontainer로 옮기는 걸 선호할 때 쓰세요.

docker run -itd --shm-size 32g --gpus all -v /opt/dlami/nvme/.cache:/root/.cache --ipc=host --network=host --privileged --name sglang_zhyncs lmsysorg/sglang:dev /bin/zsh
docker exec -it sglang_zhyncs /bin/zsh

예시 2: HuggingFace 캐시와 로컬 SGLang 레포를 둘 다 마운트하는 경우예요. dev 이미지에서 SGLang이 editable 모드로 설치되어 있어 로컬 코드 변경 사항이 dev container에 자동 동기화돼요.

docker run -itd --shm-size 32g --gpus all -v $HOME/.cache/huggingface/:/root/.cache/huggingface -v $HOME/src/sglang:/sgl-workspace/sglang --ipc=host --network=host --privileged --name sglang_zhyncs lmsysorg/sglang:dev /bin/zsh
docker exec -it sglang_zhyncs /bin/zsh

VSCode 디버거로 SGLang 디버깅하기

(없으면 만들어서) VSCode에서 launch.json을 여세요.
다음 설정을 추가하고 저장하세요. 필요에 따라 스크립트를 수정해 다른 파라미터를 적용하거나 다른 프로그램(예: 기준 벤치마크 스크립트)을 디버깅할 수 있어요.

  {
     "version": "0.2.0",
     "configurations": [
         {
             "name": "Python Debugger: launch_server",
             "type": "debugpy",
             "request": "launch",
             "module": "sglang.launch_server",
             "console": "integratedTerminal",
             "args": [
                 "--model-path", "meta-llama/Llama-3.2-1B",
                 "--host", "0.0.0.0",
                 "--port", "30000",
                 "--trust-remote-code",
             ],
             "justMyCode": false
         }
     ]
 }

"F5"를 눌러 시작하세요. 프로그램이 원격 SSH/Tunnel 호스트 + dev container에서 실행되고 있더라도 VSCode 디버거는 브레이크포인트에서 확실히 멈추게 해 줘요.

프로파일링 (Profile)

# Change batch size, input, output and add `disable-cuda-graph` (for easier analysis)
# e.g. DeepSeek V3
nsys profile -o deepseek_v3 python3 -m sglang.bench_one_batch --batch-size 1 --input 128 --output 256 --model deepseek-ai/DeepSeek-V3 --trust-remote-code --tp 8 --disable-cuda-graph

평가 (Evaluation)

# e.g. gsm8k 8 shot
python3 benchmark/gsm8k/bench_sglang.py --num-questions 2000 --parallel 2000 --num-shots 8

더 알아보기 (Learn more)

Kubernetes에 배포하기 — LWS로 쿠버네티스에 분산 배포하기
벤치마크와 프로파일링 — 성능 측정과 프로파일링 도구