如何在美国GPU服务器上部署vLLM，提供AI推理API服务？

在美国 GPU 服务器上部署 vLLM，通常可以采用 Ubuntu 22.04 LTS、NVIDIA 驱动、Docker、NVIDIA Container Toolkit 和 vLLM OpenAI 兼容服务端这一组合。部署完成后，客户端可以通过 /v1/chat/completions、/v1/completions 和 /v1/models 等接口调用模型，接入自有应用、业务后台或内部推理网关。

本文采用一台具备 NVIDIA GPU 的美国云服务器作为示例，目标是运行 Qwen/Qwen2.5-7B-Instruct，通过 vLLM 提供带 API Key 鉴权的 HTTP API。示例环境为 Ubuntu 22.04 LTS、Docker Compose Plugin、vLLM 0.8.5 容器镜像，服务端口仅绑定到本机 127.0.0.1:8000，再由 Nginx 通过 HTTPS 对外提供服务。命令和输出均为示例，实际结果会受 GPU 型号、驱动版本、模型文件和网络状况影响。

一、部署目标与环境边界

1. 目标架构

本次部署包含以下组件：

请求链路如下：

客户端
  │ HTTPS
  ▼
Nginx:443
  │ HTTP，仅本机回环地址
  ▼
127.0.0.1:8000
  │
  ▼
vLLM 容器
  │
  ▼
NVIDIA GPU

不建议直接把 8000 端口暴露到公网。即使 vLLM 配置了 API Key，也应通过云平台安全组、系统防火墙和 Nginx 控制访问范围。

2. GPU 显存预估

模型权重只是显存占用的一部分，推理时还需要为 KV Cache、CUDA 工作区、请求批处理和运行时开销预留空间。以半精度模型为例，7B 参数模型的权重通常约为 14 GB，实际运行需要的显存会高于这个数值。

下面是用于初步选型的参考范围，不是固定性能承诺：

如果单卡无法容纳模型，不能只依靠降低 --gpu-memory-utilization 解决。应改用更小模型、兼容的量化版本，或者通过 --tensor-parallel-size 使用多张显卡。

将显存预算落实到服务器规格时，可以参考A5数据的美国GPU系列，其中提供A100 80GB显卡选项，并搭配服务器CPU、内存和NVMe存储。若计划增加上下文长度或并发请求数，80GB显存档位可作为容量评估的参照，但不代表任意模型和参数组合都能运行。确定具体套餐后，再按下文检查操作系统、GPU与驱动条件。

二、部署前准备

1. 登录并确认操作系统

使用具有 sudo 权限的普通用户登录美国 GPU 服务器。先确认系统和内核信息：

cat /etc/os-release
uname -m
uname -r

预期结果应包含类似内容：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
VERSION_CODENAME=jammy
x86_64

如果是 Ubuntu 20.04、Debian、Rocky Linux 或云平台定制系统，不要直接照搬下面的 APT 仓库命令，应先切换到对应发行版的安装方式。

2. 确认 GPU 与驱动

nvidia-smi
nvidia-smi -L

可参考以下示例判断：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 550.xx       Driver Version: 550.xx       CUDA Version: 12.x     |
+-----------------------------------------------------------------------------+
| GPU  Name                  Persistence-M| Bus-Id        Disp.A | Volatile |
|  0   NVIDIA ...                         Off            |        0 |
+-----------------------------------------------------------------------------+

这里的 CUDA Version 表示驱动支持的 CUDA API 兼容版本，不等于宿主机已经安装了完整 CUDA Toolkit。使用 vLLM 官方容器时，通常不需要在宿主机额外安装 nvcc。

如果执行 nvidia-smi 出现 command not found、No devices were found 或驱动加载失败，应先处理宿主机驱动、GPU 直通和云平台实例配置。不要在驱动状态未确认前继续安装 vLLM。

如果服务器由云平台提供 NVIDIA 专用镜像，优先按照云平台文档安装驱动。确实没有驱动且系统为标准 Ubuntu 时，可以先查看可用驱动：

ubuntu-drivers devices

需要安装或更换驱动时，驱动包可能会修改内核模块并要求重启。执行前应确认当前 SSH 会话可以重新连接，并安排维护窗口：

sudo ubuntu-drivers install
sudo reboot

重启后再次执行 nvidia-smi。如果云平台要求固定驱动版本，不要使用上述自动安装方式覆盖平台驱动。

3. 检查磁盘、内存和网络

df -h /
free -h
ip -br addr

