使用 Docker 的开发指南

使用 Docker 的开发指南#

在远程主机上设置 VSCode#

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

  1. 在远程主机中，从 Https://code.visualstudio.com/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://code.visualstudio.com/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 extension。

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

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

第一次在开发容器中打开它可能需要更长时间，因为需要 docker pull 和 build。一旦成功，你应该在左下角的状态栏上看到显示你正处于开发容器中的信息：

image

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

image

选项 2. 手动启动容器（高级）#

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

❗️ 关于 RDMA 的注意事项

1. RDMA 需要 `--network host` 和 `--privileged`。如果你不需要 RDMA，可以移除它们，但保留它们也不会造成损害。因此，我们在下面的命令中默认启用这两个标志。
2. 如果使用 RoCE，你可能需要设置 `NCCL_IB_GID_INDEX`，例如：`export NCCL_IB_GID_INDEX=3`。

# 将名称更改为你的名称
docker run -itd --shm-size 32g --gpus all -v <要挂载的卷> --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 仓库。当你更喜欢手动将本地代码更改传输到 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 仓库。由于 SGLang 在开发镜像中以可编辑模式安装，本地代码更改将自动同步到 devcontainer 中。

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/Tunnel 主机 + 开发容器中运行，程序也会在断点处暂停。

性能分析#

# 更改批次大小、输入、输出并添加 `disable-cuda-graph`（以便于分析）
# 例如 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

评估#

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