使用 Docker 的开发指南

使用 Docker 的开发指南#

在远程主机上设置 VSCode#

(可选 - 如果您打算在本地运行 sglang dev 容器，可以跳过此步骤)

  1. 在远程主机上，从 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

  1. 在您的本地机器上，在 VSCode 中按下 F1，然后选择 “Remote Tunnels: Connect to Tunnel”。

设置 Docker 容器#

选项 1. 从 VSCode 自动使用默认开发容器#

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

要启用此功能，您只需

  1. 启动 Visual Studio Code 并安装 VSCode dev container 扩展。

  2. 按下 F1，输入并选择 “Dev Container: Open Folder in Container。”

  3. 输入您机器上的 sglang 本地仓库路径并按回车。

首次在开发容器中打开可能需要更长时间，因为需要进行 docker 拉取和构建。成功后，您应该在左下角的状态栏上看到您正在一个开发容器中

image

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

image

选项 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

一些有用的挂载卷包括

  1. Huggingface 模型缓存：挂载模型缓存可以避免每次 docker 重启时重新下载。Linux 上的默认位置是 ~/.cache/huggingface/。

  2. 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 在开发镜像中以可编辑模式安装，本地代码更改将自动同步到开发容器。

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#

  1. (如果不存在则创建) 在 VSCode 中打开 launch.json。

  2. 添加以下配置并保存。请注意，您可以根据需要编辑脚本以应用不同的参数或调试不同的程序（例如基准测试脚本）。

      {
     "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
         }
     ]
 }

  3. 按下 “F5” 启动。VSCode 调试器将确保程序即使在远程 SSH/隧道主机 + 开发容器中运行也能在断点处暂停。

性能分析#

# 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

评估#

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