# 使用 vLLM 部署 LLM 推理服务

> 在您的 GPU 服务器上用 vLLM 部署 LLM 推理服务：用 uv 配置 Python 环境，安装 PyTorch 和 vLLM，测试兼容 OpenAI 的 API，再将其作为系统服务长期运行。

来源：https://fullgpu.com/zh/docs/pytorch-vllm  
更新日期：2026-10-22  
发布方：FullGPU (https://fullgpu.com/)

本指南介绍如何在 FullGPU 服务器上用 vLLM 部署大语言模型（LLM）推理服务：创建 Python 环境，安装 PyTorch 和 vLLM，在单张 GPU 上或跨 8 张 GPU 启动兼容 OpenAI 的推理端点，用 curl 进行测试，并将其作为 systemd 服务运行。选择模型之前，请先用[显存计算器](https://fullgpu.com/zh/tools/vram-calculator)估算其显存需求。在 BF16 精度下，权重每个参数约占 2 字节，此外还要为 KV 缓存留出空间。

## 在 Python 环境中安装 PyTorch 和 vLLM

### 创建环境

uv 创建环境和安装软件包的速度都很快，还能获取操作系统未自带的 Python 版本：

```
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv venv ~/venvs/vllm --python 3.12
source ~/venvs/vllm/bin/activate
```

如果改用标准工具，请先运行 `sudo apt install -y python3-venv`，再运行 `python3 -m venv ~/venvs/vllm` 和同一条 `source` 命令。请把 vLLM 放在单独的环境中，与训练代码分开。

### 安装软件包

```
uv pip install vllm --torch-backend=auto
python -c "import torch, vllm; print(torch.__version__,
  torch.cuda.is_available(), vllm.__version__)"
```

您应该会在两个版本号之间看到 `True`。vLLM 固定了构建时所依赖的 PyTorch 版本，并会自动为您安装，`--torch-backend=auto` 则让 uv 选择与您的驱动相匹配的 PyTorch 构建版本。不要在此基础上再安装其他 PyTorch 版本。如果是不含 vLLM 的训练环境，可以用同样的方式单独安装 PyTorch：`uv pip install torch --torch-backend=auto`。如果使用普通的 pip，请运行 `pip install vllm`。

## 启动兼容 OpenAI 的服务器

在单张 GPU 上，7B 级模型很适合作为第一次测试：

```
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --host 127.0.0.1 --port 8000 \
  --max-model-len 16384 \
  --gpu-memory-utilization 0.90
```

在 8 卡服务器上，用张量并行把更大的模型拆分到所有 GPU 上：

```
vllm serve Qwen/Qwen2.5-72B-Instruct \
  --host 127.0.0.1 --port 8000 \
  --tensor-parallel-size 8 \
  --max-model-len 32768
```

首次启动时会下载权重，可能需要一些时间。日志中出现 `Application startup complete` 时，服务器即已就绪。权重保存在 `~/.cache/huggingface` 中；如果要把它们放在 [NVMe 数据盘](https://fullgpu.com/zh/docs/storage-nvme)上，请在启动前运行 `export HF_HOME=/data/hf`。

| 选项 | 作用 |
| --- | --- |
| `--tensor-parallel-size` | 共同承载该模型的 GPU 数量。它必须能整除模型的注意力头数；对大多数大型模型来说，设为 8 即可。 |
| `--max-model-len` | 每个请求的最长上下文（提示词加输出）。如果 vLLM 报告 KV 缓存无法容纳该最大长度，请调低此值。 |
| `--gpu-memory-utilization` | 每张 GPU 的显存中，vLLM 可用于权重和 KV 缓存的比例，默认为 0.9。如果有其他进程使用这张 GPU，请调低此值。 |
| `--host` | 监听地址。如果不设置，vLLM 会监听所有网络接口，因此请保留 `127.0.0.1`。 |

## 用 curl 测试 API

```
curl http://127.0.0.1:8000/v1/models

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen2.5-7B-Instruct",
       "messages": [{"role": "user", "content": "Say hello in five words."}],
       "max_tokens": 32}'
```

第一条请求应列出该模型。第二条请求返回 JSON，回答位于 `choices[0].message.content` 中。任何兼容 OpenAI 的客户端，只要把 base URL 设置为 `http://127.0.0.1:8000/v1` 即可使用。在您的笔记本电脑上，可以通过 SSH 隧道访问它：`ssh -N -L 8000:127.0.0.1:8000 gpu1`。

## 使用 Hugging Face 令牌访问受限模型

部分模型（例如 Meta 的 Llama 系列）要求您先在 Hugging Face 上接受许可协议。请用您的账户在模型页面上接受协议，创建一个具有读取权限的访问令牌，然后通过 `HF_TOKEN` 变量传给 vLLM。在提示符下输入令牌，可以避免它留在 shell 历史记录中：

```
read -rsp 'Hugging Face token: ' HF_TOKEN && export HF_TOKEN
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --host 127.0.0.1 --port 8000 --max-model-len 16384
```

如果下载时出现 401 或 403 错误，说明令牌缺失或有误，或者该账户尚未接受许可协议。

## 将 vLLM 作为 systemd 服务运行

1. 把设置和机密信息保存在只有 root 可读的文件中。用 `openssl rand -hex 32` 生成 API 密钥；vLLM 读取 `VLLM_API_KEY` 的效果，与传入 `--api-key` 相同。 `sudo mkdir -p /etc/vllm sudo tee /etc/vllm/vllm.env >/dev/null <<'EOF' HF_HOME=/data/hf HF_TOKEN=hf_your_token_here VLLM_API_KEY=replace-with-a-long-random-string EOF sudo chmod 600 /etc/vllm/vllm.env`
2. 创建 `/etc/systemd/system/vllm.service`。本示例以 root 身份运行，并使用上面创建的环境；如果使用其他用户账户，请相应调整 `User` 和各个路径： `[Unit] Description=vLLM OpenAI-compatible server After=network-online.target Wants=network-online.target [Service] User=root EnvironmentFile=/etc/vllm/vllm.env ExecStart=/root/venvs/vllm/bin/vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 127.0.0.1 --port 8000 --max-model-len 16384 Restart=on-failure RestartSec=10 [Install] WantedBy=multi-user.target`
3. 启动服务并跟踪日志： `sudo systemctl daemon-reload sudo systemctl enable --now vllm sudo journalctl -u vllm -f` 日志中出现 `Application startup complete` 后，只要加上请求头 `-H "Authorization: Bearer YOUR_KEY"`，前面的 curl 测试就能再次正常运行。不加这个请求头，应返回 401 Unauthorized。该服务会在崩溃后自动重启，并在开机时自动启动。

## 替代方案：vllm/vllm-openai 镜像

```
docker run -d --name vllm --gpus all --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v /data/hf:/data/hf \
  --env-file /etc/vllm/vllm.env \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-7B-Instruct --max-model-len 16384
```

该镜像的入口点就是 vLLM 服务器，因此镜像名称之后的参数会直接传给它。环境变量文件设置了 `HF_HOME=/data/hf`，所以要挂载这个路径。在生产环境中，请固定一个版本标签，不要使用 `latest`。在 AMD 服务器上，请使用 [ROCm 配置](https://fullgpu.com/zh/docs/amd-rocm)中介绍的 ROCm 镜像。

## 保护推理端点

个人使用时，让 vLLM 只监听 `127.0.0.1`，并通过 SSH 隧道访问。如果要通过互联网为应用提供服务，请在前面部署带 TLS 的反向代理，要求提供 API 密钥，并且只暴露 `/v1/` 路径：API 密钥保护的是 `/v1` 路由，`/metrics` 等其他路由可能仍然开放。[防火墙指南](https://fullgpu.com/zh/docs/networking-firewall)介绍了 ufw、Docker 发布的端口，以及 Caddy 或 nginx 的配置。关于容量规划和运行成本，请阅读[使用 vLLM 自托管 LLM 推理](https://fullgpu.com/zh/blog/self-host-llm-inference-vllm)。

## 故障排查

- **启动时出现“CUDA out of memory”错误。**请调低 `--max-model-len`，用 `--tensor-parallel-size` 把模型分布到更多 GPU 上，或者选择更小的模型或量化模型。用 `nvidia-smi` 确认没有其他进程占用显存。
- **注意力头数无法被张量并行度整除。**请选择能整除模型头数的并行度，例如用 4 代替 8。
- **401 Unauthorized.** 缺少 `Authorization` 请求头，或者密钥不匹配。

## 常见问题

### 用 vLLM 部署 70B 模型需要什么 GPU？

权重在 BF16 精度下约需 140 GB，在 FP8 精度下约需 70 GB，此外还要为 KV 缓存留出空间。一张 H200 能以 FP8 精度从容运行 70B 模型；在 BF16 精度下，单张 H200 只能勉强装下，因此请使用 B200 或 B300，或者用张量并行把模型拆分到多张 GPU 上。

### vLLM 能在 AMD Instinct MI355X 服务器上运行吗？

可以。请使用 AMD 提供的支持 ROCm 的 vLLM 镜像，并加上 ROCm 设备参数，具体见我们的 ROCm 配置指南。vllm serve 的选项完全相同。

### 如何更新 vLLM？

在同一个环境中运行 uv pip install -U vllm --torch-backend=auto，然后重启服务。如果该推理端点承载着生产流量，请先在单独的环境中测试新版本。

## 相关页面

- [如何使用 vLLM 自托管 LLM 推理](https://fullgpu.com/zh/blog/self-host-llm-inference-vllm): 使用 vLLM 自托管 LLM 推理：本文介绍如何估算所需的 GPU，运行兼容 OpenAI API 的推理服务器，调优 FP8、前缀缓存和并行策略，并为生产环境做好安全加固。
- [大模型推理 GPU 服务器：7×24 小时运行，价格固定](https://fullgpu.com/zh/solutions/inference): 大模型推理 GPU 服务器，可运行 vLLM、SGLang 或 TensorRT-LLM：本文介绍 KV 缓存估算以及 FP8 与 FP4 的选择，价格含每月 20–50 TB 流量。查看完整的选型计算。
- [大语言模型需要多少显存？](https://fullgpu.com/zh/blog/vram-for-llms): LLM 需要多少显存？快速解答 7B、14B、32B、70B 和 405B 模型在 BF16、FP8 和 4 位精度下的显存需求，另附按上下文长度计算的 KV 缓存，以及装得下模型的 GPU。
- [使用 NVIDIA Container Toolkit 运行 Docker GPU 容器](https://fullgpu.com/zh/docs/docker-containers): NVIDIA Container Toolkit 的 Docker GPU 指南：使用 --gpus 参数、选择设备、在 Compose 中预留 GPU、解决 PyTorch 共享内存不足问题，并运行 ROCm 容器。
- [GPU 服务器防火墙配置](https://fullgpu.com/zh/docs/networking-firewall): GPU 服务器防火墙配置指南：用 ufw 先放行 SSH 再启用防火墙，同时过滤 IPv6，避开 Docker 发布端口绕过 ufw 的陷阱，并用 TLS 和 API 密钥保护 vLLM 推理端点。