logo

单机单卡开源大模型推理服务上线与回滚实操指南

作者:KAKAKA2026.11.18 11:42浏览量:0

简介:本文以 vLLM 在单台服务器单张 GPU 上部署推理服务为例,讲解显存与带宽估算、版本锁定、服务启动、健康检查、验收指标、监控告警阈值和回滚步骤。照做可得到一套可上线、可回退的部署流程,并在上线前完成自检。

一、适用范围与版本

本文以 vLLM 为例。它提供兼容 OpenAI 接口的服务进程。其他推理框架的思路相同,但启动参数和指标名称不同,需要查阅对应文档。

本文的前提如下:

  • 单台服务器,安装一张 40 GB 或 48 GB 显存的 NVIDIA GPU。
  • 推理进程只监听本机 127.0.0.1:8000。外部请求经过前置网关,由网关负责 TLS 证书和访问控制。
  • 模型已从发布方获得权重文件和 SHA256 哈希清单。

不适用的场景包括:多卡张量并行、多机部署、同一台机器运行多个模型。使用量化模型时,显存和性能数据都需要重新压测。

1.1 版本要求

组件 要求 说明
操作系统 Ubuntu 22.04 或 24.04 LTS 与 NVIDIA 驱动官方支持列表一致
NVIDIA 驱动 满足所选 CUDA 版本的最低驱动要求 以 vLLM 发布说明中的 CUDA 版本为准
Python 所选 vLLM 版本官方支持的版本 不要使用系统中未经验证的版本
vLLM 压测通过的固定版本,例如 vllm==<版本号> 写入锁定文件,禁止随意升级

版本号在部署前写入 /opt/llm/requirements.lock。升级 vLLM 时,要重新执行压测和验收。

二、资源估算

2.1 显存

推理时的显存占用由三部分组成:

  1. 模型权重:参数量乘以每个参数的字节数。半精度(float16)每个参数占 2 字节。
  2. KV cache:随并发数和上下文长度增长。
  3. 激活与运行时开销:经验上预留约 2 GiB,具体以实测为准。

以 70 亿参数的模型为例,权重为 7×10⁹ × 2 字节 ≈ 14 GB,约合 13 GiB。

KV cache 每个 token 占用的字节数为:2 × 层数 × KV 头数 × 头维度 × 每元素字节数。这些参数在模型目录的 config.json 中,字段名通常为 num_hidden_layers、num_key_value_heads 和 head_dim。假设模型有 32 层、8 个 KV 头、头维度为 128,使用 float16,则每个 token 占用 2 × 32 × 8 × 128 × 2 = 131072 字节,即 128 KiB。

若最大并发为 16,单请求上下文上限为 4096 token,则 KV cache 需要 16 × 4096 × 128 KiB = 8 GiB。

合计约 13 + 8 + 2 = 23 GiB。在 24 GB 显卡上,这个估算没有余量。框架运行时的内存碎片、峰值波动和多请求并发都会增加占用。24 GB 显卡只能在实测后,通过降低并发或上下文上限使用。生产环境建议选择 40 GB 或 48 GB 显存的型号。

启动时 --gpu-memory-utilization 控制 vLLM 可以占用的显存比例。建议先从 0.90 开始,压测无 OOM 后再调整。

2.2 带宽

带宽按以下公式估算:

带宽 ≈ 峰值 QPS × 平均单次响应字节数 × 余量系数(建议取 2 到 3)

各项口径如下:

  • 峰值 QPS:业务高峰分钟内每秒新增的请求数。
  • 平均单次响应字节数:压测中测得的完整响应体字节数,流式输出时取整次响应的累计字节。不要凭经验填写。
  • 余量系数:覆盖 HTTP 头、TLS 开销和突发流量。

假设峰值 QPS 为 20,平均响应为 3 KB,则基础流量为 20 × 3 KB = 60 KB/s,约合 0.48 Mbps。乘以余量系数 3 后,规划值约为 1.5 Mbps。文本推理通常不是带宽瓶颈,但内网调用和公网访问应分别规划,避免公网流量挤占内部通信。

2.3 存储

  • 系统盘与权重盘分开。
  • 权重盘需同时保存当前版本和至少一个历史版本,便于回滚。
  • 权重盘预留 20% 以上的空闲空间,防止日志或临时文件写满磁盘。

推荐的目录结构如下:

  1. /data/models/
  2. ├── <模型名>/
  3. │ ├── <新版本号>/
  4. │ └── <旧版本号>/
  5. └── current -> <模型名>/<当前版本号>/

