在 Linux 系统上使用 vLLM 搭建本地模型服务，是当前生产环境中非常主流的方案。相比于 Ollama，vLLM 通过 PagedAttention 等技术，在高并发场景下的吞吐量和显存管理上表现更优。

以下是一份完整的实战指南，帮助你从零开始搭建。

---

第一步：环境准备与依赖安装

vLLM 对 CUDA 版本和 Python 环境有特定要求。为了不污染系统环境，强烈建议使用 Conda 或 Python 虚拟环境。

1. 硬件与系统要求

• 操作系统：Linux (Ubuntu, Redhat, openEuler 等)。
• GPU：NVIDIA GPU，计算能力 7.0 及以上（如 V100, T4, RTX 30/40/50 系列， A100/H100 等）。
• 显存：根据模型大小决定。例如，32B 模型建议 24GB+ 显存（如 RTX 3090/4090）。
• CUDA 版本：建议 12.1 或 12.4。

2. 安装 Miniconda 与创建环境

如果你的系统 Python 版本低于 3.9，建议先安装 Miniconda。

# 下载 Miniconda (Python 3.9 版本)
wget https://repo.anaconda.com/miniconda/Miniconda3-py39_25.1.1-2-Linux-x86_64.sh
bash Miniconda3-py39_25.1.1-2-Linux-x86_64.sh -p /path/to/conda_base

# 配置环境变量
echo 'export PATH="/path/to/conda_base/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 创建新的虚拟环境 (Python 3.10 ~ 3.12 均可)
conda create -n vllm_env python=3.10 -y
conda activate vllm_env

3. 安装 PyTorch 与 vLLM

根据你的 CUDA 版本，选择合适的 PyTorch 安装命令。这里以 CUDA 12.4 为例。

# 安装 PyTorch (官方推荐)
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# 直接安装 vLLM (会同步安装依赖)
pip install vllm

注意：对于较新的显卡（如 RTX 5090），可能需要从源码编译或安装 nightly 版本。

---

第二步：下载模型

vLLM 支持 HuggingFace 和 ModelScope（国内较快）上的模型。

1. 通过 ModelScope 下载（推荐国内用户）

# 安装 modelscope
pip install modelscope

# 下载模型示例：Qwen2.5-7B-Instruct 或 DeepSeek-R1
# 模型会默认下载到 ~/.cache/modelscope/hub/models/
modelscope download --model Qwen/Qwen2.5-7B-Instruct
# 或者下载更大参数的模型
modelscope download --model deepseek-ai/DeepSeek-R1-Distill-Qwen-32B

使用 modelscope download 命令下载模型到指定目录，主要有两种方法：使用 --local_dir 参数直接指定，或者通过设置环境变量来改变默认路径。

🎯 方法一：使用 --local_dir 参数（推荐）

这是最直接的方法，通过添加 --local_dir 参数并指定你想要存放模型的文件夹路径即可。

基本命令格式：

modelscope download --model <模型ID> --local_dir <你想要的路径>

实际示例：下载 Qwen/Qwen2.5-7B-Instruct 到 /home/user/models 目录

modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /home/user/models/Qwen2.5-7B-Instruct

💡 小提示：这个命令会下载完整的模型到指定路径。如果你只想下载模型中的某个特定文件（比如配置文件 config.json），可以在命令中加上文件名：

modelscope download --model Qwen/Qwen2.5-7B-Instruct config.json --local_dir /home/user/models/

⚙️ 方法二：设置环境变量 MODELSCOPE_CACHE

如果你不希望每次下载都指定路径，可以设置环境变量 MODELSCOPE_CACHE，之后所有下载的模型都会默认存放到这个目录下。

临时设置（仅当前终端会话有效）：

export MODELSCOPE_CACHE=/home/user/my_model_cache
modelscope download --model Qwen/Qwen2.5-7B-Instruct

永久设置（添加到 Shell 配置文件，如 ~/.bashrc）：

