vLLM 快速上手教程：3 步从零到首次生成，新手最完整的入门路径

vLLM 快速上手教程：3 步从零到首次生成，新手最完整的入门路径

【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm

vLLM是一款开源的高吞吐、低显存消耗的LLM 推理与服务引擎，由加州大学伯克利分校发起，现已成为最活跃的 AI 开源项目之一。它支持 200 多种模型架构，提供 PagedAttention、连续批处理等核心加速技术，并内置 OpenAI 兼容的 API 服务器。本教程带你用 3 步从零完成vLLM 安装、首次文本生成和 API 服务部署，新手也能轻松上手。

为什么选择 vLLM？

在开始之前，先用 30 秒了解 vLLM 的核心优势：

vLLM 的推理引擎内部将任务拆分为输入处理、调度、模型执行和输出处理四个模块，理解这个结构有助于你快速定位问题：

第 1 步：30 秒完成 vLLM 安装

vLLM 支持 Linux 环境，Python 版本要求 3.10 – 3.13。推荐使用 uv（一个超快的 Python 环境管理工具）来创建环境并安装：

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

💡--torch-backend=auto会根据你机器上的 CUDA 驱动版本自动选择合适的 PyTorch 版本，避免新手常见的版本不匹配问题。

如果习惯用 pip，也可以直接执行pip install vllm。安装完成后，运行以下命令验证是否成功：

vllm --help

只要看到命令行帮助信息，就说明vLLM 安装已完成。AMD GPU 用户可参考官方安装文档 docs/getting_started/installation/gpu.md 中的 ROCm 章节。

第 2 步：离线推理，生成你的第一段文字

vLLM 的第一个入口是LLM类，适合在本地脚本中批量生成文本。官方示例脚本在 examples/basic/offline_inference/basic.py，核心逻辑只有 3 行：

from vllm import LLM, SamplingParams llm = LLM(model="facebook/opt-125m") # 1. 加载模型 outputs = llm.generate(prompts, sampling_params) # 2. 批量生成 print(outputs[0].outputs[0].text) # 3. 打印结果

逐步解释一下：

1. 加载模型：LLM(model=...)会自动从 Hugging Face 下载模型并初始化推理引擎。首次运行需要联网下载，建议使用较小的模型（如facebook/opt-125m，仅约 0.5GB）用于入门体验。
2. 设置采样参数：SamplingParams(temperature=0.8, top_p=0.95)控制生成随机性。temperature越低输出越确定，top_p控制候选词范围。
3. 批量生成：llm.generate()一次性处理多条 prompt，这正是 vLLM 高吞吐优势体现的地方。

📌 如果你使用的是对话模型（如 Qwen、Llama-3），建议改用llm.chat()方法传入消息列表，vLLM 会自动应用模型自带的对话模板，效果更稳定。

模型代码的入口实现位于 vllm/entrypoints/llm.py，想深入了解的同学可以顺着源码看。

第 3 步：一条命令启动 OpenAI 兼容 API 服务

这是 vLLM 最受新手欢迎的能力——用一条命令把任意模型变成OpenAI 兼容的 API 服务器：

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

服务默认启动在http://localhost:8000，你可以用--host和--port修改地址。此时用curl测试一下：

# 查看已加载的模型 curl http://localhost:8000/v1/models # 发起一次聊天补全请求 curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen/Qwen2.5-1.5B-Instruct", "messages": [ {"role": "user", "content": "用一句话介绍 vLLM"} ] }'

因为协议与 OpenAI 完全兼容，任何现有的 OpenAI 客户端代码只需把base_url指向本地即可无缝切换，官方客户端示例见 examples/basic/online_serving/openai_chat_completion_client.py：

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")

进阶：接入图形化聊天界面

有了 API 服务，你就可以把它接入各种现成的聊天前端，零代码拥有自己的 AI 助手界面：

常见选择包括 Open WebUI、Dify、AnythingLLM 等，只需将 API 地址填为http://localhost:8000/v1即可，部署细节可参考 docs/deployment/ 目录下的各框架文档。

新手常见问题速查

❓ 启动时报显存不足怎么办？调小--max-model-len（最大上下文长度），或对大模型使用量化版本（vLLM 原生支持 FP8、AWQ、GPTQ 等格式）。

❓ 支持哪些硬件？NVIDIA CUDA、AMD ROCm、Intel XPU、Google TPU 及主流 CPU 均可运行，对应安装方式在 docs/getting_started/installation/README.md 中有分平台说明。

❓ 模型从哪里下载？默认从 Hugging Face 拉取；国内用户可设置环境变量VLLM_USE_MODELSCOPE=True切换为 ModelScope 源。

❓ 离线推理和在线服务怎么选？批量跑固定 prompt 选离线推理（LLM类）；需要被其他应用调用、多人访问则选在线服务（vllm serve）。两者入口关系如下图所示：

下一步学习路径

恭喜！你已完成 vLLM 从安装到部署的全部 3 步 🎉 接下来可以按兴趣深入：

• 📘 完整入门文档：docs/getting_started/quickstart.md
• 🧩 架构原理详解：docs/design/arch_overview.md
• 📡 在线服务进阶配置：docs/serving/online_serving/
• 🧪 更多上手示例：examples/basic/

核心路径回顾：安装 →LLM类离线生成 →vllm serve启动 API 服务。掌握这条主线后，量化、LoRA、结构化输出、多机并行等高级功能都将成为你顺手可得的工具。

【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm