使用 Docker 进行开发指南#

在远程主机上配置 VSCode#

(可选 - 如果你计划在本地运行 sglang 开发容器，可以跳过此步骤)

在远程主机上，从 https://vscode.js.cn/docs/?dv=linux64cli 下载 code，并在 shell 中运行 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://vscode.js.cn/docs/remote/tunnels
./code tunnel

在本地机器上，在 VSCode 中按 F1 并选择 “Remote Tunnels: Connect to Tunnel”。

配置 Docker 容器#

选项 1. 使用 VSCode 自动启动默认开发容器 (dev container)#

sglang 仓库根目录中有一个 .devcontainer 文件夹，允许 VSCode 在开发容器内自动启动。你可以在 VSCode 官方文档在容器内开发中阅读更多关于此扩展的信息。 (图 1：来自 VSCode 官方文档在容器内开发的示意图。)

要启用此功能，你只需要：

启动 Visual Studio Code 并安装 VSCode dev container 扩展。
按 F1，输入并选择 “Dev Container: Open Folder in Container”。
输入你机器上的 sglang 本地仓库路径并按回车。

第一次在开发容器中打开可能需要较长时间，因为需要进行 docker pull 和 build。成功后，你应该会在左下角的状态栏看到显示你正处于开发容器中。

现在，当你在 VSCode 终端运行 sglang.launch_server 或按 F5 开始调试时，sglang 服务器将在开发容器中启动，并自动应用你所有的本地更改。

选项 2. 手动启动容器 (高级)#

以下启动命令是 SGLang 团队进行内部开发的示例。你可以根据需要修改或添加目录映射，特别是针对模型权重的下载路径，以防止不同的 Docker 容器重复下载。

❗️ 关于 RDMA 的说明

1. `--network host` and `--privileged` are required by RDMA. If you don't need RDMA, you can remove them but keeping them there does not harm. Thus, we enable these two flags by default in the commands below.
2. You may need to set `NCCL_IB_GID_INDEX` if you are using RoCE, for example: `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 模型缓存：挂载模型缓存可以避免每次 docker 重启时重新下载。Linux 上的默认位置是 ~/.cache/huggingface/。
SGLang 仓库：SGLang 本地仓库中的代码更改将自动同步到 .devcontainer。

示例 1：挂载本地缓存文件夹 /opt/dlami/nvme/.cache 但不挂载 SGLang 仓库。当你更倾向于手动将本地代码更改传输到开发容器时使用此方式。

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 仓库。由于 SGLang 在开发镜像中是以可编辑模式 (editable mode) 安装的，本地代码更改会自动同步到开发容器。

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 主机 + 开发容器中，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

使用 Docker 的开发指南

目录