linux系统使用vllm搭建本地模型的详细步骤

目录

• 第一步：环境准备与依赖安装
• 1. 硬件与系统要求
• 2. 安装 Miniconda 与创建环境
• 3. 安装 PyTorch 与 vLLM
• 第二步：下载模型
• 1. 通过 ModelScope 下载（推荐国内用户）
• 🎯 方法一：使用 –local_dir 参数（推荐）
• ⚙️ 方法二：设置环境变量 MODELSCOPE_CACHE
• 2. 通过 HuggingFace 下载
• 第三步：启动 OpenAI 兼容的 API 服务
• 1. 基础启动命令
• 2. 参数详解
• 3. 高级配置
• 第四步：验证与调用
• 1. 使用 curl 测试
• 2. 使用 Python 调用
• 第五步：性能优化与故障排查
• 1. 常见问题
• 2. 压测工具

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

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

• 操作系统：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。

如果你的系统 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

根据你的 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（国内较快）上的模型。

# 安装 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 参数并指定你想要存放模型的文件夹路径即可。

基本命令格式：

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，之后所有下载的模型都会默认存放到这个目录下。

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

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/ 路径下。

# 安装 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

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

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

参数	说明	建议值
–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 中展示的模型名称	自定义名称，方便调用

多卡并行：如果你的模型很大（如 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 的日志。

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

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)

• 显存不足 (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 支持）。

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 的本地大模型服务。

到此这篇关于linux系统使用vllm搭建本地模型的详细步骤的文章就介绍到这了,更多相关vllm搭建本地模型内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！