在裸金属服务器上部署vLLM推理服务

说明在裸金属服务器上部署开源模型推理服务：官方前置条件为 Linux 与 Python 3.10 至 3.13，并覆盖 NVIDIA GPU 核对、隔离环境安装、服务启动和 /v1/models 验证。

在裸金属服务器上部署 vLLM，先按官方 Quickstart 准备 Linux 和 Python 3.10 至 3.13，并按 GPU 安装文档确认 NVIDIA GPU 的 compute capability 至少为 7.5；随后在全新 Python 环境安装并运行 vllm serve。服务启动后先请求 /v1/models 检查模型列表，再配置监听地址、API key、显存比例和上下文长度。

裸金属服务器先做兼容性检查

GPU 安装文档列出的预编译包包含 C++ 和 CUDA 12.9 binaries；B200、GB200 至少需要 CUDA 12.8。如果服务器使用其他 CUDA 版本，或准备沿用已有的 PyTorch 环境，官方要求改为源码构建，并使用 GCC/G++ 11.3 或更新版本。

具体到裸金属机箱，还要按具体卡型核对物理空间、供电接口和散热。NVIDIA 的 L4 规格列出 24GB GPU 显存、最大 72W TDP，并采用单槽半高 PCIe 形态；H100 规格则显示，SXM 形态最大 TDP 可达 700W，PCIe NVL 形态为 350-400W。不同卡型和形态不能套用同一套机箱与电源条件。

启动 vLLM 推理服务

按官方 Quickstart 的推荐路径，使用 uv 创建 Python 3.12 虚拟环境并安装。--torch-backend=auto 会检查已安装的 CUDA driver 版本并选择相应的 PyTorch 索引，也可以通过 UV_TORCH_BACKEND=auto 设置。

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

环境准备好后，用模型名启动服务：

vllm serve Qwen/Qwen2.5-1.5B-Instruct

服务默认监听 http://localhost:8000。需要让业务网中的其他机器访问时，可明确设置地址和端口，并启用 API key：

vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --host YOUR_VALUE \
  --port 8000 \
  --api-key YOUR_VALUE

--api-key 或 VLLM_API_KEY 都会启用 header 中的 API key 检查；也可以在 --api-key 后传入多个 key，服务接受其中任意一个，便于轮换。OpenAI Python 客户端可将 base_url 指向 http://localhost:8000/v1。当前一个 server process 一次承载一个模型，应在部署前确定服务边界。

设置显存和上下文参数

在线服务的 engine arguments 是 vllm serve 的一部分，具体参数可对照 Engine Arguments 和 Serve 命令参考。这些参数控制的是当前实例，不应脱离模型大小和业务请求方式直接套用。

--gpu-memory-utilization 表示 model executor 使用的 GPU 显存比例，范围为 0 到 1，默认值为 0.92。它是单实例限制，不会自动协调同一 GPU 上的另一个实例。
--kv-cache-memory-bytes 直接设置每张 GPU 的 KV cache 大小；设置后会覆盖 --gpu-memory-utilization。
--max-model-len 覆盖 prompt 与 output 的总长度；不指定时从模型配置推导，设为 -1 或 auto 时会选择适配当前 GPU 显存的最大长度。
--max-num-seqs 限制单次迭代处理的 sequences 数量，--max-num-batched-tokens 限制单次迭代处理的 tokens 数量。
--tensor-parallel-size 和 --pipeline-parallel-size 的默认值均为 1。多节点部署时，并行与扩展说明要求把 tensor parallel size 设为每节点的 GPU 数量，把 pipeline parallel size 设为节点数量。

验证服务是否真的可用

先检查模型列表：

curl http://localhost:8000/v1/models

响应中应出现已经启动的模型。如果启动时启用了 API key，应通过带凭据的客户端执行检查。

模型列表正常后，还需要验证推理接口。OpenAI 兼容服务器说明列出了 /v1/completions 和 /v1/chat/completions，可继续向 chat endpoint 发送请求，确认模型能够实际生成响应，而不只是完成注册。

在线服务说明还列出了 /version、/load、/v1/models 和 /health 等基础运维端点。服务器默认使用 tokenizer 中预定义的 chat template；如果模型没有可用模板，chat 请求会报错，此时可通过 --chat-template YOUR_VALUE 指定文件路径或模板字符串。更细的日志字段和采集方式应以当前版本的在线服务文档为准。

常见出错点

模型权重默认进入 Hugging Face cache，--download-dir 可以指定下载和加载位置，详见 Serve 命令参考。编译产物等缓存则由 VLLM_CACHE_ROOT 控制，默认根目录是 ~/.cache/vllm，并遵循 XDG_CACHE_HOME，参见安全说明。部署前应同时确认系统盘或数据盘的剩余空间和写入权限。

安装 nightly wheels 时不要改用 pip。NVIDIA CUDA 安装说明明确说明，pip 合并默认索引与 extra index 时可能只选择最新版本，因此 nightly 安装需要使用 uv。

如果启动时出现显存不足，应先检查模型、上下文长度、并发序列和批处理 token 上限。CUDA graphs 默认还会占用额外显存；排查时可以临时加入 --enforce-eager，它会禁用 CUDA graph capture 和 torch.compile，始终以 eager 模式运行，具体行为见显存优化说明。

这些步骤依据正文链接的官方文档整理，未运行或测量；使用前请对照当前版本复核。