模型文件、容器镜像和缓存会占用磁盘空间。7B 模型的实际下载空间可能在十几 GB 到数十 GB 之间，建议至少为系统、镜像和模型缓存预留 50 GB 以上，并根据模型数量增加磁盘。

美国服务器还需要能够访问容器镜像仓库和模型仓库。如果服务器配置了云平台出口限制、防火墙或企业 DNS，应提前确认：

curl -I --max-time 15 https://registry-1.docker.io
curl -I --max-time 15 https://huggingface.co

这些命令返回 200、301 或其他 HTTP 响应，通常说明 TCP 和 TLS 基本可用；超时、DNS 失败或证书错误则需要先处理网络问题。

三、安装 Docker 与 NVIDIA Container Toolkit

1. 安装 Docker Engine

下面的命令适用于 Ubuntu 22.04。安装 Docker 会新增软件源和系统服务，执行前应确认服务器允许安装第三方软件包。

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor --yes -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo systemctl enable --now docker

验证 Docker 和 Compose：

sudo docker version
sudo docker compose version
sudo systemctl is-active docker

预期状态类似：

active
Docker Compose version v2.x.x

如果当前用户不在 docker 用户组，本文后续命令统一使用 sudo docker 或 sudo docker compose。将用户加入 docker 组会赋予其近似主机管理员级别的容器权限，属于权限变更操作，应结合服务器账号管理策略决定是否执行。

2. 安装 NVIDIA Container Toolkit

NVIDIA Container Toolkit 用于让 Docker 容器访问宿主机 GPU。执行以下命令添加软件源：

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

curl -s -L 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 > /dev/null

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

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

使用 CUDA 基础镜像验证容器能否看到 GPU：

sudo docker run --rm --gpus all \
  nvidia/cuda:12.4.1-base-ubuntu22.04 \
  nvidia-smi

如果验证成功，容器内应能看到与宿主机相同的 GPU 列表。该命令只是测试 GPU 映射，不会修改模型或推理服务。

如果出现以下情况，应分别处理：

• could not select device driver "" with capabilities: [[gpu]]：Docker 尚未正确配置 NVIDIA runtime。
• 容器能启动但 nvidia-smi 无设备：检查宿主机驱动和 GPU 直通。
• CUDA 版本相关错误：确认宿主机驱动满足镜像内 CUDA 运行库的最低要求，必要时更换兼容镜像或升级驱动。
• 拉取镜像超时：检查美国服务器的 DNS、出口策略和 Docker Hub 访问情况。

四、创建 vLLM 配置

1. 创建工作目录和环境文件

sudo mkdir -p /opt/vllm
sudo chown "$USER":"$USER" /opt/vllm
cd /opt/vllm

生成一个随机 API Key。该 Key 只用于示例，生产环境应通过密码管理系统或云密钥服务保存：

API_KEY=$(openssl rand -hex 32)

cat > .env <

这里的 HF_TOKEN 对公开模型可以留空。如果使用需要授权的私有模型或受限模型，应将访问令牌写入 .env，并限制文件权限。不要把 .env 提交到 Git，也不要把 API Key 放在前端代码中。

API Key 会作为 vLLM 启动参数传入容器，因此主机管理员仍可能通过进程信息或容器检查命令看到它。多租户生产环境建议在 vLLM 前增加独立的认证、限流和审计层。

2. 编写 Docker Compose 文件

创建 /opt/vllm/compose.yaml：

cat > compose.yaml <<'EOF'
services:
  vllm:
    image: ${VLLM_IMAGE}
    container_name: vllm-api
    restart: unless-stopped
    gpus: all
    ipc: host

    environment:
      HF_HOME: /root/.cache/huggingface
      HF_TOKEN: ${HF_TOKEN:-}

    volumes:
      - hf_cache:/root/.cache/huggingface

    ports:
      - "127.0.0.1:8000:8000"

    command:
      - "--model"
      - "${MODEL_ID}"
      - "--served-model-name"
      - "${SERVED_MODEL_NAME}"
      - "--host"
      - "0.0.0.0"
      - "--port"
      - "8000"
      - "--api-key"
      - "${VLLM_API_KEY}"
      - "--max-model-len"
      - "${MAX_MODEL_LEN}"
      - "--gpu-memory-utilization"
      - "${GPU_MEMORY_UTILIZATION}"
      - "--tensor-parallel-size"
      - "${TENSOR_PARALLEL_SIZE}"

volumes:
  hf_cache:
EOF

配置中的关键参数含义如下：

