vLLM本地部署教程

简介

vLLM 是当前最热门的大模型推理引擎之一，专为提升 LLM 部署效率而生。（适用 Windows/x64。）

一、核心痛点与软件介绍

想把开源大模型跑在自己的机器上、随时调用，却总被部署过程劝退？这份vLLM本地部署教程就是为你准备的。vLLM是一个开源的大模型推理引擎，简单说，它让你在自己的服务器或工作站上启动一个兼容OpenAI接口的推理服务，把模型权重加载进去就能对外提供对话、生成能力，省去依赖云端API的开销与数据外发的顾虑。它适合想自建AI应用的开发者、需要私有化部署的企业技术团队，以及对推理成本敏感的研究者。与同类方案相比，其核心优势在于PagedAttention技术——对显存中的KV缓存做分页管理，显著提升显存利用率与并发吞吐，让同一张卡承载更多请求。

二、环境要求与官方下载

vLLM基于Python生态，安装前请先在机器上准备好Python环境，具体可支持的Python版本以官网实际版本为准；若走GPU加速路线，还需要匹配的CUDA驱动与工具链，NVIDIA显卡型号支持范围请以官方仓库公布的兼容列表为准。系统最低要求（OS版本、CPU、内存）官网未公布统一参数，建议以官网为准，并预留充足的显存用于加载模型权重。

获取渠道很简单：前往软件官网获取——官方文档站为 https://docs.vllm.ai/ ，官方仓库为 https://github.com/vllm-project/vllm 。本页下载区也展示了真实下载通道（GitHub Release 的 wheel 包），具体以页面实际提供为准。

三、保姆级安装步骤

方式一：pip 安装（最常用）

1. 打开终端（Windows 用 PowerShell，macOS/Linux 用系统自带终端），输入 python --version 回车，确认 Python 已就绪。
2. 建议先建虚拟环境：输入 python -m venv vllm-env 回车，再按系统执行激活命令（Windows：vllm-env\Scripts\activate；macOS/Linux：source vllm-env/bin/activate）。
3. 输入 pip install vllm 回车，等待依赖自动拉取安装完成。若需要指定某个已发布版本，可前往官方仓库 Releases 页面查看可用版本号后用 pip install vllm==版本号 安装。
4. 安装结束后输入 python -c "import vllm; print(vllm.__version__)" 验证是否成功导入。

方式二：源码构建：克隆官方仓库后进入目录，按仓库内说明安装构建依赖再执行安装，适合需要改代码或追新特性的用户，具体步骤以官方仓库说明为准。

关于平台支持：官方 Release 页面提供了 Linux 与 macOS（arm64）的 wheel 包；Windows 端暂无对应安装包，建议在 WSL2 或 Linux 环境中部署；macOS 端下载对应 wheel 后在终端用 pip 安装即可，无需 dmg 拖拽安装流程（该项目不提供图形安装镜像）。若 pip 安装时报 CUDA 相关错误（如提示找不到 CUDA_HOME），说明当前环境缺 GPU 编译依赖，可改用官方 Docker 镜像运行，或在 CPU 模式下安装，详见下文 FAQ。

四、首次启动快速配置

安装完成后，用一条命令即可拉起推理服务：

1. 在终端输入 vllm serve 模型名称或本地路径 回车（例如从 HuggingFace 拉取的开源模型标识），首次运行会自动下载权重，请耐心等待。
2. 服务默认监听本地端口，启动成功后终端会打印 OpenAI 兼容接口地址，可用浏览器或 curl 访问验证。
3. 关键参数按需调整：--max-model-len 控制上下文长度（显存紧张时调小）；--tensor-parallel-size 指定多卡并行数；--served-model-name 自定义对外暴露的模型名；--gpu-memory-utilization 控制显存占用比例。所有参数以当前版本官方文档为准。
4. 环境变量方面，可在启动前通过系统环境变量指定模型缓存目录（如 HF_HOME）避免重复下载，具体变量名以官方文档为准。

五、常见安装报错解决方案（FAQ）

