其他

关注公众号 jb51net

关闭
AI > 其他 >

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

Yaphetshl

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

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

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

1. 硬件与系统要求

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-nameAPI 中展示的模型名称自定义名称，方便调用

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. 常见问题

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

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