下面是零基础小白也能看懂的 vLLM 私有化部署 Qwen 大模型 全流程指南，从环境搭建到调用测试，一步步带你完成。

官网：

vLLM

官网中文站：

欢迎来到 vLLM！ | vLLM 中文站

---

目录

一、前期准备：你需要什么

1. 硬件要求

2. 软件环境一览

二、安装 NVIDIA 驱动和 CUDA（裸机必做）

1. 安装 NVIDIA 驱动

2. 安装 CUDA（推荐 12.1）

三、安装 Miniconda 并创建虚拟环境

四、安装 vLLM

五、下载 Qwen 模型（挑选一个）

模型推荐（按显存需求从小到大）

方式 1：用 huggingface-cli 下载（需科学上网）

方式 2：用 modelscope 下载（国内网络友好）

六、启动 vLLM OpenAI 兼容 API 服务

七、测试 API 调用

1. 用 curl 测试

2. 用 Python 代码调用（openai 库）

八、进阶：后台运行与生产配置

让服务后台运行（使用 nohup）

调优建议

九、常见问题排查

十、总结

---

一、前期准备：你需要什么

1. 硬件要求

• GPU 显存：部署 7B 模型至少需要 16 GB 显存（如 RTX 4080/4090、A10、A100），如果部署 1.8B 或 0.5B 小模型，8 GB 显存即可。
• 内存：建议 32 GB 以上（加载模型时会占用）。
• 硬盘：模型文件约 15-20 GB，预留 50 GB 剩余空间。
• 操作系统：推荐 Ubuntu 22.04，也可用 Windows WSL2 或云 GPU 主机（如 AutoDL、恒源云）。

2. 软件环境一览

• Python 3.10 左右
• CUDA 12.1+（与 vLLM 官方预编译包匹配）
• NVIDIA 驱动（支持你的显卡）
• vLLM（核心推理引擎）
• 模型下载工具：huggingface_hub 或 modelscope

如果你使用云 GPU 厂商提供的镜像，通常已装好 NVIDIA 驱动和 CUDA，可跳到第四步开始。

---

二、安装 NVIDIA 驱动和 CUDA（裸机必做）

1. 安装 NVIDIA 驱动

先用 nvidia-smi 检查是否已有驱动。若无输出，执行：

sudo apt update
sudo apt install -y ubuntu-drivers-common
sudo ubuntu-drivers autoinstall
sudo reboot

重启后再运行 nvidia-smi，看到显卡信息和驱动版本即成功。

2. 安装 CUDA（推荐 12.1）

去 NVIDIA CUDA Toolkit 下载页 选择对应系统，按提示安装。例如 Ubuntu 22.04：

wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

安装时注意不要选择安装驱动（已经装过），其他默认勾选即可。
安装后把 CUDA 加入环境变量：

echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

验证：nvcc --version 应显示 CUDA 12.1。

---

三、安装 Miniconda 并创建虚拟环境

Miniconda 可以帮我们隔离 Python 环境，避免库冲突。

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

一路 yes，安装后重启终端或 source ~/.bashrc。

创建专用环境（Python 3.10）：

conda create -n vllm_qwen python=3.10 -y
conda activate vllm_qwen

---

四、安装 vLLM

vLLM 官网推荐直接用 pip 安装，省时省力（自动匹配 CUDA 版本）：

pip install vllm

注意：如果你之前自己编译过 CUDA，确保 CUDA 版本 ≥ 12.1，否则 pip 可能下载 CPU 版本。也可用更精确的安装命令：

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

验证安装：python -c "import vllm; print(vllm.__version__)"。

---

五、下载 Qwen 模型（挑选一个）

模型推荐（按显存需求从小到大）

模型	显存需求	下载地址 (HuggingFace)
Qwen2.5-0.5B-Instruct	~2 GB	Qwen/Qwen2.5-0.5B-Instruct
Qwen2.5-1.5B-Instruct	~4 GB	Qwen/Qwen2.5-1.5B-Instruct
Qwen2.5-7B-Instruct	~16 GB	Qwen/Qwen2.5-7B-Instruct
Qwen2.5-14B-Instruct	~30 GB	Qwen/Qwen2.5-14B-Instruct

