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

  发布时间:2026-04-23 16:03:21   作者:Yaphetshl   我要评论
在 Linux 系统上使用 vLLM 搭建本地模型服务,是当前生产环境中非常主流的方案,相比于 Ollama,vLLM 通过 PagedAttention 等技术,在高并发场景下的吞吐量和显存管理上表现更优,下面就来详细的介绍vllm搭建本地模型的详细步骤,感兴趣的可以了解一下

在 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-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

后台运行:使用 nohuptmux 保持服务在后台运行。

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

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

相关文章

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

    在 Linux 系统上使用 vLLM 搭建本地模型服务,是当前生产环境中非常主流的方案,相比于 Ollama,vLLM 通过 PagedAttention 等技术,在高并发场景下的吞吐量和显存管理上表现
    2026-04-23
  • Windows上部署Hermes-Agent的实现步骤

    本文详细介绍了如何在Windows系统上部署和使用Hermes-Agent,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一
    2026-04-23
  • Hermes Agent迁移到外部硬盘的详细教程

    本文详细介绍了将OS系统HermesAgent将数据迁移到外部硬盘以节省内置SSD空间的过程,步骤包括停止HermesAgent、确认外部硬盘状态、移动数据、创建建建符号链接等确保迁移后的
    2026-04-23
  • 用Hermes Agent的profile方式来实现多Agent的配置指南

    本文介绍了使用HermesAgent的profile方式实现多Agent配置的方法,通过创建独立的profile目录,每个profile拥有独立的配置文件、内存、会话、技能等,保证了Agent间的隔离性,文
    2026-04-22
  • Mac从零部署Hermes Agent并接入飞书的保姆级教程

    Hermes Agent 是 Nous Research 开源的 AI Agent 框架,和 OpenClaw 同类,最大特点是会自我成长,本文基于实际踩坑过程整理,从 Hermes 安装到飞书 Bot + 飞书 CLI 完整打通,
    2026-04-22
  • Hermes Agent vs OpenClaw:2026年两大AI Agent框架深度对比分析

    OpenClaw作为开源社区宠儿,Hermes Agent作为企业级解决方案,两者在设计理念、架构实现和适用场景上存在根本性差异,本文就对二者进行了深度的对比分析,需要的朋友可以参考
    2026-04-21
  • VSCode GitHub Copilot安装与使用技巧完全指南

    Copilot是种基于智能的代码动补全具,由OpenAI和GitHub共同开发,它使智能算 法来分析代码库,并根据上下和编程语的语法提,动成质量的代码,这篇文章主要介绍了VSCode GitHub C
    2026-04-21
  • Hermes Agent工具集大全:20+工具让你的AI无所不能

    工具集是Hermes Agent区别于普通AI聊天工具的关键,通过调用各种工具,Hermes Agent不仅仅是一个对话伙伴,而是一个能够实际操作系统的智能代理,本文整理了20+个工具集,覆
    2026-04-20
  • Hermes Agent 配置大全

    文章详细介绍了HermesAgent的`config.yaml`核心配置文件,包括模型选择、工具启用、安全策略、消息网关等配置项,提供了示例配置和最佳实践建议,感兴趣的可以了解一下
    2026-04-20
  • Hermes-Agent 部署Telegram/Discord机器人的全过程(多平台远程控制)

    本文介绍了Hermes-Agent部署Telegram/Discord机器人的全过程,包括创建机器人、配置Hermes对接、启动机器人网关、测试机器人等功能,并提供进阶配置(如后台持久化运行、配置
    2026-04-20

最新评论