【大模型:部署】--使用VLLM架构部署本地大模型

在本地或私有云部署大语言模型（LLM）时，我们常面临一个痛点：显存占用高、推理吞吐低。传统的 HuggingFace Transformers 推理速度较慢，而 TensorRT-LLM 等方案虽然快但环境配置极其复杂。

vLLM 的出现打破了这一僵局。它凭借核心的 PagedAttention 技术，实现了：

• 🚀 高吞吐：比 HuggingFace Transformers 快 14-24 倍，接近 TensorRT-LLM 性能。
• 💾 显存优化：通过分页内存管理，大幅减少 KV Cache 的显存浪费，支持更长上下文和更大 Batch Size。
• 🔌 易用性：无缝兼容 HuggingFace 模型生态，支持 OpenAI API 格式，开箱即用。

本文将带你从零开始，使用 vLLM 在本地完成大模型的高性能部署。

官方文档：使用 vLLM - vLLM - vLLM 文档

论文：2309.06180 Efficient Memory Management for Large Language Model Serving with PagedAttention

github：https://github.com/vllm-project/vllm

目录

1.VLLM--框架简介

2.VLLM--安装部署

2.1.创建环境

2.2.下载模型

2.3.启动服务

2.4.测试连接

2.5.参数解析

[1. 模型与权重加载](#1. 模型与权重加载)

[2. 并行与分布式](#2. 并行与分布式)

[3. 上下文长度与序列调度](#3. 上下文长度与序列调度)

[4. 显存与 KV Cache 管理](#4. 显存与 KV Cache 管理)

[5. 多模态](#5. 多模态)

[6. 工具调用 (Function Calling)](#6. 工具调用 (Function Calling))

[7. 网络与服务](#7. 网络与服务)

[8. 生成与采样默认值](#8. 生成与采样默认值)

[9. 性能调优与调试](#9. 性能调优与调试)

---

1.VLLM--框架简介

vLLM （Virtual Large Language Model）是一个开源的大语言模型（LLM）高性能推理与服务框架 。它由加州大学伯克利分校 RISELab 团队于 2023 年开发，核心目标是解决 LLM 推理过程中显存利用率低、吞吐量瓶颈两大难题，刚兴趣的可以拜读论文

借鉴操作系统虚拟内存分页机制：

1. 将 KV Cache 切分为固定大小的 Block（类似内存页）
2. Block 之间无需物理连续，通过 Block Table 进行逻辑映射
3. 按需动态分配，几乎消除碎片
4. 支持跨请求 Block 共享（如相同 System Prompt 只需存储一份）

📊 效果：显存浪费降至 <4%，相同显存可容纳更多并发请求，吞吐量提升 2-24 倍。

2.VLLM--安装部署

• 操作系统：Linux
• Python: 3.10 -- 3.13

2.1.创建环境

conda create --name vllm python=3.11 -y
conda activate vllm

pip install vllm

2.2.下载模型

可以直接到开源网站下载：

模型库首页 · 魔搭社区

HF-Mirror

直接下载模型到服务器上面

2.3.启动服务

创建文件 start_vllm_Qwen-VL-8B.sh

运行：

#!/bin/bash

# 1. 指定使用的显卡（例如使用 4 张 GPU：0, 1, 2, 3）
export CUDA_VISIBLE_DEVICES=4,5,6,7

# 2. 避免 transformers 联网加载超时
export TRANSFORMERS_OFFLINE=1
export HF_DATASETS_OFFLINE=1

# 💡 建议保留：验证 NCCL 确实走了 P2P 路径（确认后可移除）
export NCCL_DEBUG=INFO

#GPU4-7 同 NUMA PIX 连接，P2P 正常，不禁用以获得最佳带宽
export NCCL_P2P_DISABLE=1  #可以删除

#单机无完整 IB 栈，必须禁用
export NCCL_IB_DISABLE=1

# 3. 指定模型本地路径
MODEL_PATH="/home/newuser002/guoyuping/Qwen/"

# 4. 启动 vLLM API 服务
python -m vllm.entrypoints.openai.api_server \
    --model ${MODEL_PATH} \
    --host 0.0.0.0 \
    --port 8000 \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.85 \
    --trust-remote-code \
    --max-num-seqs 128 \                  # 1. 允许同时批处理的最大序列数（提升并发吞吐）
    --max-num-batched-tokens 16384 \     # 2. 增大单次 Prefetch 的 Token 批处理上限
    --max-model-len 40960 \
    --limit-mm-per-prompt '{"image": 6}' \
    --kv-cache-dtype fp8 \
    --enable-auto-tool-choice \
    --tool-call-parser hermes \
    --default-chat-template-kwargs '{"enable_thinking": false}'

然后cd到目录下运行：

./start_vllm_Qwen-VL-8B.sh

这样的就是运行成功了

2.4.测试连接

支持openai的接口：

from openai import OpenAI

client = OpenAI(base_url="http://ip:8000/v1", api_key="EMPTY")

response = client.chat.completions.create(
    model="/home/newuser002/guoyuping/Qwen/",  # 与启动脚本中的 MODEL_PATH 一致
    messages=[{"role": "user", "content": "用一句话介绍杭州"}],
    stream=True,
)

print("=== 文本对话流式输出 ===")
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print("\n")

2.5.参数解析

1. 模型与权重加载

参数	类型	默认值	说明
--model	str	必填	模型路径（本地目录或 HF Hub ID）。vLLM 以此作为 API 中的 model 字段匹配名
--trust-remote-code	flag	False	允许执行模型仓库中的自定义 Python 代码。Qwen/Yi/GLM 等模型必加
--served-model-name	str/list	None	API 对外暴露的模型别名，可与 --model 不同，支持多个别名
--tokenizer	str	None	单独指定 tokenizer 路径，默认复用 --model 路径
--tokenizer-mode	str	auto	tokenizer 加载模式：auto / slow / mistral
--revision	str	None	HF Hub 模型的 git revision / branch / tag
--code-revision	str	None	远程代码的 git revision
--tokenizer-revision	str	None	tokenizer 的 git revision
--quantization / -q	str	None	量化方法：awq / gptq / fp8 / bitsandbytes 等
--dtype / -dt	str	auto	模型权重数据类型：auto / half / float16 / bfloat16 / float32
--load-format	str	auto	权重加载格式：auto / pt / safetensors / npcache / dummy
--download-dir	str	None	HF 模型下载缓存目录
--enforce-eager	flag	False	禁用 CUDA Graph，使用 eager 模式。调试用，生产环境会降低性能

2. 并行与分布式

参数	类型	默认值	说明
--tensor-parallel-size / -tp	int	1	张量并行 GPU 数量。必须与 CUDA_VISIBLE_DEVICES 指定的卡数一致
--pipeline-parallel-size / -pp	int	1	流水线并行层数。通常仅多机部署时使用
--data-parallel-size / -dp	int	1	数据并行副本数（vLLM ≥0.7 支持）
--distributed-executor-backend	str	auto	分布式后端：auto / mp / ray
--worker-use-ray	flag	False	(已废弃) 使用 Ray 作为 worker 管理器
--max-parallel-loading-workers	int	None	并行加载权重的 worker 数，大模型可加速启动

3. 上下文长度与序列调度

参数	类型	默认值	说明
--max-model-len	int	None	最大上下文窗口长度。限制此值可减少 KV Cache 预分配显存
--max-num-seqs	int	256	调度器允许同时处理的最大并发请求数
--max-num-batched-tokens	int	None	Prefill 阶段单次迭代最大 Token 数。增大可提升吞吐，但增加首字延迟
--max-logprobs	int	20	API 允许返回的最大 logprobs 数量
--enable-prefix-caching	flag	False	开启前缀缓存，相同 system prompt 的请求可复用 KV Cache
--disable-sliding-window	flag	False	禁用滑动窗口注意力，强制使用全量 KV Cache
--rope-scaling	json	None	RoPE 位置编码缩放配置（JSON 字符串）
--rope-theta	float	None	覆盖模型默认的 RoPE theta 值

4. 显存与 KV Cache 管理

参数	类型	默认值	说明
--gpu-memory-utilization	float	0.9	GPU 显存用于 KV Cache + 激活值的比例。降低可防 OOM
--kv-cache-dtype	str	auto	KV Cache 数据类型：auto / fp8 / fp8_e5m2 / fp8_e4m3。FP8 可节省约 50% KV Cache 显存
--block-size	int	16	KV Cache 物理块大小（Token 数）。影响内存碎片率
--num-gpu-blocks-override	int	None	手动指定 GPU KV Cache 块数，跳过自动 profiling
--swap-space	int	4	CPU Swap 空间大小（GB），用于 KV Cache 换出
--cpu-offload-gb	float	0	CPU 卸载 KV Cache 的大小（GB）
--enable-chunked-prefill	flag	False	分块预填充，长 Prompt 可降低峰值显存并减少 Decode 抢占

5. 多模态

参数	类型	默认值	说明
--limit-mm-per-prompt	json	{}	每种模态每请求最大数量，如 '{"image": 6, "video": 2}'
--mm-processor-kwargs	json	{}	传递给多模态预处理器的额外参数
--disable-mm-preprocessor-cache	flag	False	禁用多模态预处理结果缓存

6. 工具调用 (Function Calling)

参数	类型	默认值	说明
--enable-auto-tool-choice	flag	False	启用原生工具调用解析引擎
--tool-call-parser	str	None	解析器类型：hermes / llama3_json / mistral / qwen25 等
--chat-template	str	None	自定义 Jinja2 chat template 文件路径
--default-chat-template-kwargs	json	{}	注入 chat template 的默认变量，如 '{"enable_thinking": false}'
--enable-reasoning	flag	False	启用推理/思考模式（部分模型支持）
--reasoning-parser	str	None	思考内容解析器

7. 网络与服务

参数	类型	默认值	说明
--host	str	localhost	监听地址。0.0.0.0 表示所有网卡
--port	int	8000	服务端口
--api-key	str	None	设置 API Key 校验，不设置则无鉴权
--cors-allowed-origins	list	*	CORS 允许的源
--ssl-certfile	str	None	HTTPS 证书文件路径
--ssl-keyfile	str	None	HTTPS 私钥文件路径
--root-path	str	""	反向代理子路径前缀
--middleware	str/list	\[\]	自定义 ASGI 中间件模块路径
--uvicorn-log-level	str	info	Uvicorn 日志级别

8. 生成与采样默认值

参数	类型	默认值	说明
--default-generation-config	str	None	默认生成配置 JSON 文件路径
--guided-decoding-backend	str	auto	结构化输出后端：auto / outlines / lm-format-enforcer / xgrammar
--logits-processor-pattern	str	None	允许使用的自定义 LogitsProcessor 正则白名单

9. 性能调优与调试

参数	类型	默认值	说明
--seed	int	0	随机种子
--disable-log-requests	flag	False	关闭请求日志，高并发时减少 IO 开销
--disable-log-stats	flag	False	关闭定期统计日志
--engine-use-ray	flag	False	(已废弃) 引擎进程使用 Ray
--disable-custom-all-reduce	flag	False	禁用自定义 AllReduce kernel，回退 NCCL
--compilation-config / -O	json/int	None	Torch Compile 优化级别：0(关) / 1 / 2 / 3
--speculative-model	str	None	投机解码草稿模型路径
--num-speculative-tokens	int	None	投机解码步数
--speculative-method	str	None	投机解码方法：draft_model / medusa / eagle

💡 参数版本提示

以上参数基于 vLLM ≥ 0.7.x 整理。不同版本间参数可能有增删改名（如 --enable-auto-tool-choice 在 0.6.x 引入，--data-parallel-size 在 0.7+ 引入）。建议通过以下命令查看你所安装版本的完整参数列