每个版本目录内附带 SHA256SUMS 文件。部署前执行校验:

  1. cd /data/models/<模型名>/<版本号> && sha256sum -c SHA256SUMS

所有文件都显示 OK 才能继续。任何一个失败,都要重新下载,不能跳过。

检查磁盘剩余空间:

  1. df -h /data

三、环境准备

3.1 检查 GPU 与驱动

  1. nvidia-smi
  2. nvidia-smi --query-gpu=name,driver_version,memory.total --format=csv

验收标准:

  • GPU 型号与采购型号一致。
  • driver_version 满足所选 CUDA 版本的要求。
  • memory.total 不低于 40 GB。

检查 GPU 上是否有其他进程占用显存:

  1. nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv

如果有无关进程,先确认其归属并停止,再继续部署。停止进程前需要获得负责人确认。

3.2 创建专用用户与目录

推理服务不使用 root 运行:

  1. sudo useradd --system --home /opt/llm --shell /usr/sbin/nologin llm
  2. sudo mkdir -p /opt/llm /var/log/llm /etc/llm-infer
  3. sudo chown -R llm:llm /opt/llm /var/log/llm

模型目录由 root 所有,服务用户只读:

  1. sudo chown -R root:llm /data/models
  2. sudo chmod -R 750 /data/models

3.3 安装 Python 环境并锁定版本

  1. sudo -u llm python3 -m venv /opt/llm/venv
  2. sudo -u llm /opt/llm/venv/bin/pip install "vllm==<压测通过的版本号>"
  3. sudo -u llm /opt/llm/venv/bin/pip freeze > /opt/llm/requirements.lock

验证 CUDA 可用:

  1. /opt/llm/venv/bin/python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

输出应为 CUDA 版本号和 True。如果显示 False,说明驱动、CUDA 或 PyTorch 版本不匹配,需要先修复,不能继续启动服务。

四、启动服务

4.1 关键启动参数

参数 示例值 说明
--host 127.0.0.1 只监听本机,外部访问经网关
--port 8000 服务端口
--served-model-name demo-model 对外暴露的模型名,客户端请求时使用
--dtype float16 与权重精度一致
--max-model-len 4096 单请求上下文上限,直接影响 KV cache
--max-num-seqs 16 最大并发序列数,由压测结果决定
--gpu-memory-utilization 0.90 vLLM 可占用的显存比例
--disable-log-requests 开启 不记录请求内容,避免用户输入落盘

API 密钥通过环境变量 VLLM_API_KEY 传入,不写在命令行或代码中。参数名称会随版本变化,部署前执行 /opt/llm/venv/bin/vllm serve --help 确认。

手动启动测试:

  1. /opt/llm/venv/bin/vllm serve /data/models/current \
  2. --served-model-name demo-model \
  3. --host 127.0.0.1 \
  4. --port 8000 \
  5. --dtype float16 \
  6. --max-model-len 4096 \
  7. --max-num-seqs 16 \
  8. --gpu-memory-utilization 0.90 \
  9. --disable-log-requests

4.2 使用 systemd 托管

创建密钥文件,权限限定为 root 写、服务用户只读:

  1. sudo sh -c 'umask 077; echo "VLLM_API_KEY=<随机生成的长字符串>" > /etc/llm-infer/env'
  2. sudo chown root:llm /etc/llm-infer/env
  3. sudo chmod 640 /etc/llm-infer/env

创建服务文件 /etc/systemd/system/llm-infer.service:

  1. [Unit]
  2. Description=vLLM inference service
  3. After=network-online.target
  4. Wants=network-online.target
  5. StartLimitIntervalSec=600
  6. StartLimitBurst=3
  7. [Service]
  8. User=llm
  9. Group=llm
  10. EnvironmentFile=/etc/llm-infer/env
  11. ExecStart=/opt/llm/venv/bin/vllm serve /data/models/current --served-model-name demo-model --host 127.0.0.1 --port 8000 --dtype float16 --max-model-len 4096 --max-num-seqs 16 --gpu-memory-utilization 0.90 --disable-log-requests
  12. Restart=on-failure
  13. RestartSec=10
  14. TimeoutStartSec=900
  15. NoNewPrivileges=true
  16. [Install]
  17. WantedBy=multi-user.target

TimeoutStartSec 设为 900 秒,因为大模型加载可能需要数分钟。启动服务:

  1. sudo systemctl daemon-reload
  2. sudo systemctl enable --now llm-infer
  3. sudo journalctl -u llm-infer -f

日志中出现模型加载完成和 Uvicorn 监听信息后,再进行健康检查。

