在 GPU 服务器上用 SGLang 部署 LLM 推理服务

在 GPU 服务器上部署 SGLang：需要准备什么

要在 GPU 服务器上部署 SGLang：先用 uv 安装，或者运行它的 Docker 镜像；再用 sglang serve 在 127.0.0.1:30000 上启动一个 Hugging Face 模型，并设置 API 密钥；然后向 /v1 发送 OpenAI 风格的请求。可以通过 SSH 隧道访问它，或者用 TLS 代理只对外发布 /v1/。NVIDIA GPU 需要支持 CUDA 13 的驱动，也就是 580 系列或更新的版本（NVIDIA 驱动与 CUDA）；AMD MI355X 上则使用 SGLang 的 ROCm 镜像。

如果您下单时在“软件”步骤中选择了 SGLang，它已经连同您选择的模型一起装好；本指南介绍的是如何自行安装和运行。SGLang 与 vLLM、Ollama 和 llama.cpp 的对比，参见 vLLM vs Ollama vs llama.cpp vs SGLang；vLLM 的用法参见推理服务。下文的示例使用我们目录中的两个模型：

这条规则在权重的基础上为 KV 缓存增加 20%，并按 92% 的 GPU 显存计为可用，与我们的模型页面一致；模型页面还会列出所有放得下该模型的服务器。长上下文和大量并发请求需要更多显存。这两个检查点都无需授权即可下载；需要授权的模型则要在环境变量中设置 HF_TOKEN。

SGLang 安装：使用 uv 或 Docker

请以 root 身份运行本指南中的命令。SGLang 需要 Python 3.11 或更高版本（Ubuntu 22.04 自带的是 3.10），因此这里用 uv 把 Python 3.12 安装到 /opt 下，下文创建的服务账户也能读取那里的文件（安装指南）：

nvidia-smi                                         # 表头中的 CUDA Version 应为 13.0 或更高
curl -LsSf https://astral.sh/uv/install.sh | sh     # 然后开一个新终端，让 uv 出现在 PATH 中
export UV_PYTHON_INSTALL_DIR=/opt/uv-python
uv venv --python 3.12 --managed-python /opt/sglang
source /opt/sglang/bin/activate
uv pip install --prerelease=allow sglang
sglang version

请保留 --prerelease=allow：部分依赖只发布了预发布版本，如果不加这个参数，低于 0.12.0 的 uv 版本会在没有任何提示的情况下安装 SGLang 0.5.9。如果使用 Docker，请安装 Docker 和 NVIDIA Container Toolkit（参见容器），并使用具体的发布版本标签，而不是 latest：2026年10月20日核实时，最新版本是 v0.5.22（Docker Hub 标签）。

用 sglang serve 启动服务端

创建 API 密钥，把模型缓存放在 NVMe 磁盘上（参见存储与数据），然后在 tmux 中启动服务端（参见 SSH 访问）。SGLang 会在首次启动时下载模型：

export SGLANG_API_KEY=$(openssl rand -hex 32)
echo "$SGLANG_API_KEY"                    # 记下它，供客户端使用
export HF_HOME=/data/hf

sglang serve --model-path openai/gpt-oss-120b \
  --host 127.0.0.1 --port 30000 --api-key "$SGLANG_API_KEY" \
  --reasoning-parser gpt-oss --tool-call-parser gpt-oss

等待日志中出现 The server is fired up and ready to roll! 这一行。127.0.0.1 和 30000 端口都是默认值，这里明确写了出来，下文的命令则省略不写。较早的 python3 -m sglang.launch_server 接受同样的参数，目前仍然可用，但现在推荐的入口是 sglang serve；sglang serve --help 会列出所有参数（服务器参数）。

使用 Docker 时，服务端会在容器内监听所有网络接口；-p 127.0.0.1:30000:30000 让发布的端口只绑定在主机的回环地址上，因为 Docker 的端口规则会绕过 ufw：

docker run -d --name sglang --restart unless-stopped \
  --gpus all --ipc=host --shm-size 32g \
  -v /data/hf:/root/.cache/huggingface \
  -p 127.0.0.1:30000:30000 \
  lmsysorg/sglang:v0.5.22 \
  sglang serve --model-path openai/gpt-oss-120b --host 0.0.0.0 --port 30000 \
    --api-key "$SGLANG_API_KEY" --reasoning-parser gpt-oss --tool-call-parser gpt-oss
docker logs -f sglang

在服务器上打开第二个终端进行测试，同样要导出这个密钥：

curl -s http://127.0.0.1:30000/v1/models -H "Authorization: Bearer $SGLANG_API_KEY"

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SGLANG_API_KEY" \
  -d '{"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "Say hello in five words."}]}'

model 字段必须与 --model-path 一致，除非您用 --served-model-name 设置了一个更短的名称。任何 OpenAI 客户端都能连接：使用 base_url="http://127.0.0.1:30000/v1"，并把 api_key 设为您的密钥即可。