echo "export MODELSCOPE_CACHE=/home/user/my_model_cache" >> ~/.bashrc
source ~/.bashrc
# 然后直接下载
modelscope download --model Qwen/Qwen2.5-7B-Instruct

设置后，模型默认会下载到 /home/user/my_model_cache/hub/models/ 路径下。

2. 通过 HuggingFace 下载

# 安装 huggingface_hub
pip install huggingface_hub

# 登录 (如果需要 gated 模型)
huggingface-cli login

# 下载模型
huggingface-cli download deepseek-ai/DeepSeek-R1-Distill-Qwen-32B --local-dir ./models/DeepSeek-R1-Distill-Qwen-32B

---

第三步：启动 OpenAI 兼容的 API 服务

vLLM 提供了一个类 OpenAI 的 API 服务，方便直接接入现有的客户端（如 FastGPT, Chatbox, 或你的代码）。

1. 基础启动命令

python -m vllm.entrypoints.openai.api_server \
    --model /root/.cache/modelscope/hub/models/Qwen/Qwen2.5-7B-Instruct \
    --served-model-name Qwen2.5-7B \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.9 \
    --max-model-len 4096 \
    --port 8000 \
    --host 0.0.0.0

2. 参数详解

参数	说明	建议值
--model	模型路径（本地路径或 HuggingFace ID）	必填
--tensor-parallel-size	张量并行数，即使用的 GPU 数量	如果有 4 张卡设为 4
--gpu-memory-utilization	显存利用率	0.85 ~ 0.95
--max-model-len	最大上下文长度	根据显存调整，显存不足可适当降低
--dtype	数据类型	bfloat16 (推荐) 或 float16
--served-model-name	API 中展示的模型名称	自定义名称，方便调用

3. 高级配置

• 多卡并行：如果你的模型很大（如 72B），可以配置多卡推理。

  # 假设有 4 张 GPU
  export CUDA_VISIBLE_DEVICES=0,1,2,3
  python -m vllm.entrypoints.openai.api_server --model Qwen/Qwen2.5-72B-Instruct --tensor-parallel-size 4
  

• 稳定模式 (V0 引擎)：如果遇到显存不足（OOM）或启动失败，可以尝试禁用新版 V1 引擎。

  export VLLM_USE_V1=0
  

• 后台运行：使用 nohup 或 tmux 保持服务在后台运行。

  nohup python -m vllm.entrypoints.openai.api_server --model ... > vllm.log 2>&1 &
  

---

第四步：验证与调用

服务启动后，会看到类似 INFO: Uvicorn running on http://0.0.0.0:8000 的日志。

1. 使用 curl 测试

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

2. 使用 Python 调用

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"  # vLLM 默认不需要 API Key
)

response = client.chat.completions.create(
    model="Qwen2.5-7B",
    messages=[{"role": "user", "content": "写一首关于秋天的诗"}]
)

print(response.choices[0].message.content)

---

第五步：性能优化与故障排查

1. 常见问题

• 显存不足 (OOM)：
  • 降低 --gpu-memory-utilization 到 0.6 或 0.7。
  • 降低 --max-model-len。
  • 如果使用的是消费级显卡（如 RTX 4090），可以考虑关闭 ECC（错误校验）来释放少量显存。
• 启动报错 ImportError：通常是由于 CUDA 版本与 PyTorch 不匹配。建议严格按照 pip install vllm 的依赖自动安装，或重建虚拟环境。
• 速度慢：
  • 增加 --tensor-parallel-size 利用多卡并行。
  • 确保开启了 --dtype bfloat16（如果 GPU 支持）。

2. 压测工具

vLLM 自带压测脚本，可以用来测试部署后的吞吐量。

# 安装依赖
pip install pandas datasets

# 运行压测 (需要提前下载 benchmark 脚本)
python3 vllm/benchmarks/benchmark_serving.py \
    --backend vllm \
    --model /path/to/model \
    --dataset-name sharegpt \
    --request-rate inf \
    --num-prompts 100

通过以上步骤，你应该能在 Linux 服务器上成功运行一个高性能的、兼容 OpenAI API 的本地大模型服务。