五、健康检查与验收

5.1 基础检查

加载密钥到当前 shell,避免把密钥写入命令历史:

  1. set -a; . /etc/llm-infer/env; set +a

依次执行以下检查:

  1. # 1. 健康检查,返回 200 表示服务就绪
  2. curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/health
  3. # 2. 模型列表,应包含 demo-model
  4. curl -fsS http://127.0.0.1:8000/v1/models -H "Authorization: Bearer ${VLLM_API_KEY}"
  5. # 3. 最小推理冒烟测试
  6. curl -fsS http://127.0.0.1:8000/v1/chat/completions \
  7. -H "Authorization: Bearer ${VLLM_API_KEY}" \
  8. -H "Content-Type: application/json" \
  9. -d '{"model":"demo-model","messages":[{"role":"user","content":"用一句话介绍你自己"}],"max_tokens":64,"temperature":0}'

第一项应输出 200。第二项应列出 demo-model。第三项应返回 JSON 格式的回答。任何一项失败,都不进入下一步。

5.2 压测方法

压测用于确定 --max-num-seqs 和验收基线,不能使用拍脑袋的数字。

  • 输入与输出长度:按真实业务分布采样,至少覆盖短、中、长三档。输出长度用 max_tokens 控制。
  • 并发梯度:依次测试 1、4、8、16 等并发档位,每档持续至少 10 分钟。
  • 记录指标:首 token 延迟(TTFT)的 P50、P95、P99,端到端延迟的 P95 和 P99,输出 token 吞吐,5xx 比例,超时比例,OOM 次数。
  • 判定:选出满足延迟目标且错误率达标的最高并发。--max-num-seqs 取该值的 80%,留出余量。

压测工具可以使用 vLLM 自带的基准测试命令(新版本为 vllm bench serve,具体参数以 --help 为准),也可以使用 locust、k6 等通用工具。压测时应在服务器本机或同一内网执行,避免公网波动干扰结果。

5.3 验收指标

指标 通过条件 说明
启动到 /health 返回 200 不超过 5 分钟 以实测加载时间为准,并写入基线
显存峰值 不超过总显存的 95% 压测全过程中采样 nvidia-smi
压测错误率(5xx 与超时) 不高于 0.5% 在验收负载下持续 30 分钟
首 token 延迟 P95 不高于业务目标值 目标值由业务方确定
长稳运行 连续 2 小时无进程重启 检查 systemctl show llm-infer -p NRestarts
输出抽检 黄金测试集人工比对,无明显回归 与上一版本输出对照
日志检查 日志中无用户输入原文 确认 --disable-log-requests 已生效

上表中的数字是起始值。每个团队应根据自己的业务目标和压测结果调整。

5.4 外部访问网关

外部请求经过网关进入推理服务。下面的 Nginx 配置只作示例,生产环境应接入正式的鉴权系统。

  1. http {
  2. limit_req_zone $binary_remote_addr zone=llm_api:10m rate=10r/s;
  3. server {
  4. listen 443 ssl;
  5. server_name llm.example.com;
  6. ssl_certificate /etc/nginx/certs/fullchain.pem;
  7. ssl_certificate_key /etc/nginx/certs/privkey.pem;
  8. location /v1/ {
  9. limit_req zone=llm_api burst=20 nodelay;
  10. proxy_pass http://127.0.0.1:8000;
  11. proxy_buffering off;
  12. proxy_read_timeout 300s;
  13. }
  14. }
  15. }

proxy_buffering off 保证流式输出实时返回。TLS 证书需要定期续期,续期后执行 nginx -t 检查配置,再执行 systemctl reload nginx。

防火墙只开放 443 端口,并确认 8000 端口不可从外部访问:

  1. sudo ufw allow 443/tcp
  2. sudo ufw deny 8000/tcp

从另一台外部机器验证:

  1. curl -m 5 http://<服务器公网IP>:8000/health

该命令应超时或被拒绝。如果能返回结果,说明推理端口暴露在公网,需要立即修复。

六、监控与告警

6.1 指标采集

vLLM 在 /metrics 端点暴露 Prometheus 格式的指标:

  1. curl -s http://127.0.0.1:8000/metrics | grep "^vllm:" | head -n 20

指标名称会随版本变化,例如 KV cache 使用率在不同版本中可能是 vllm:gpu_cache_usage_perc 或 vllm:kv_cache_usage_perc。接入监控前,先用上面的命令确认当前版本的实际名称。

6.2 告警规则

下表的阈值是起始值,应在上线后根据一周的数据调整。

