垦荒学园
  • 中文

      • 安装与环境

      vLLM 的 幸福路径是 Linux + NVIDIA CUDA GPU。官方预编译轮子面向 Linux；不原生支持 Windows——Windows 用户请用 WSL2 里的 Linux 发行版再装。CPU 推理即使存在，也不是本课目标：没有合适 GPU 时，先用 Ollama 完成本地对话。

      Python、CUDA 小版本、计算能力下限会随发行变化。下面以常见稳定事实为准，具体数字请核对本机的 GPU 安装页。

      环境要求（幸福路径）

      项常见要求（以当前文档为准）
      操作系统Linux（Ubuntu 等）；Windows → WSL2
      Python3.10–3.13，推荐 3.12
      GPUNVIDIA，计算能力常见为 7.5+（T4、RTX 20 系及以上、A100、L4、H100、B200 等）
      驱动 / CUDA能跑对应 PyTorch CUDA 轮子；当前文档常提到 CUDA 12.8 / 12.9 构建
      磁盘Hub 缓存（默认 ~/.cache/huggingface）要有数 GB 以上空闲

      先确认 GPU 可见：

      nvidia-smi

      能列出 GPU 名称、驱动版本即可。WSL2 里同样要能跑通 nvidia-smi，否则先修好 NVIDIA 在 WSL 中的 GPU 支持，再装 vLLM。

      创建虚拟环境

      官方也推荐 uv。pip 足够入门：

      python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

      uv 示例（以当前文档为准）：

      uv venv --python 3.12 --seed
source .venv/bin/activate

      请使用全新环境。vLLM 自带编译好的 CUDA 内核，与「随便一个 conda 里的 PyTorch」混装很容易 ABI 不匹配。

      安装 vLLM

      最简命令：

      pip install vllm

      官方 GPU 页常建议让安装器选对 PyTorch CUDA 索引，例如：

      uv pip install vllm --torch-backend=auto

      或（示例，CUDA 小版本会变）：

      pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129

      不要把文档里的 cu129 抄死到生产脚本里而不核对：以 安装文档 和 PyTorch Get Started 为准。

      验证：

      python -c "import vllm; print('vllm ok')"
vllm --help
# 或
vllm serve --help

      能看到 serve（部分新版本可能写作 server，以当前 CLI 为准）即可进入 快速上手。

      Windows：WSL2

      1. 安装 WSL2 与 Ubuntu（或其他官方支持的 Linux）。
      2. 在 Windows 侧安装足够新的 NVIDIA 驱动，使 WSL 内 nvidia-smi 可用。
      3. 在 WSL 终端里创建 venv 并 pip install vllm，不要在 Win32 Python 里装官方轮子。
      4. 模型缓存建议放在 Linux 文件系统（例如 \\wsl$\... 对应的家目录），避免跨文件系统拖慢 Hub 下载。

      社区有非官方 Windows 构建，本教程不覆盖；生产与教学一律按 Linux / WSL2。

      Hugging Face 缓存与 Token

      权重默认从 Hub 拉取。未门控小模型（本课用的 Qwen 0.5B、OPT-125M）一般不必登录。门控模型需要：

      export HF_TOKEN="hf_..."   # 或 HUGGING_FACE_HUB_TOKEN，以 Hub 文档为准

      不要把 Token 写进 Git。国内网络访问 Hub 失败时，需自备镜像或提前把模型目录放到本地，再用本地路径当作 --model。

      其他加速器（了解即可）

      文档还提到 AMD ROCm、Intel GPU、TPU、以及社区维护的 Apple Silicon（vLLM-Metal）等。本教程不把它们当主路径。 需要时直接读官方对应安装页，不要假设 pip install vllm 在 Mac 原生上等于 CUDA 体验。

      常见问题

      nvidia-smi 找不到设备？ 先修驱动 / WSL GPU，再装 Python 包。

      导入时报 CUDA / PyTorch 版本冲突？ 新建 venv；不要先 pip install torch 再装另一个 CUDA 标签的 vLLM。

      只有 CPU？ 可以读后续章节理解 API，但不要期待「生产吞吐」。日常对话用 Ollama。

      权限与共享内存？ Docker 部署见 Docker，常用 --ipc=host。

      下一步

      评论