SGLang 多卡部署：张量并行、专家并行与数据并行

# 把一个模型拆分到 2、4 或 8 块 GPU 上
sglang serve --model-path openai/gpt-oss-120b --tp 2 --api-key "$SGLANG_API_KEY"

# 混合专家（MoE）模型：把专家也分布到各块 GPU 上
sglang serve --model-path deepseek-ai/DeepSeek-R1-0528 --tp 8 --ep 8 \
  --reasoning-parser deepseek-r1 --api-key "$SGLANG_API_KEY"

# 单块 GPU 就能放下的模型：每块 GPU 运行一个副本
sglang serve --model-path openai/gpt-oss-20b --dp-size 8 --api-key "$SGLANG_API_KEY"

• 张量并行（--tp）会拆分每一层，每一步都要在各块 GPU 之间交换数据，因此最能从 NVLink 或 Infinity Fabric 中受益。如果在 PCIe 显卡上启动时报错“peer access is not supported between these two devices”，请加上 --enable-p2p-check。
• 专家并行（--ep）把混合专家模型的各个专家放到不同的 GPU 上。使用默认后端时，它的值不能超过 --tp；DeepEP 及其他 all-to-all 后端则要求两者相等（专家并行）。按我们的规则，DeepSeek-R1-0528 约需 827 GB 显存；SGLang 的 Cookbook 在 8× H200 或 8× B200 上运行它的 FP8 权重。
• 数据并行（--dp-size）运行多个模型副本，统一通过一个端口对外提供服务。SGLang 的调优指南建议，在显存允许时优先用它来提高吞吐量；更大规模的部署则推荐使用其 Model Gateway。

拓扑检查和互连测试参见多 GPU。

显存设置、FP8 与显存不足（OOM）错误

启动时，SGLang 会从每块 GPU 的显存中预留一个固定比例（--mem-fraction-static），用于存放权重和 KV 缓存池；其余显存则留给激活值和 CUDA Graph 缓冲区。服务端就绪之前输出的那行日志会显示 max_total_num_tokens（缓存池能容纳的 token 数）和 available_gpu_mem：SGLang 的调优指南建议让剩余显存保持在 5–8 GB，如果剩得更多，就调高这个比例。

相比加载时再转换，SGLang 更推荐使用预量化的检查点：直接加载 Qwen 官方的 Qwen/Qwen3.8-27B-FP8，不要加 --quantization；对于已经量化过的检查点，例如 gpt-oss-120b（MXFP4）或 DeepSeek-R1-0528（FP8），也绝不要加这个参数（量化）。FP8 KV 缓存只有在注意力后端支持它时才会快（量化 KV 缓存）。Qwen3.8 27B 是混合架构模型，另有一组显存相关参数（--mamba-*）：它的 Cookbook 页面给出了适用于 H200 和 RTX PRO 6000 的完整命令。“CUDA error: illegal memory access”报错有时其实是显存不足的变相表现（故障排查）。

SGLang OpenAI 接口：结构化输出、工具调用与推理内容

服务端在 /v1 下提供 OpenAI 的 Chat Completions 和 Completions API，另有一个兼容 Anthropic 的 /v1/messages 接口。用对应的推理解析器启动推理模型后，推理过程会放在 reasoning_content 中，与 content 中的回答分开；加上工具调用解析器后，工具调用会以结构化的 tool_calls 返回，而不是原始文本。请使用各模型 Cookbook 页面中指定的解析器：

结构化输出会把回答约束为符合 JSON schema、正则表达式或 EBNF 语法的格式；默认后端是 XGrammar：

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" -H "Authorization: Bearer $SGLANG_API_KEY" \
  -d '{"model": "openai/gpt-oss-120b",
       "messages": [{"role": "user", "content": "Capital of France and its population, as JSON."}],
       "response_format": {"type": "json_schema", "json_schema": {"name": "city", "schema": {
         "type": "object",
         "properties": {"name": {"type": "string"}, "population": {"type": "integer"}},
         "required": ["name", "population"]}}}}'

SGLang 建议同时在提示词中写明所需的格式。详情参见：结构化输出、工具解析器、推理解析器。

在 AMD MI355X 上部署 SGLang

每块 MI355X 配备 288 GB 显存。在这款 GPU 上，SGLang 的 AMD 页面推荐使用 Docker 和预构建的 ROCm 镜像；主机上只需要 AMD 内核驱动（参见 MI355X 上的 ROCm）。镜像标签中写明了发布版本、ROCm 版本和 GPU 系列，其中 mi35x 对应 gfx950。v0.5.22 的发布说明列出的是 v0.5.22-rocm10-mi35x；Docker Hub 上还有基于 ROCm 7.2 的构建（-rocm720-mi35x、-rocm724-mi35x）：如果容器看不到 GPU，请选择与主机上 ROCm 版本（amd-smi version）最接近的构建。