• ports 绑定到 127.0.0.1，表示只允许本机访问，避免直接暴露 vLLM 端口。
• --served-model-name 是 API 请求中使用的模型名，不一定等于 Hugging Face 模型 ID。
• --max-model-len 8192 限制单次请求的最大上下文长度，数值越高，KV Cache 占用通常越大。
• --gpu-memory-utilization 0.90 表示 vLLM 尝试使用约 90% 的可用 GPU 显存。遇到显存不足时可以尝试调低，但它无法弥补模型权重本身放不下的问题。
• --tensor-parallel-size 1 表示使用一张 GPU。两张同类 GPU 可以改为 2，但必须确认 nvidia-smi -L 能看到至少两张卡，并且容器具备多卡访问权限。

如果需要设置多卡，修改 .env：

sed -i 's/^TENSOR_PARALLEL_SIZE=.*/TENSOR_PARALLEL_SIZE=2/' .env

此命令会覆盖该配置行，执行前应确认 .env 已备份。单卡环境不要设置为 2，否则服务会启动失败。

检查 Compose 配置语法时使用安静模式，避免在终端打印包含 API Key 的完整展开配置：

sudo docker compose config --quiet

没有输出且退出状态为 0，通常表示 YAML 和变量引用格式正确。

五、启动 vLLM 并验证模型

1. 拉取镜像并启动

cd /opt/vllm

sudo docker compose pull
sudo docker compose up -d

查看容器状态：

sudo docker compose ps
sudo docker ps --filter name=vllm-api

启动阶段可能需要下载容器镜像和模型文件，第一次启动时间取决于美国服务器到镜像仓库、模型仓库的网络速度和磁盘性能。查看日志：

sudo docker compose logs -f --tail=100

示例状态仅用于判断日志方向，不代表实际执行记录：

INFO ... Starting vLLM API server
INFO ... Loading model Qwen/Qwen2.5-7B-Instruct
INFO ... Available cache memory ...
INFO ... Uvicorn running on http://0.0.0.0:8000

看到模型加载完成并开始监听端口后，按 Ctrl+C 退出日志查看，不会停止容器。另开终端检查：

sudo docker inspect -f '{{.State.Status}}' vllm-api
sudo nvidia-smi

容器状态应为：

running

nvidia-smi 中应能看到 Python 或 vLLM 相关进程占用显存。若容器状态为 restarting，不要反复执行 up，先查看完整日志定位原因。

2. 验证模型列表接口

读取 .env 中的 API Key：

cd /opt/vllm
API_KEY=$(awk -F= '$1=="VLLM_API_KEY"{print substr($0,index($0,"=")+1)}' .env)

请求本机 API：

curl --fail-with-body -sS --max-time 30 \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer ${API_KEY}"

成功时会返回类似结构：

{
  "object": "list",
  "data": [
    {
      "id": "qwen2.5-7b-instruct",
      "object": "model",
      "owned_by": "vllm"
    }
  ]
}

重点检查 data[0].id 是否为 qwen2.5-7b-instruct。如果请求返回 401，通常是 API Key 不正确或请求头缺失；如果返回 404，先确认访问路径是否为 /v1/models。

3. 验证聊天补全接口

使用模型列表中返回的 id 发起测试请求：

curl --fail-with-body -sS --max-time 120 \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b-instruct",
    "messages": [
      {
        "role": "user",
        "content": "请用一句话说明 vLLM 的作用。"
      }
    ],
    "temperature": 0.2,
    "max_tokens": 128
  }'

成功响应通常包含以下字段：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "vLLM 是用于高效提供大语言模型推理服务的运行框架。"
      },
      "finish_reason": "stop"
    }
  ]
}

第一次请求可能包含模型预热、CUDA 图初始化或 KV Cache 初始化时间。应至少执行两到三次请求，再观察响应时间和显存使用情况，不要只根据第一次请求判断吞吐能力。

六、通过 Nginx 提供 HTTPS API

1. 安装 Nginx 并保留配置备份

只有本机 API 验证成功后，才建议配置公网入口。Nginx 配置修改前先备份：

sudo cp -a /etc/nginx "/etc/nginx.backup.$(date +%Y%m%d%H%M%S)"
sudo apt-get update
sudo apt-get install -y nginx

如果系统中已有 Nginx，该备份可用于回滚。不要在没有备份的情况下批量覆盖 /etc/nginx。

2. 创建反向代理配置

将 api.example.com 替换为已经解析到美国服务器公网 IP 的域名：

