如何使用vllm本地部署大模型

本文介绍如何在本地 (Linux 环境) 使用 vLLM 部署多模态大模型 Qwen/Qwen3-VL-2B-Instruct，并通过 OpenAI 兼容接口进行推理测试。流程包含：

1. 环境配置
2. 模型下载
3. 启动本地服务
4. 客户端测试
5. 常见问题与解决方案

1. 环境配置

1.1 vLLM 安装

首先做好环境隔离，创建一个名为 vllmenv 的 conda 环境并激活，然后在该环境中安装 vLLM 主体。

conda create -n vllmenv python=3.11 -y
conda activate vllmenv
pip install vllm

1.2 flash-attn 版本确定及安装（可选）

为了确保 attention 走 FlashAttention，加速省显存，可以安装 flash-attn。flash-attn 的 wheel 必须与 Torch 版本、CUDA 版本、CXX11 ABI、Python ABI、架构等匹配，否则容易出现安装失败、符号缺失、运行时崩溃等问题，因此需要先在本机环境里获取这些关键参数，再去选择正确的 wheel

执行以下命令获取关键环境参数：

# 查看是否启用 CXX11 ABI
python -c "import torch; print(torch._C._GLIBCXX_USE_CXX11_ABI)"

# 查看 PyTorch 和 CUDA 信息
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.version.cuda)"

# 获取 Python 版本标记
python -c "import sys; print(f'cp{sys.version_info.major}{sys.version_info.minor}')"

# 查看架构
uname -m

对应输出示例：

True  # True or Flase, 决定 wheel 名称中的 abiTRUE/abiFALSE
2.9.0+cu128  # PyTorch 2.9.0 + CUDA 12.8
True
12.8  # CUDA 12.8
cp311
x86_64

得到配置信息之后，前往下列页面去找对应的 .whl 文件：

FlashAttention Releases 页面
FlashAttention Releases 页面 2 （更新）

这里为了对应上述的配置信息，下载了 flash_attn_3-3.0.0b1+20251028.cu128torch290cxx11abitrue.b3f1b6-cp39-abi3-linux_x86_64.whl

然后进行安装：

pip install flash_attn_3-3.0.0b1+20251028.cu128torch290cxx11abitrue.b3f1b6-cp39-abi3-linux_x86_64.whl

这里配置信息和 whl 文件的关系如下：

Note： 当 wheel 的标签中有 abi3，表示这个 wheel 使用的是 Python 3.8+ 通用 ABI，因此它兼容所有 Python 3.8+ 版本（3.8 / 3.9 / 3.10 / 3.11 / 3.12 都能用）。

2. 模型下载

hf download repo_id

说明：repo_id 替换为对应 Hugging Face 仓库，例如 Qwen/Qwen3-VL-2B-Instruct。

3. 启动本地服务

使用 vLLM 启动 OpenAI 兼容 API 服务：

CUDA_VISIBLE_DEVICES=0,1,2,3 python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-VL-2B-Instruct \
  --host 0.0.0.0 \
  --port 8888 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9 \
  --tensor-parallel-size 4

参数说明：

• CUDA_VISIBLE_DEVICES=0,1,2,3 指定使用哪些 GPU
• --model Hugging Face repo id（默认从 HF 拉取）
• --host 与 --port 服务监听地址与端口
• --max-model-len 4096 最大上下文长度
• --gpu-memory-utilization 0.9 vLLM 可用显存比例
• --tensor-parallel-size 4 张量并行大小，通常与 GPU 数一致

4. 客户端测试

使用 OpenAI Python SDK 请求 vLLM 的 OpenAI 兼容接口，传入单张图片 URL 与 query：

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8888/v1", api_key="EMPTY")

model = "Qwen/Qwen3-VL-2B-Instruct"
image_url = "https://your-image-url.com/test.jpg"
query = "请描述这张图，并指出最重要的三个细节。"

resp = client.chat.completions.create(
    model=model,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "image_url", "image_url": {"url": image_url}},
                {"type": "text", "text": query},
            ],
        }
    ],
    max_tokens=512,
    temperature=0.2,
)

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

说明：

• base_url 对应第 3 步启动的服务地址
• 如果服务端未设置鉴权，api_key 可随便填（常见写法是 EMPTY）

5. 常见问题

5.1 Hugging Face 模型下载卡进度条

在进行模型下载的过程中可能会遇到模型下载进度条卡到一个节点的情况，这个时候可以考虑设置 HF_HUB_DISABLE_XET：

export HF_HUB_DISABLE_XET=1
hf download deepseek-ai/deepseek-vl2-tiny

export HF_HUB_DISABLE_XET=1 的作用是：强制 Hugging Face Hub 的下载与上传不要走 hf-xet（Xet Storage 后端与客户端），即使你的环境里已经装了 hf-xet 也不用它，而是回退到 huggingface_hub 的非 Xet 下载路径。这个开关设置的初衷是 huggingface_hub 会在检测到 hf-xet 可用时自动启用它（因为它通常更快，支持基于分块去重的传输），但如果遇到 Xet 相关的兼容、卡住、环境问题，就可以用这个变量显式禁用。

5.2 使用 ModelScope 进行模型下载

vLLM 默认使用 Hugging Face 对应的 repo id。如果使用 ModelScope 进行模型下载，则需要做一些改动：

export VLLM_USE_MODELSCOPE=True
CUDA_VISIBLE_DEVICES=0,1 python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen3-VL-2B-Instruct \
  --hf-overrides '{"architectures":["Qwen3VLForConditionalGeneration"]}' \
  --host 0.0.0.0 --port 8888 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9 \
  --tensor-parallel-size 2

这里的 --hf_overrides 本质上就是给 config.json 打补丁，让 vLLM 能正确解析模型架构。具体这个模型 --hf-overrides 这里的设置应该是什么，可以参考 list-of-multimodal-language-models

参考文献

[1] vLLM 0.11.0部署Qwen3-VL-4B实战指南
[2] vLLM Docs: modelscope

Updated on January 16, 2026, the first post in 2026. Wish everything fine in the new year. 🎇