echo 0 > /proc/sys/kernel/numa_balancing      # AMD 页面的建议；重启后失效
docker run -d --name sglang --restart unless-stopped \
  --device=/dev/kfd --device=/dev/dri --group-add video \
  --ipc=host --shm-size 16g \
  --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
  -v /data/hf:/root/.cache/huggingface \
  -e SGLANG_USE_AITER=0 \
  -p 127.0.0.1:30000:30000 \
  lmsysorg/sglang:v0.5.22-rocm10-mi35x \
  python3 -m sglang.launch_server --model-path openai/gpt-oss-120b \
    --host 0.0.0.0 --port 30000 --api-key "$SGLANG_API_KEY" \
    --reasoning-parser gpt-oss --tool-call-parser gpt-oss

该镜像默认启用 AMD 的 AITER 内核（SGLANG_USE_AITER=1）。在 MI355X 上运行 gpt-oss 时，GPT-OSS Cookbook 会关闭这些内核；其他模型请保持默认设置，除非其 Cookbook 页面另有说明。AMD 页面中的 --network=host 和 --privileged 只在使用 RDMA 时才需要，这里没有加上。--tp 和 --ep 的用法与 NVIDIA 上相同。我们的模型页面只为已确认支持 ROCm 的模型提供在 MI355X 上运行 SGLang 的选项：gpt-oss-20b、gpt-oss-120b 和 DeepSeek-R1-0528。

将 SGLang 作为系统服务运行并安全访问

要让 SGLang 在崩溃或系统重启后自动恢复运行，请用 systemd 以非特权用户身份运行它（使用 Docker 时，--restart unless-stopped 就能做到这一点）。请先停掉在 tmux 中运行的那个实例。密钥保存在仅 root 可读的文件中，由 systemd 把它代入 ${SGLANG_API_KEY}（systemd.service）：

useradd --system --create-home --home-dir /var/lib/sglang --shell /usr/sbin/nologin sglang
mkdir -p /data/hf && chown -R sglang:sglang /data/hf
install -m 600 /dev/null /etc/sglang.env
echo "SGLANG_API_KEY=$SGLANG_API_KEY" > /etc/sglang.env    # 即上文创建的密钥

cat > /etc/systemd/system/sglang.service <<'EOF'
[Unit]
Description=SGLang server
Wants=network-online.target
After=network-online.target

[Service]
User=sglang
EnvironmentFile=/etc/sglang.env
Environment=HF_HOME=/data/hf
ExecStart=/opt/sglang/bin/sglang serve --model-path openai/gpt-oss-120b \
  --host 127.0.0.1 --port 30000 --api-key ${SGLANG_API_KEY} \
  --reasoning-parser gpt-oss --tool-call-parser gpt-oss --enable-metrics
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable --now sglang
journalctl -u sglang -f

SSH 隧道：适合个人和小团队

# 在您自己的电脑上执行；之后 API 就在 http://localhost:30000/v1
ssh -N -L 30000:127.0.0.1:30000 gpu1

带 TLS 的 Caddy：适合公开接口

把一个 DNS 名称指向服务器，从官方仓库安装 Caddy，并且只转发 /v1/。与 vLLM 指南中一样，Caddy 会自动获取并续期证书：

cat > /etc/caddy/Caddyfile <<'EOF'
llm.example.com {
    handle /v1/* {
        reverse_proxy 127.0.0.1:30000
    }
    handle {
        respond 404
    }
}
EOF
systemctl reload caddy
ufw allow 80,443/tcp

监控与升级 SGLang

curl -s http://127.0.0.1:30000/metrics | grep -E '^sglang:(num_running_reqs|num_queue_reqs|token_usage|cache_hit_rate)'
journalctl -u sglang -f | grep "Decode batch"      # 日志行中的 #running-req、token usage、#queue-req
nvidia-smi --query-gpu=index,utilization.gpu,memory.used,memory.total --format=csv -l 5
watch -n 2 amd-smi monitor                         # MI355X

/metrics 需要启用 --enable-metrics（生产环境指标）。即使在空闲时，GPU 显存看上去也是满的：权重和 KV 缓存池在启动时就已预留。应该关注 token_usage（KV 缓存池中已使用的比例）和排队情况：如果请求一直在排队等待，而使用率始终高于 0.9，就说明瓶颈在于缓存池（增加 GPU 或改用 FP8 KV 缓存会有帮助）。

升级之前，请先阅读发布说明：0.5.20 起不再支持 CUDA 12，0.5.22 要求 Python 3.11 或更高版本。

uv pip install --python /opt/sglang/bin/python --upgrade --prerelease=allow sglang
/opt/sglang/bin/sglang version
systemctl restart sglang

如果想固定在已知版本，请把 --upgrade --prerelease=allow sglang 替换为 --prerelease=allow "sglang==0.5.22"。使用 Docker 时，先删除容器（docker rm -f sglang），再用新标签重新启动容器。/data/hf 中的模型在升级后依然保留，但如果租期结束时没有续费，模型就无法保留：届时磁盘会被清空。