5. 部署与运维

这是什么：部署与运维 = 把服务当成一台要 7×24 值班的生产机器：探活、看指标、多卡扩容、处理故障。

为什么用：上一章调完参数，服务在本机跑得好好的。可上生产之后进程会挂、显存会爆、流量会涨，没人盯着就等着用户来投诉。

如何用：本章先讲四个运维接口，再讲多卡怎么切，最后给一张常见故障的速查表。

5.1 四个运维接口

接口	用途	典型用法
`GET /health`	探活	负载均衡器、K8s liveness probe
`GET /version`	版本号	确认跑的是哪个版本
`GET /v1/models`	服务中的模型	校验 `--served-model-name`
`GET /load`	当前负载	看排队情况

/health 正常返回 200，引擎挂了返回 503：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8000/health

你会看到（示意）：

在 K8s 里就把 /health 挂成 liveness probe，探活失败三次就重启容器：

livenessProbe:
  httpGet:
    path: /health
    port: 8000
  periodSeconds: 10
  failureThreshold: 3

服务日志默认打在 stdout。嫌信息太吵可以用环境变量 VLLM_LOGGING_LEVEL=WARNING 压低级别，排障时再调回 INFO 或 DEBUG。

5.2 Prometheus 指标

/metrics 默认就开着，不用额外参数，直接抓：

curl -s http://localhost:8000/metrics | grep vllm:num_requests_running

你会看到（示意）：

vllm:num_requests_running{model_name="Qwen/Qwen3-8B"} 8.0
vllm:num_requests_waiting{model_name="Qwen/Qwen3-8B"} 3.0
vllm:kv_cache_usage_perc{model_name="Qwen/Qwen3-8B"} 0.42

盯这几个就够：

指标	看什么	报警信号
`vllm:num_requests_waiting`	排队数	持续大于 0 说明处理不过来
`vllm:kv_cache_usage_perc`	KV cache 占用	接近 1 说明显存吃紧
`vllm:time_to_first_token_seconds`	首字延迟	突然飙升
`vllm:request_success_total`	成功 / 失败请求数	`finished_reason="error"` 在涨

嫌日志吵可以加 --disable-log-stats 关掉每 5 秒一次的统计打印——但注意它会连 Prometheus 指标一起关掉。

5.3 多卡

模型塞不进一张卡时，用张量并行（把权重横向切到多张卡）和流水线并行（把网络层竖着切）。

# 4 张卡跑一个模型副本
vllm serve Qwen/Qwen3-8B --tensor-parallel-size 4

你会看到（示意）：

INFO [distributed.py:538] Started engine core with 4 workers
INFO [gpu_model_runner.py:2412] GPU KV cache size: 760,320 tokens

选型原则：

场景	建议
单机多卡，模型能塞进单机	张量并行 `--tensor-parallel-size N`
单机多卡但卡数除不尽模型层数	流水线并行 `--pipeline-parallel-size N`
多机	张量并行 = 每机卡数，流水线并行 = 机器数，配 `--distributed-executor-backend ray`

卡间通信靠 NCCL。有 NVLink 的机器差距很明显，没有的话多卡收益会被通信拖慢。

5.4 用 Docker 跑生产

docker run -d --name vllm \
  --runtime nvidia --gpus all \
  --ipc=host --shm-size=16g \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  --restart unless-stopped \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen3-8B --served-model-name qwen3

你会看到（示意）：

a3f1c2e4b5d6

关键几项：--gpus all 分配显卡；--ipc=host / --shm-size 给足共享内存（多卡进程间要传张量，共享内存不够会报错）；-v ~/.cache/huggingface 复用模型缓存；--restart unless-stopped 容器挂了自动拉起。

5.5 常见故障速查表

现象	原因	处理
启动就 OOM	显存不够	调小 `--gpu-memory-utilization`、换量化模型、减小 `--max-model-len`
`No available memory for the cache blocks`	KV cache 一块都放不下	降 `--gpu-memory-utilization` 给权重留够，再调上下文长度
请求排队不动	并发已满	加卡，或调小 `--max-model-len` 提并发
CUDA out of memory	多进程抢同一张卡	用 `--device-ids` 或 `CUDA_VISIBLE_DEVICES` 分卡
NCCL 初始化失败	卡间通信不通	检查 NVLink / 网卡，确认都在同一台机器

排查顺序永远是：先看启动日志的 GPU KV cache size，再看 /metrics 里的队列长度和 KV cache 占用。

动手改

写一个 check.sh，每 10 秒 curl 一次 /health，连挂 3 次就退出报警
抓一次 /metrics，把 vllm:num_requests_running、vllm:kv_cache_usage_perc、vllm:time_to_first_token_seconds 三条存到文件里
用 --tensor-parallel-size 2 起一个多卡实例，对比单卡时的 GPU KV cache size 和并发能力

小结

/health 返回 200 就健康，503 就是引擎挂了
/metrics 默认开着，重点盯等待队列、KV cache 占用、首字延迟
--disable-log-stats 会连 Prometheus 指标一起关
模型太大就上张量并行，单机内优先张量并行
Docker 部署记住 --gpus all 和 --ipc=host

下一章：综合练习 🐸