症状1：pip install 报错提示找不到 CUDA_HOME、CUDA must be available
这是在 macOS 或无 CUDA 环境下直接编译导致的。解决动作：改用官方 Docker 镜像运行，或确认本机是否有可用的 CUDA 工具链；纯 CPU 环境请参考官方文档选择对应的安装方式。

症状2：在 RTX 5080/5090（Blackwell 架构）上启动报编译或内核错误
社区反馈显示该架构需要 CUDA 12.8 与 PyTorch 2.6 环境才能正常编译运行。解决动作：按官方文档 Issue 中给出的容器启动方式准备环境，或使用官方 Docker 镜像，避免手动编译踩坑。

症状3：启动服务时报 Sinks are only supported in FlashAttention 3 断言错误
该问题在 RTX 5090、4090 等显卡上均有用户反馈，与所选模型的注意力实现不匹配有关。解决动作：调整启动参数中的注意力后端选择（如关闭或切换 FlashAttention 版本），或升级到官方仓库中已修复该问题的版本，具体参数写法以官方文档为准。

六、优缺点

优点

• PagedAttention 显存分页管理，显著提升显存利用率与并发吞吐。
• 提供 OpenAI 兼容接口，已有 OpenAI SDK 的应用几乎零改动即可切换到本地服务。
• 开源协议为 Apache-2.0，商用友好，可自由修改分发。
• 社区活跃度高，历史版本迭代频繁，新模型（DeepSeek、Kimi、Qwen、Llama 系列等）跟进速度快。
• 提供 Docker 镜像与 pip 两种主流安装路径，上手门槛相对可控。

缺点

• 对 GPU 与 CUDA 环境依赖较强，纯 CPU 或 macOS 环境部署体验受限，部分场景报错较多。
• Windows 原生支持缺失，需借助 WSL2 或 Linux 环境，对新手不够友好。
• 显存要求高，大参数模型需要高端显卡或多卡并行，硬件门槛不低。

七、历史版本

• v0.31.0（2026-10-05）：DeepSeek-V4.1-Flash 性能优化，FlashMLA mega attention 与 NVFP4 压缩 KV 缓存成为 SM100 默认配置，含 717 次提交、307 位贡献者。下载：https://github.com/vllm-project/vllm/releases/download/v0.31.0/vllm-0.31.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.30.0（2026-09-22）：新增 DeepSeek-V4.1-Flash 模型支持，KV 缓存经 MXFP8 存储优化，含 762 次提交。下载：https://github.com/vllm-project/vllm/releases/download/v0.30.0/vllm-0.30.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.29.0（2026-09-09）：Model Runner V2 成为所有模型默认执行路径，新增 CUDA graph 内存分析用于 KV 缓存自动 sizing。下载：https://github.com/vllm-project/vllm/releases/download/v0.29.0/vllm-0.29.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.28.0（2026-08-26）：Kimi-K3 全栈性能优化，引入 Decode Context Parallel 支持与融合 FlashKDA 内核。下载：https://github.com/vllm-project/vllm/releases/download/v0.28.0/vllm-0.28.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.27.1（2026-08-11）：v0.27.0 的补丁版本，支持量化 DSpark Markov heads。下载：https://github.com/vllm-project/vllm/releases/download/v0.27.1/vllm-0.27.1%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.27.0（2026-08-10）：Kimi K3 完整支持落地，含核心模型文件、Python 与 Rust 前端。下载：https://github.com/vllm-project/vllm/releases/download/v0.27.0/vllm-0.27.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.26.0（2026-07-27）：新增 Inkling 模型家族支持，含分段 CUDA graph 与 Hopper FA4 相对注意力。下载：https://github.com/vllm-project/vllm/releases/download/v0.26.0/vllm-0.26.0%2Bcpu-cp312-cp312-macosx_11_0_arm64.whl
• v0.25.1（2026-07-14）：补丁版本，修复无系统 FFmpeg 时 TorchCodec 阻塞模型启动的问题。下载：https://github.com/vllm-project/vllm/releases/download/v0.25.1/vllm-0.25.1%2Bcpu-cp38-abi3-manylinux_2_34_aarch64.whl
• v0.25.0（2026-07-11）：Model Runner V2 成为所有稠密模型默认路径，含 558 次提交。下载：https://github.com/vllm-project/vllm/releases/download/v0.25.0/vllm-0.25.0%2Bcpu-cp38-abi3-manylinux_2_34_aarch64.whl
• v0.24.0（2026-06-29）：新增 MiniMax-M3 模型支持，含 BF16/FP8 indexer、MXFP4 与 FP8 稀疏 GQA 支持。下载：https://github.com/vllm-project/vllm/releases/download/v0.24.0/vllm-0.24.0%2Bcpu-cp38-abi3-manylinux_2_34_aarch64.whl