sudo tee /etc/nginx/sites-available/vllm-api > /dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;

    server_name api.example.com;

    client_max_body_size 2m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Authorization $http_authorization;

        proxy_buffering off;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}
EOF

sudo ln -sfn /etc/nginx/sites-available/vllm-api \
  /etc/nginx/sites-enabled/vllm-api

sudo nginx -t
sudo systemctl reload nginx

nginx -t 必须显示语法检查成功后才能 reload。示例结果：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

此时可以用 HTTP 检查链路是否连通，但不要在公网通过明文 HTTP 传输正式 API Key。正式调用应在证书签发后使用 HTTPS。

3. 配置 TLS 证书

确保域名的 A 记录已经指向服务器公网 IPv4，并且云平台安全组允许临时访问 TCP 80 和正式访问 TCP 443。安装 Certbot：

sudo apt-get install -y certbot python3-certbot-nginx

申请证书并让 Certbot 修改 Nginx 配置：

sudo certbot --nginx -d api.example.com

该命令可能将 HTTP 重定向到 HTTPS，并修改站点配置。执行前已经备份 Nginx；如果证书申请失败，应先查看 DNS、80 端口和域名解析，不要反复覆盖配置。

证书完成后测试公网 API：

curl --fail-with-body -sS --max-time 30 \
  https://api.example.com/v1/models \
  -H "Authorization: Bearer ${API_KEY}"

如果返回模型列表，说明域名、TLS、Nginx 和 vLLM 已连通。生产环境还应配置证书自动续期检查：

sudo systemctl status certbot.timer
sudo certbot renew --dry-run

4. 配置主机和云平台防火墙

防火墙规则变更可能导致 SSH 断连。执行前应保持当前 SSH 会话，并确认云平台安全组已经允许实际使用的 SSH 端口。下面以 SSH 使用 22 端口为例：

sudo ufw status verbose

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

sudo ufw enable
sudo ufw status numbered

如果 SSH 使用其他端口，应将 22 替换为实际端口。不要添加 8000/tcp 的公网放行规则，因为 Compose 已将该端口绑定到 127.0.0.1。

如果需要限制管理入口，可以将 SSH 规则改为固定办公出口 IP，但必须先确认备用登录通道可用。防火墙回滚时，应使用编号删除错误规则，而不是直接清空全部规则：

sudo ufw status numbered
sudo ufw delete <规则编号>

七、常见失败处理

1. 容器启动后立即退出

先查看最近日志：

sudo docker compose logs --tail=200 vllm-api

常见原因包括：

• 模型名称拼写错误或模型仓库不可访问；
• TENSOR_PARALLEL_SIZE 大于实际 GPU 数量；
• vLLM 镜像与宿主机驱动不兼容；
• 参数名称不被当前 vLLM 版本支持；
• API Key 或环境变量为空；
• 磁盘空间不足。

确认容器实际使用的镜像和配置：

sudo docker inspect vllm-api \
  --format '{{.Config.Image}}'

sudo docker inspect vllm-api \
  --format '{{range .Config.Cmd}}{{printf "%s " .}}{{end}}'

不要在共享终端中直接打印包含 API Key 的完整容器配置。

2. CUDA out of memory

先查看 GPU 显存：

nvidia-smi

如果模型权重加载阶段就发生 OOM，优先选择更小或量化模型；如果是长上下文或并发请求阶段发生 OOM，可先缩短上下文并降低资源配置：

sed -i 's/^MAX_MODEL_LEN=.*/MAX_MODEL_LEN=4096/' .env
sed -i 's/^GPU_MEMORY_UTILIZATION=.*/GPU_MEMORY_UTILIZATION=0.85/' .env

sudo docker compose up -d

修改 .env 前应保存副本：

cp .env ".env.backup.$(date +%Y%m%d%H%M%S)"

如果降低上下文后仍然无法加载模型，说明问题可能是权重本身超过单卡容量，应更换模型、使用兼容量化版本或启用多卡张量并行，而不是继续降低利用率。

3. 模型下载失败、401 或 403

检查容器日志中显示的模型仓库错误：

sudo docker compose logs --tail=200 vllm-api | grep -Ei '401|403|401|timeout|download|hugging'

处理方向如下：

• 公开模型：确认服务器可以访问模型仓库；
• 私有模型：在 .env 中填写有效的 HF_TOKEN；
• 受许可模型：先在模型仓库页面完成使用授权；
• 下载中断：确认磁盘空间和缓存卷没有被删除；
• 网络不稳定：不要频繁执行清理命令，避免重复下载大文件。

