linux系統(tǒng)使用vllm搭建本地模型的詳細(xì)步驟

發(fā)布時間：2026-04-23 16:03:21 作者：Yaphetshl

在 Linux 系統(tǒng)上使用 vLLM 搭建本地模型服務(wù)，是當(dāng)前生產(chǎn)環(huán)境中非常主流的方案,相比于 Ollama，vLLM 通過 PagedAttention 等技術(shù)，在高并發(fā)場景下的吞吐量和顯存管理上表現(xiàn)更優(yōu),下面就來詳細(xì)的介紹vllm搭建本地模型的詳細(xì)步驟，感興趣的可以了解一下

第一步：環(huán)境準(zhǔn)備與依賴安裝

vLLM 對 CUDA 版本和 Python 環(huán)境有特定要求。為了不污染系統(tǒng)環(huán)境，強(qiáng)烈建議使用 Conda 或 Python 虛擬環(huán)境。

1. 硬件與系統(tǒng)要求

操作系統(tǒng)：Linux (Ubuntu, Redhat, openEuler 等)。
GPU：NVIDIA GPU，計算能力 7.0 及以上（如 V100, T4, RTX 30/40/50 系列， A100/H100 等）。
顯存：根據(jù)模型大小決定。例如，32B 模型建議 24GB+ 顯存（如 RTX 3090/4090）。
CUDA 版本：建議 12.1 或 12.4。

2. 安裝 Miniconda 與創(chuàng)建環(huán)境

如果你的系統(tǒng) 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
# 配置環(huán)境變量
echo 'export PATH="/path/to/conda_base/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 創(chuàng)建新的虛擬環(huán)境 (Python 3.10 ~ 3.12 均可)
conda create -n vllm_env python=3.10 -y
conda activate vllm_env

3. 安裝 PyTorch 與 vLLM

根據(jù)你的 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（國內(nèi)較快）上的模型。

1. 通過 ModelScope 下載（推薦國內(nèi)用戶）

# 安裝 modelscope
pip install modelscope
# 下載模型示例：Qwen2.5-7B-Instruct 或 DeepSeek-R1
# 模型會默認(rèn)下載到 ~/.cache/modelscope/hub/models/
modelscope download --model Qwen/Qwen2.5-7B-Instruct
# 或者下載更大參數(shù)的模型
modelscope download --model deepseek-ai/DeepSeek-R1-Distill-Qwen-32B

使用 modelscope download 命令下載模型到指定目錄，主要有兩種方法：使用 --local_dir 參數(shù)直接指定，或者通過設(shè)置環(huán)境變量來改變默認(rèn)路徑。

?? 方法一：使用 --local_dir 參數(shù)（推薦）

這是最直接的方法，通過添加 --local_dir 參數(shù)并指定你想要存放模型的文件夾路徑即可。

基本命令格式：

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/

?? 方法二：設(shè)置環(huán)境變量 MODELSCOPE_CACHE

如果你不希望每次下載都指定路徑，可以設(shè)置環(huán)境變量 MODELSCOPE_CACHE，之后所有下載的模型都會默認(rèn)存放到這個目錄下。

臨時設(shè)置（僅當(dāng)前終端會話有效）：

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

永久設(shè)置（添加到 Shell 配置文件，如 ~/.bashrc）：

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

設(shè)置后，模型默認(rèn)會下載到 /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 服務(wù)

vLLM 提供了一個類 OpenAI 的 API 服務(wù)，方便直接接入現(xiàn)有的客戶端（如 FastGPT, Chatbox, 或你的代碼）。

1. 基礎(chǔ)啟動命令

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. 參數(shù)詳解

參數(shù)	說明	建議值
--model	模型路徑（本地路徑或 HuggingFace ID）	必填
--tensor-parallel-size	張量并行數(shù)，即使用的 GPU 數(shù)量	如果有 4 張卡設(shè)為 4
--gpu-memory-utilization	顯存利用率	0.85 ~ 0.95
--max-model-len	最大上下文長度	根據(jù)顯存調(diào)整，顯存不足可適當(dāng)降低
--dtype	數(shù)據(jù)類型	bfloat16 (推薦) 或 float16
--served-model-name	API 中展示的模型名稱	自定義名稱，方便調(diào)用

3. 高級配置

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

# 假設(shè)有 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

穩(wěn)定模式 (V0 引擎)：如果遇到顯存不足（OOM）或啟動失敗，可以嘗試禁用新版 V1 引擎。

export VLLM_USE_V1=0

后臺運(yùn)行：使用 nohup 或 tmux 保持服務(wù)在后臺運(yùn)行。

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

第四步：驗證與調(diào)用

服務(wù)啟動后，會看到類似 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 調(diào)用

from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"  # vLLM 默認(rèn)不需要 API Key
)
response = client.chat.completions.create(
    model="Qwen2.5-7B",
    messages=[{"role": "user", "content": "寫一首關(guān)于秋天的詩"}]
)
print(response.choices[0].message.content)

第五步：性能優(yōu)化與故障排查

1. 常見問題

顯存不足 (OOM)：
- 降低 --gpu-memory-utilization 到 0.6 或 0.7。
- 降低 --max-model-len。
- 如果使用的是消費(fèi)級顯卡（如 RTX 4090），可以考慮關(guān)閉 ECC（錯誤校驗）來釋放少量顯存。
啟動報錯 ImportError：通常是由于 CUDA 版本與 PyTorch 不匹配。建議嚴(yán)格按照 pip install vllm 的依賴自動安裝，或重建虛擬環(huán)境。
速度慢：
- 增加 --tensor-parallel-size 利用多卡并行。
- 確保開啟了 --dtype bfloat16（如果 GPU 支持）。

2. 壓測工具

vLLM 自帶壓測腳本，可以用來測試部署后的吞吐量。

# 安裝依賴
pip install pandas datasets
# 運(yùn)行壓測 (需要提前下載 benchmark 腳本)
python3 vllm/benchmarks/benchmark_serving.py \
    --backend vllm \
    --model /path/to/model \
    --dataset-name sharegpt \
    --request-rate inf \
    --num-prompts 100

通過以上步驟，你應(yīng)該能在 Linux 服務(wù)器上成功運(yùn)行一個高性能的、兼容 OpenAI API 的本地大模型服務(wù)。

到此這篇關(guān)于linux系統(tǒng)使用vllm搭建本地模型的詳細(xì)步驟的文章就介紹到這了,更多相關(guān)vllm搭建本地模型內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！