vllm部署大模型

一、部署环境

Ubuntu 22.04 64位
NVIDIA A100
CUDA 版本 12.4.1
Driver 版本 570.195.03
CUDNN 版本 9.2.0.82

1、检查物理显卡

先看物理 / 云服务器配置：确认机器带 NVIDIA 显卡
查看系统识别硬件
有输出 → 识别到显卡，只是缺驱动
无任何输出 → 系统都没识别到 GPU 硬件

lspci | grep -i nvidia

2、检查GPU驱动是否正常

nvidia-smi 是英伟达显卡驱动自带内置工具
安装正式显卡驱动 → 自动附带 nvidia-smi 二进制程序
驱动装成功 → 自动写入系统 PATH → 任意目录直接输命令就能用
反过来：
能正常执行 nvidia-smi 输出信息 = 显卡驱动百分百安装生效

nvidia-smi

二、安装docker

安装docker教程

三、安装NVIDIA GPU环境

1、安装容器桥接工具：NVIDIA Container Toolkit（决定Docker容器能不能用GPU）

1.1、添加 NVIDIA GPG 密钥

这是一条Linux 环境下安装 NVIDIA 容器工具包的密钥导入命令，核心作用是：下载并验证 NVIDIA 官方 GPG 密钥，保存到系统可信密钥目录，为后续安装 NVIDIA 容器工具包做安全认证准备。
第一部分：curl 下载密钥
curl：Linux 系统的网络下载工具，用来从网址获取内容
-fsSL：四个参数组合，是生产环境常用的安全静默模式：
-f：请求失败时直接返回错误，不输出垃圾页面
-s：静默模式，不显示下载进度条
-S：配合 -s 使用，出错时仍显示错误信息
-L：自动跟随网址重定向
网址：NVIDIA 官方提供的 GPG 公钥文件地址
作用：安全下载 NVIDIA 的官方 GPG 公钥文本

第二部分：管道符 |
管道符的作用：把左边命令的输出结果，直接传递给右边命令作为输入
这里就是：把 curl 下载的密钥文本，直接传给 gpg 命令处理

第三部分：gpg 密钥格式化 + 保存
gpg：GNU 隐私护卫工具，用来处理加密 / 签名 / 密钥
–dearmor：核心参数
下载的密钥是 ASCII 文本格式
这个参数把它转换成 系统能识别的二进制 .gpg 格式
-o：指定输出文件路径
输出路径：/usr/share/keyrings/ 是 Linux 系统存放可信第三方密钥的标准目录
作用：将下载的密钥转换成系统标准格式，保存为 NVIDIA 容器工具包专用密钥

以静默安全模式从 NVIDIA 官网下载 GPG 公钥 → 通过管道传给管理员权限的 gpg 工具 → 转换成系统支持的二进制格式 → 保存到系统可信密钥目录，命名为 nvidia-container-toolkit-keyring.gpg

这条命令的最终目的（为什么要执行它）
Linux 系统安装软件时，必须验证软件来源是否官方、未被篡改。
这条命令就是把 NVIDIA 加入系统的 “可信软件厂商白名单”，后续才能安全安装 nvidia-docker2 / NVIDIA Container Toolkit，让 Docker 容器调用 GPU。

这是 NVIDIA 容器工具包安装的第一步（密钥信任）
curl 负责下载密钥，gpg –dearmor 负责格式转换
最终生成一个系统可信的密钥文件，用于后续软件安装校验

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

1.2、添加软件源

这是配置 NVIDIA 容器工具包 APT 软件源的核心命令，作用是：下载官方软件源配置 → 注入刚才安装的 GPG 密钥签名 → 写入系统软件源目录，让 apt 能安全识别并安装 NVIDIA 官方软件。

第一部分：curl 下载官方源配置
curl：Linux 网络下载工具
-fsSL：静默安全下载（失败报错、无进度、自动重定向）
网址：NVIDIA 官方提供的 APT 软件源配置文件
作用：下载纯净的 NVIDIA 软件源配置文本

第二部分：sed 注入密钥签名（核心步骤）
sed：Linux 文本流编辑工具，直接处理管道传来的文本
s# 原内容 #新内容 #g：替换语法（用 # 代替 / 避免路径冲突）
替换逻辑：
原文本：deb https://
替换成：deb [signed-by=/usr/share/keyrings/…gpg] https://
关键作用：给软件源绑定上一步导入的 GPG 密钥
告诉系统：安装这个源里的软件，必须用这个密钥校验，确保安全。

第三部分：sudo tee 写入系统源目录
tee：读取管道输入，同时输出到文件 + 屏幕（这里主要用于写入文件）
目标路径：/etc/apt/sources.list.d/
这是 Debian/Ubuntu 系统存放第三方软件源的标准目录
作用：把编辑好的、带密钥签名的软件源配置，保存成系统可识别的 .list 文件

静默下载 NVIDIA 官方软件源配置 → 用 sed 给源地址绑定 GPG 密钥（安全校验）→ 用管理员权限写入系统 APT 软件源目录