方式 1：用 huggingface-cli 下载（需科学上网）

pip install huggingface_hub
huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./Qwen2.5-7B-Instruct

方式 2：用 modelscope 下载（国内网络友好）

下载方式1：通过命令下载

pip install modelscope
python -c "from modelscope import snapshot_download; snapshot_download('qwen/Qwen2.5-7B-Instruct', cache_dir='./Qwen2.5-7B-Instruct')"

下载完成后，记下模型的本地路径，比如 /home/yourname/Qwen2.5-7B-Instruct。

注意：ModelScope中提供了三种下载模型的方式，其中可以通过SDK方式下载：

编写文件downloads.py文件，添加如下代码：

from modelscope import snapshot_download
model_dir = snapshot_download('Qwen/Qwen3-8B',cache_dir='/root/autodl-tmp/modelss
/Qwen3-8B',revision='master')

然后运行download.py文件，执行如下命令：

python download.py

---

六、启动 vLLM OpenAI 兼容 API 服务

最简单的启动命令：

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5 \
    --max-model-len 8k \
    --gpu-memory-utilization 0.9

参数说明：

• --model：模型本地路径。
• --served-model-name：API 调用时的模型名，可自定义。
• --max-model-len：最大输入+输出 token 数，根据显存调整。
• --gpu-memory-utilization：显存占用上限比例（0.9 表示用满 90%）。

启动成功后会看到类似：

INFO:     Uvicorn running on http://0.0.0.0:8000

此时 API 服务已在 8000 端口运行。

可添加更多设置信息的启动命令:

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5 \
    --max-model-len 8k \
    --host 0.0.0.0 \
    --port 6006 \
    --dtype bfloat16 \
    --gpu-memory-utilization 0.9 \
    --enable-auto-tool-choice \
    --tool-call-parser hermes
    --enable-reasoning \
    --reasoning-parser deepseek_r1

运行命令后API服务已经在6006 端口运行

---

七、测试 API 调用

1. 用 curl 测试

curl http://localhost:6006/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5",
    "messages": [
      {"role": "user", "content": "你好，请用一句话介绍你自己"}
    ],
    "temperature": 0.7
  }'

正常返回 JSON 格式的对话结果。

2.访问大模型的API文档

浏览器中输入地址：http://localhost:6006/docs

2. 用 Python 代码调用（openai 库）

安装依赖：pip install openai

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="qwen2.5",
    messages=[{"role": "user", "content": "给我讲一个程序员笑话"}],
    temperature=0.7
)
print(response.choices[0].message.content)

---

八、进阶：后台运行与生产配置

让服务后台运行（使用 nohup）

nohup python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2.5-7B-Instruct \
    --served-model-name qwen2.5 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.9 > vllm.log 2>&1 &

查看日志：tail -f vllm.log

调优建议

• 多卡部署：加 --tensor-parallel-size 2 使用 2 块 GPU。
• 量化加速：若显存紧张，可加 --quantization awq（需模型为 AWQ 量化版）。
• 调整上下文长度：--max-model-len 8192 支持更长对话（会占用更多显存）。
• 生产环境建议用 systemd 或 docker 管理服务。

---

九、常见问题排查

现象	可能原因	解决
nvidia-smi 报错	驱动未正确安装	重装驱动，注意禁用 Nouveau
vLLM 提示 CUDA 不可用	pip 安装的 vLLM 不是 CUDA 版本	卸载重装，指定 --extra-index-url
显存不足 (OOM)	模型太大或上下文太长	降低 max-model-len，或换小模型，或使用量化版本
下载模型太慢	网络不通	用 modelscope 下载，或预先下载到本地
服务启动后 API 无响应	防火墙或端口占用	检查 lsof -i:8000，开放端口或换端口

---

十、总结

至此，你已经拥有了一个完全私有的 Qwen 大模型 API 服务，可以与任意前端（如 ChatBox、NextChat、Open WebUI）对接。整个流程的核心就是：

准备 GPU 机器 → 装驱动/CUDA → 装 vLLM → 下载模型 → 启动服务 → 调用 API

即使是零基础，跟着命令一步步走，也能在 1 小时内完成部署。祝你部署顺利！如果遇到具体问题，欢迎随时交流。