编程 vLLM/SGLang 多机部署 4 个启动坑：v0.11 全归约变量回归、qGPU OOM、KV Cache 超限与 CFS 慢加载

2026-10-09 00:04:10

TI-ONE 自定义镜像部署 LLM：vLLM/SGLang 启动命令与 4 个启动坑

来源：腾讯云 TI-ONE 文档《部署自定义 LLM 大模型（用户自定义推理镜像）》

部署方式选择：单机、多机、qGPU 先分清

镜像固定到带版本号的稳定版：vllm/vllm-openai:v0.11.0、lmsysorg/sglang:v0.5.5。不要用 latest、dev、main、nightly，否则重启时镜像漂移。

单机：直接按下面的 vLLM / SGLang 启动命令跑。
多机：vLLM 需要先起 Ray，再在 head 节点执行 vllm serve；SGLang 用 --dist-init-addr、--nnodes、--node-rank。
TP 填总卡数。例如两机 16 卡，TP=16。MASTER_ADDR、RANK 由平台注入。
小于 1 卡（qGPU）：先看 CUDA 版本，见坑 2。

启动命令：vLLM 与 SGLang

vLLM 单机：

vllm serve /data/model \
  --port 8501 \
  --host 0.0.0.0 \
  --served-model-name $SERVED_MODEL_NAME \
  -tp $TP

SGLang 单机：

python3 -m sglang.launch_server \
  --model-path /data/model \
  --host 0.0.0.0 \
  --port 8501 \
  --enable-metrics \
  --tp $TP

--enable-metrics 默认关闭，需要手动打开。

多机 vLLM，先在所有节点起 Ray。head 节点：

ray start --head --port 6700 --include-dashboard false --disable-usage-stats

其余节点：

ray start --address $MASTER_ADDR:6700 --block

Ray 起来后，再在 head 上执行 vllm serve。

多机 SGLang 直接加分布式参数：

python3 -m sglang.launch_server \
  --model-path /data/model \
  --host 0.0.0.0 \
  --port 8501 \
  --enable-metrics \
  --tp $TP \
  --dist-init-addr $MASTER_ADDR:$MASTER_PORT \
  --nnodes $WORLD_SIZE \
  --node-rank $RANK

四个启动报错 / 慢加载排障

坑 1：vLLM v0.11.0 非整机多机，显卡序号异常

vLLM v0.11.0 把环境变量 VLLM_ALLREDUCE_USE_SYMM_MEM 的默认值改成了 1。非整机多机部署时，会导致获取显卡序号异常。规避方式是显式设为 0：

export VLLM_ALLREDUCE_USE_SYMM_MEM=0

坑 2：qGPU 小于 1 卡，CUDA>12.2 在 profiling 阶段 OOM

小于 1 卡（qGPU）时，vLLM 镜像里 CUDA>12.2 会在显存 profiling 阶段统计异常，并以 CUDA OOM 退出。处理办法是用 cuda-compat-12-2（535.216.01-0ubuntu1）降级容器 CUDA runtime，并设置：

export LD_LIBRARY_PATH=/usr/local/cuda-12.2/compat

如果网络拉不到，就先下载 deb 包，再传到 COS/CFS。

坑 3：权重放得下仍 OOM，先调上下文长度

显存放得下权重，仍然 OOM，通常是因为 KV Cache 与上下文长度挂钩。开源模型默认上下文常是 256K/1M，按需调小：

vLLM：--max-model-len 16384
SGLang：--context-length 16384

坑 4：从 CFS/NFS 加载权重慢

从 CFS/NFS 加载权重慢，是因为默认加载逻辑按本地存储优化。可换加载策略：

vLLM v0.10.2+：--safetensors-load-strategy eager
SGLang v0.5.1+：--weight-loader-disable-mmap

这两个选项会增大内存占用，容器内存建议≥显存。如果频繁重启，可以用平台文件预加载，走本地盘加载。