这是 NVIDIA 容器工具包安装的第二步（配置软件源）
curl 下载源 → sed 绑定密钥 → tee 写入系统
完成后系统就信任 NVIDIA 官方软件源，可以正常 apt 安装
和上一条命令是一套组合拳：密钥信任 + 源配置

curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

1.3、更新软件源并安装

nvidia-container-toolkit的核心作用：
它是 NVIDIA 官方专门为容器（Docker /containerd）打造的 GPU 桥接工具，唯一目的就是让 Docker 容器能正常使用宿主机的 NVIDIA GPU。

它解决了什么问题？
默认情况下：
Docker 是隔离环境
容器里看不到宿主机的显卡
容器里无法运行 CUDA、无法使用 GPU 加速
nvidia-container-toolkit 就是用来打通容器和 GPU的中间层。

它的核心功能非常明确：
让容器识别到 NVIDIA 显卡
自动把宿主机的 GPU 驱动映射进容器（不用在容器里重装驱动）
提供 nvidia-container-runtime 运行时（让 Docker 支持 –gpus all 这样的 GPU 调用参数）
兼容 Docker /containerd/ Kubernetes

nvidia-container-toolkit顾名思义，英伟达显卡和docker容器技术之间的工具包。
它是Docker 与 NVIDIA GPU 之间的桥梁。没有它 → 容器用不了 GPU

sudo apt update && sudo apt install -y nvidia-container-toolkit

2、配置 Docker 支持 NVIDIA runtime

一句话：这条命令是给 Docker 打上 “能调用宿主机 GPU” 的插件配置，让 Docker 容器里能直接用显卡（CUDA、nvidia-smi 等）
nvidia-ctk：NVIDIA Container Toolkit 的命令行工具
runtime configure：配置容器运行时
–runtime=docker：指定给 Docker 做配置（也可以是 containerd/crio）NVIDIA

nvidia-container-toolkit：让容器能 “看见” GPU 的工具包
nvidia-ctk runtime configure：把这个工具包注册给 Docker，容器里能看到宿主机显卡，不用在容器里装驱动，直接复用宿主机驱动。
nvidia-smi：宿主机查显卡（和容器无关）

流程是：
装驱动 → 装 nvidia-container-toolkit → 执行这条 configure → 重启 docker → 容器可用 GPU。

sudo nvidia-ctk runtime configure --runtime=docker

3、重启 Docker 服务，让配置生效

sudo systemctl restart docker

4、验证（成功则有输出结果，失败则无返回）

4.1. 确认 runtime 存在

which nvidia-container-runtime

4.2. 确认 Docker 已识别 nvidia runtime

docker info | grep -i nvidia

四、vllm部署模型

1、执行容器命令

docker run -d \
  --runtime nvidia --gpus all \
  --name vllm-qwen2.5-0.5b \
  --restart always \
  -p 443:8000 \
  --ipc=host \
  -v /opt/llm/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --api-key CompanyAI@2026 \
  --enable-prefix-caching \
  --max-num-batched-tokens 16384

1.1、查看预填充缓存的命中率

（会出现：Prefix cache hit rate: 71.1%）

docker logs vllm-qwen2.5-0.5b --tail 20

2、检查模型服务是否正常启动

查看容器状态

docker ps -a | grep vllm-qwen2.5-0.5b

3、容器启动失败时，立刻看日志（最关键）

docker logs vllm-qwen2.5-0.5b -f

4、确认端口是否监听成功

ss -tulnp | grep 8000

五、问题与解决

1、问题解决

curl: (7) Failed to connect to 47.250.190.43 port 8000: Timed out

先确认ping 47.250.190.43，能不能ping通，如果出现丢包就换成手机热点

ping 47.250.190.43

2、安全组要放行指定端口，如果8000端口不被认可的话，可以换成443端口进行放行

2.1、关闭并删除容器

docker stop vllm-qwen2.5-0.5b

docker rm -f vllm-qwen2.5-0.5b

2.2、用 443 端口重新启动容器

docker run -d \
  --runtime nvidia --gpus all \
  --name vllm-qwen2.5-0.5b \
  --restart always \
  -p 443:8000 \
  --ipc=host \
  -v /opt/llm/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-0.5B-Instruct \
  --api-key CompanyAI@2026 \
  --enable-prefix-caching \
  --max-num-batched-tokens 16384

2.3、终极排查：在服务器上抓包，看流量是否到达，

在服务器上执行 <code>tcpdump</code> 抓包，确认请求是否真的到达了服务器：（抓 443 端口的流量）

sudo tcpdump -i any port 443 -n

3、Unauthorized

vLLM 对 OpenAI 格式的 API Key 有严格的要求，正确的格式应该是：

Authorization: Bearer CompanyAI@2026

4、The model ‘Qwen2.5-0.5B-Instruct’ does not exist

模型名称要写全：–model Qwen/Qwen2.5-0.5B

Qwen/Qwen2.5-0.5B