模型缓存位于名为 hf_cache 的 Docker volume 中。除非确认需要重新下载，否则不要使用 docker compose down -v。

4. /v1/models 返回 401、404 或模型不存在

401 通常表示请求头错误：

Authorization: Bearer your-api-key

404 可能是路径缺少 /v1，也可能是 Nginx location 或 proxy_pass 配置不正确。

如果模型列表接口成功，但聊天接口返回模型不存在，检查请求体中的 model 是否与 served-model-name 一致：

grep -E '^(MODEL_ID|SERVED_MODEL_NAME)=' /opt/vllm/.env

客户端应使用：

{
  "model": "qwen2.5-7b-instruct"
}

而不是直接使用：

{
  "model": "Qwen/Qwen2.5-7B-Instruct"
}

除非两者配置成相同值。

5. Nginx 返回 502 Bad Gateway

先确认 vLLM 容器状态和本机端口：

sudo docker compose ps
curl -v http://127.0.0.1:8000/v1/models
sudo tail -n 100 /var/log/nginx/error.log

不同结果代表不同问题：

• 本机 8000 也无法访问：处理 vLLM 容器或模型加载问题；
• 本机访问正常，Nginx 返回 502：检查 proxy_pass、Nginx 配置和 reload 状态；
• Nginx 能访问模型列表，聊天请求超时：检查 proxy_read_timeout、上下文长度和模型推理时间；
• HTTPS 握手失败：检查证书、域名解析和云平台 443 端口规则。

6. GPU 负载低但 API 响应慢

先区分首个请求慢和持续请求慢。首次请求可能包含模型加载或编译开销；持续请求慢则需要检查：

watch -n 1 nvidia-smi
sudo docker stats vllm-api

还应记录请求的输入 Token 数、输出 Token 数、并发数和上下文长度。美国服务器的 GPU 型号、客户端所在地区、网络 RTT、请求大小和模型精度都会影响实际延迟，不能只用单次 curl 结果代表服务吞吐。

八、验收与回滚检查项

1. 上线验收

正式交付前逐项确认：

• nvidia-smi 能识别目标 GPU，显存和驱动状态正常；
• sudo docker run --rm --gpus all ... nvidia-smi 能在容器内识别 GPU；
• sudo docker compose ps 中 vllm-api 状态为 running；
• vLLM 日志显示模型加载完成且没有持续重启；
• /v1/models 携带正确 API Key 时返回模型列表；
• /v1/chat/completions 能返回有效 JSON；
• API 请求使用的模型名与 SERVED_MODEL_NAME 一致；
• 8000 没有对公网开放；
• Nginx nginx -t 检查通过；
• HTTPS 域名能够访问 /v1/models；
• 云平台安全组和 UFW 仅放行必要端口；
• .env 权限为 600，API Key 未提交到代码仓库；
• 模型缓存所在磁盘仍有足够可用空间；
• 证书续期定时器和日志轮转状态正常。

2. 保留当前版本并回滚 vLLM

升级镜像或调整参数前，先备份配置：

cd /opt/vllm
cp compose.yaml "compose.yaml.backup.$(date +%Y%m%d%H%M%S)"
cp .env ".env.backup.$(date +%Y%m%d%H%M%S)"

如果新版本启动失败，将 .env 中的镜像改回已验证版本：

sed -i 's#^VLLM_IMAGE=.*#VLLM_IMAGE=vllm/vllm-openai:v0.8.5#' .env
sudo docker compose up -d

Docker Compose 重新创建容器时不会自动删除 hf_cache，已下载的模型通常可以继续使用。

3. 停止服务但保留模型缓存

临时下线服务：

cd /opt/vllm
sudo docker compose stop

重新上线：

sudo docker compose start

如果需要删除容器但保留模型缓存：

sudo docker compose down

不要轻易执行以下命令：

sudo docker compose down -v

-v 会删除 Compose 管理的 hf_cache 卷，可能导致模型缓存被清除，下一次启动需要重新下载。

4. 回滚 Nginx 和防火墙

如果 Nginx 修改后导致站点异常，先测试配置：

sudo nginx -t

确认需要恢复时，可以停止 Nginx 并从备份目录恢复。恢复前应确认备份目录名称：

ls -ld /etc/nginx.backup.*

防火墙回滚应先查看编号：

sudo ufw status numbered

只删除本次新增且确认有问题的规则，保留当前 SSH 端口规则，避免误锁定服务器。回滚完成后，再分别验证本机 vLLM、Nginx HTTP 状态和 HTTPS API 状态。