告警项 指标或来源 阈值 持续时间 级别
服务不可用 /health 探测结果 非 200,每 15 秒探测 连续 3 次 严重
请求排队堆积 vllm:num_requests_waiting 大于 0 持续 5 分钟 警告
KV cache 紧张 KV cache 使用率 大于 90% 持续 5 分钟 警告
错误率升高 网关 5xx 占比 大于 1% 持续 5 分钟 严重
延迟升高 端到端延迟 P95 超过验收基线的 1.5 倍 持续 10 分钟 警告
进程反复重启 systemd 重启次数 10 分钟内 2 次及以上 即时 严重
磁盘空间不足 /data 剩余比例 低于 20% 即时 警告
显存接近上限 nvidia-smi 显存使用率 大于 95% 持续 5 分钟 警告

告警通知应发送到值班渠道。严重级别告警需要人工确认。

6.3 日志管理

  • 请求内容默认不记录。如需开启,必须设置保留期,并限制日志目录的访问权限。
  • 服务日志由 systemd journal 管理。长期保留时,将日志导出到 /var/log/llm,并配置 logrotate。
  • 日志中若出现密钥、用户隐私数据,应立即按安全事件处理,并轮换密钥。

七、上线与回滚

7.1 上线前自检清单

上线前逐项确认:

  • 新版本的 SHA256SUMS 校验全部通过。
  • vLLM 版本与 requirements.lock 一致。
  • GPU 型号、驱动版本、显存总量符合要求。
  • torch.cuda.is_available() 输出为 True。
  • 服务监听地址为 127.0.0.1,8000 端口外部不可达。
  • API 密钥已配置,且未出现在命令行、代码或日志中。
  • 压测完成,--max-num-seqs 与压测结果一致。
  • 验收指标全部通过,黄金测试集输出已抽检。
  • 告警规则已生效,值班人员已确认接收渠道。
  • 旧版本目录保留,磁盘剩余空间高于 20%。
  • 回滚步骤已演练,操作人知道回滚命令的位置。

7.2 上线步骤

单卡环境只能运行一个服务实例,无法做灰度或滚动发布。上线需要安排维护窗口,并在网关侧暂停外部流量。

  1. 在网关侧切换到维护页,停止新请求。
  2. 原子替换 current 软链接,指向新版本:
  1. sudo ln -sfn /data/models/<模型名>/<新版本号> /data/models/current.new
  2. sudo mv -Tf /data/models/current.new /data/models/current
  1. 重启服务并查看日志:
  1. sudo systemctl restart llm-infer
  2. sudo journalctl -u llm-infer -n 100 --no-pager
  1. 依次执行第五章的健康检查和冒烟测试。
  2. 恢复网关流量,并观察 30 分钟。期间关注错误率、延迟和显存指标。
  3. 观察结束且指标正常后,记录上线时间和版本号。

7.3 回滚触发条件

出现以下任一情况,应立即回滚:

  • /health 连续失败 3 次,且 5 分钟内无法恢复。
  • 5xx 错误率超过 1%,持续 5 分钟。
  • 出现 OOM 或进程 10 分钟内重启 2 次及以上。
  • 黄金测试集输出出现人工确认的质量回归。
  • 端到端延迟 P95 超过验收基线的 1.5 倍,持续 10 分钟。

是否回滚由值班负责人决定。遇到上述情况时,不要长时间排查后再决定回滚。

7.4 回滚步骤

  1. 在网关侧切换到维护页,停止外部流量。
  2. 将 current 软链接指回上一个稳定版本:
  1. sudo ln -sfn /data/models/<模型名>/<旧版本号> /data/models/current.new
  2. sudo mv -Tf /data/models/current.new /data/models/current
  3. sudo systemctl restart llm-infer
  1. 执行健康检查和冒烟测试,确认输出正常。
  2. 恢复网关流量,并观察 15 分钟。
  3. 保存故障现场日志,便于事后分析:
  1. sudo journalctl -u llm-infer --since "1 hour ago" --no-pager > /var/log/llm/rollback-$(date +%F-%H%M).log
  1. 记录回滚时间、触发的指标、操作人、新旧版本号。

7.5 回滚注意事项

  • 回滚不会撤销新版本已经产生的日志和数据。
  • 如果新版本修改了 tokenizer 或对话模板,客户端可能需要同步调整。回滚后需要确认客户端行为。
  • 旧版本目录在新版本稳定运行至少 7 天之前不要删除。删除任何版本目录都属于不可逆操作,需要负责人确认。
  • 回

发表评论

活动