八、社区高频问题与已知坑

• macOS 上 pip install 报 Cannot find CUDA_HOME：症状为安装即失败。思路：该报错源于默认安装路径尝试编译 CUDA 相关组件，Mac 用户可改用 Docker 或 CPU 安装路径，具体以官方文档 Issue 讨论为准。
• DeepSeek-V4-Flash 系列在 Ampere（A100/A800、RTX 30xx）上无法运行：症状为模型加载失败。思路：官方仓库已建 Issue 跟踪 SM8x 适配进度，暂不支持时可选择其他已适配型号的检查点。
• 单次启动仅支持一个模型，多模型切换需自行处理：社区有 Feature 请求希望支持多模型下载与切换，当前需分别启动服务或借助编排工具实现。
• Llama 3.1 系列的分块预填与前缀缓存、滑动窗口、multi-LoRA 不兼容：需使用后几项特性时，按官方博客说明调整启动参数关闭分块预填。

九、同类软件推荐

如果你在对比选型，可一并了解 llama.cpp、TensorRT-LLM、Text Generation Inference（TGI）等同类大模型推理方案，结合自身硬件与场景选择。

同类软件推荐

以下是与本文软件定位相近、可相互替代的同类工具，便于按需选型：

• llama.cpp（本站已收录，点击查看下载与教程）
• TensorRT-LLM（同类热门，建议结合官网评估）
• Text Generation Inference（同类热门，建议结合官网评估）

核心功能

• 本页保留官方站点入口作为下载来源，并在可用时提供网盘转存通道，链接与提取码随页面展示。
• 围绕「vLLM本地部署教程」这一需求给出可执行的获取与部署步骤，减少试错成本。
• 提供版本与架构比对，避免装错版本或选错系统架构导致无法运行。

使用场景

• 需要在本机部署或重装 vLLM本地部署教程（当前版本），并希望先核对版本与文件信息再获取的场景。
• 使用 vLLM本地部署教程 时遇到官方站点访问不稳定或速度较慢，需要国内网盘通道作为替代的情况。
• 需要在多台设备使用同一 vLLM本地部署教程 版本（当前版本），便于统一环境与后续排查时。

注意事项

• 部署 vLLM本地部署教程 时路径建议避免中文与空格，可减少部分写入失败的概率。
• 若安全软件出现拦截提示，请先确认来源为本页收录渠道后再决定是否放行。

安装与校验

• 通过本页「夸克/百度 网盘」通道转存到自己的网盘后再取回文件，可避免直接下载中断造成的文件不完整。
• 解压后先确认 vLLM本地部署教程 主程序能否正常启动，再决定是否替换原有版本。
• 如遇安全软件拦截，请先确认来源为本页收录渠道，再决定是否放行。

官方来源获取步骤

• 第 1 步：打开本页给出的官方站点入口，核对页面域名与下方收录信息是否一致。
• 第 2 步：在官方页面的下载区选择与本机 Windows/x64 匹配的安装包，注意区分 32 位与 64 位。
• 第 3 步：下载完成后核对文件名与文件大小，再执行安装或解压；建议解压到 C:\\Tools 这类不含中文与空格的路径。