单机单卡开源大模型推理服务上线与回滚实操指南
作者: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 显存
推理时的显存占用由三部分组成:
- 模型权重:参数量乘以每个参数的字节数。半精度(float16)每个参数占 2 字节。
- KV cache:随并发数和上下文长度增长。
- 激活与运行时开销:经验上预留约 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% 以上的空闲空间,防止日志或临时文件写满磁盘。
推荐的目录结构如下:
/data/models/├── <模型名>/│ ├── <新版本号>/│ └── <旧版本号>/└── current -> <模型名>/<当前版本号>/
每个版本目录内附带 SHA256SUMS 文件。部署前执行校验:
cd /data/models/<模型名>/<版本号> && sha256sum -c SHA256SUMS
所有文件都显示 OK 才能继续。任何一个失败,都要重新下载,不能跳过。
检查磁盘剩余空间:
df -h /data
三、环境准备
3.1 检查 GPU 与驱动
nvidia-sminvidia-smi --query-gpu=name,driver_version,memory.total --format=csv
验收标准:
- GPU 型号与采购型号一致。
driver_version满足所选 CUDA 版本的要求。memory.total不低于 40 GB。
检查 GPU 上是否有其他进程占用显存:
nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv
如果有无关进程,先确认其归属并停止,再继续部署。停止进程前需要获得负责人确认。
3.2 创建专用用户与目录
推理服务不使用 root 运行:
sudo useradd --system --home /opt/llm --shell /usr/sbin/nologin llmsudo mkdir -p /opt/llm /var/log/llm /etc/llm-infersudo chown -R llm:llm /opt/llm /var/log/llm
模型目录由 root 所有,服务用户只读:
sudo chown -R root:llm /data/modelssudo chmod -R 750 /data/models
3.3 安装 Python 环境并锁定版本
sudo -u llm python3 -m venv /opt/llm/venvsudo -u llm /opt/llm/venv/bin/pip install "vllm==<压测通过的版本号>"sudo -u llm /opt/llm/venv/bin/pip freeze > /opt/llm/requirements.lock
验证 CUDA 可用:
/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 确认。
手动启动测试:
/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
4.2 使用 systemd 托管
创建密钥文件,权限限定为 root 写、服务用户只读:
sudo sh -c 'umask 077; echo "VLLM_API_KEY=<随机生成的长字符串>" > /etc/llm-infer/env'sudo chown root:llm /etc/llm-infer/envsudo chmod 640 /etc/llm-infer/env
创建服务文件 /etc/systemd/system/llm-infer.service:
[Unit]Description=vLLM inference serviceAfter=network-online.targetWants=network-online.targetStartLimitIntervalSec=600StartLimitBurst=3[Service]User=llmGroup=llmEnvironmentFile=/etc/llm-infer/envExecStart=/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-requestsRestart=on-failureRestartSec=10TimeoutStartSec=900NoNewPrivileges=true[Install]WantedBy=multi-user.target
TimeoutStartSec 设为 900 秒,因为大模型加载可能需要数分钟。启动服务:
sudo systemctl daemon-reloadsudo systemctl enable --now llm-infersudo journalctl -u llm-infer -f
日志中出现模型加载完成和 Uvicorn 监听信息后,再进行健康检查。
五、健康检查与验收
5.1 基础检查
加载密钥到当前 shell,避免把密钥写入命令历史:
set -a; . /etc/llm-infer/env; set +a
依次执行以下检查:
# 1. 健康检查,返回 200 表示服务就绪curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/health# 2. 模型列表,应包含 demo-modelcurl -fsS http://127.0.0.1:8000/v1/models -H "Authorization: Bearer ${VLLM_API_KEY}"# 3. 最小推理冒烟测试curl -fsS http://127.0.0.1:8000/v1/chat/completions \-H "Authorization: Bearer ${VLLM_API_KEY}" \-H "Content-Type: application/json" \-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 配置只作示例,生产环境应接入正式的鉴权系统。
http {limit_req_zone $binary_remote_addr zone=llm_api:10m rate=10r/s;server {listen 443 ssl;server_name llm.example.com;ssl_certificate /etc/nginx/certs/fullchain.pem;ssl_certificate_key /etc/nginx/certs/privkey.pem;location /v1/ {limit_req zone=llm_api burst=20 nodelay;proxy_pass http://127.0.0.1:8000;proxy_buffering off;proxy_read_timeout 300s;}}}
proxy_buffering off 保证流式输出实时返回。TLS 证书需要定期续期,续期后执行 nginx -t 检查配置,再执行 systemctl reload nginx。
防火墙只开放 443 端口,并确认 8000 端口不可从外部访问:
sudo ufw allow 443/tcpsudo ufw deny 8000/tcp
从另一台外部机器验证:
curl -m 5 http://<服务器公网IP>:8000/health
该命令应超时或被拒绝。如果能返回结果,说明推理端口暴露在公网,需要立即修复。
六、监控与告警
6.1 指标采集
vLLM 在 /metrics 端点暴露 Prometheus 格式的指标:
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 上线步骤
单卡环境只能运行一个服务实例,无法做灰度或滚动发布。上线需要安排维护窗口,并在网关侧暂停外部流量。
- 在网关侧切换到维护页,停止新请求。
- 原子替换
current软链接,指向新版本:
sudo ln -sfn /data/models/<模型名>/<新版本号> /data/models/current.newsudo mv -Tf /data/models/current.new /data/models/current
- 重启服务并查看日志:
sudo systemctl restart llm-infersudo journalctl -u llm-infer -n 100 --no-pager
- 依次执行第五章的健康检查和冒烟测试。
- 恢复网关流量,并观察 30 分钟。期间关注错误率、延迟和显存指标。
- 观察结束且指标正常后,记录上线时间和版本号。
7.3 回滚触发条件
出现以下任一情况,应立即回滚:
/health连续失败 3 次,且 5 分钟内无法恢复。- 5xx 错误率超过 1%,持续 5 分钟。
- 出现 OOM 或进程 10 分钟内重启 2 次及以上。
- 黄金测试集输出出现人工确认的质量回归。
- 端到端延迟 P95 超过验收基线的 1.5 倍,持续 10 分钟。
是否回滚由值班负责人决定。遇到上述情况时,不要长时间排查后再决定回滚。
7.4 回滚步骤
- 在网关侧切换到维护页,停止外部流量。
- 将
current软链接指回上一个稳定版本:
sudo ln -sfn /data/models/<模型名>/<旧版本号> /data/models/current.newsudo mv -Tf /data/models/current.new /data/models/currentsudo systemctl restart llm-infer
- 执行健康检查和冒烟测试,确认输出正常。
- 恢复网关流量,并观察 15 分钟。
- 保存故障现场日志,便于事后分析:
sudo journalctl -u llm-infer --since "1 hour ago" --no-pager > /var/log/llm/rollback-$(date +%F-%H%M).log
- 记录回滚时间、触发的指标、操作人、新旧版本号。
7.5 回滚注意事项
- 回滚不会撤销新版本已经产生的日志和数据。
- 如果新版本修改了 tokenizer 或对话模板,客户端可能需要同步调整。回滚后需要确认客户端行为。
- 旧版本目录在新版本稳定运行至少 7 天之前不要删除。删除任何版本目录都属于不可逆操作,需要负责人确认。
- 回

登录后可评论,请前往 登录 或 注册