在本地或私有云部署大语言模型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 PagedAttentiongithubhttps://github.com/vllm-project/vllm目录1.VLLM--框架简介2.VLLM--安装部署2.1.创建环境2.2.下载模型2.3.启动服务2.4.测试连接2.5.参数解析1. 模型与权重加载2. 并行与分布式3. 上下文长度与序列调度4. 显存与 KV Cache 管理5. 多模态6. 工具调用 (Function Calling)7. 网络与服务8. 生成与采样默认值9. 性能调优与调试1.VLLM--框架简介vLLMVirtual Large Language Model是一个开源的大语言模型LLM高性能推理与服务框架。它由加州大学伯克利分校 RISELab 团队于 2023 年开发核心目标是解决 LLM 推理过程中显存利用率低、吞吐量瓶颈两大难题刚兴趣的可以拜读论文借鉴操作系统虚拟内存分页机制将 KV Cache 切分为固定大小的Block类似内存页Block 之间无需物理连续通过 Block Table 进行逻辑映射按需动态分配几乎消除碎片支持跨请求Block 共享如相同 System Prompt 只需存储一份效果显存浪费降至 4%相同显存可容纳更多并发请求吞吐量提升 2-24 倍。2.VLLM--安装部署操作系统LinuxPython: 3.10 -- 3.132.1.创建环境conda create --name vllm python3.11 -y conda activate vllm pip install vllm2.2.下载模型可以直接到开源网站下载模型库首页 · 魔搭社区HF-Mirror直接下载模型到服务器上面2.3.启动服务创建文件 start_vllm_Qwen-VL-8B.sh运行#!/bin/bash # 1. 指定使用的显卡例如使用 4 张 GPU0, 1, 2, 3 export CUDA_VISIBLE_DEVICES4,5,6,7 # 2. 避免 transformers 联网加载超时 export TRANSFORMERS_OFFLINE1 export HF_DATASETS_OFFLINE1 # 建议保留验证 NCCL 确实走了 P2P 路径确认后可移除 export NCCL_DEBUGINFO #GPU4-7 同 NUMA PIX 连接P2P 正常不禁用以获得最佳带宽 export NCCL_P2P_DISABLE1 #可以删除 #单机无完整 IB 栈必须禁用 export NCCL_IB_DISABLE1 # 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_urlhttp://ip:8000/v1, api_keyEMPTY) response client.chat.completions.create( model/home/newuser002/guoyuping/Qwen/, # 与启动脚本中的 MODEL_PATH 一致 messages[{role: user, content: 用一句话介绍杭州}], streamTrue, ) print( 文本对话流式输出 ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue) print(\n)2.5.参数解析1. 模型与权重加载参数类型默认值说明--modelstr必填模型路径本地目录或 HF Hub ID。vLLM 以此作为 API 中的model字段匹配名--trust-remote-codeflagFalse允许执行模型仓库中的自定义 Python 代码。Qwen/Yi/GLM 等模型必加--served-model-namestr/listNoneAPI 对外暴露的模型别名可与--model不同支持多个别名--tokenizerstrNone单独指定 tokenizer 路径默认复用--model路径--tokenizer-modestrautotokenizer 加载模式auto/slow/mistral--revisionstrNoneHF Hub 模型的 git revision / branch / tag--code-revisionstrNone远程代码的 git revision--tokenizer-revisionstrNonetokenizer 的 git revision--quantization/-qstrNone量化方法awq/gptq/fp8/bitsandbytes等--dtype/-dtstrauto模型权重数据类型auto/half/float16/bfloat16/float32--load-formatstrauto权重加载格式auto/pt/safetensors/npcache/dummy--download-dirstrNoneHF 模型下载缓存目录--enforce-eagerflagFalse禁用 CUDA Graph使用 eager 模式。调试用生产环境会降低性能2. 并行与分布式参数类型默认值说明--tensor-parallel-size/-tpint1张量并行 GPU 数量。必须与CUDA_VISIBLE_DEVICES指定的卡数一致--pipeline-parallel-size/-ppint1流水线并行层数。通常仅多机部署时使用--data-parallel-size/-dpint1数据并行副本数vLLM ≥0.7 支持--distributed-executor-backendstrauto分布式后端auto/mp/ray--worker-use-rayflagFalse(已废弃) 使用 Ray 作为 worker 管理器--max-parallel-loading-workersintNone并行加载权重的 worker 数大模型可加速启动3. 上下文长度与序列调度参数类型默认值说明--max-model-lenintNone最大上下文窗口长度。限制此值可减少 KV Cache 预分配显存--max-num-seqsint256调度器允许同时处理的最大并发请求数--max-num-batched-tokensintNonePrefill 阶段单次迭代最大 Token 数。增大可提升吞吐但增加首字延迟--max-logprobsint20API 允许返回的最大 logprobs 数量--enable-prefix-cachingflagFalse开启前缀缓存相同 system prompt 的请求可复用 KV Cache--disable-sliding-windowflagFalse禁用滑动窗口注意力强制使用全量 KV Cache--rope-scalingjsonNoneRoPE 位置编码缩放配置JSON 字符串--rope-thetafloatNone覆盖模型默认的 RoPE theta 值4. 显存与 KV Cache 管理参数类型默认值说明--gpu-memory-utilizationfloat0.9GPU 显存用于 KV Cache 激活值的比例。降低可防 OOM--kv-cache-dtypestrautoKV Cache 数据类型auto/fp8/fp8_e5m2/fp8_e4m3。FP8 可节省约 50% KV Cache 显存--block-sizeint16KV Cache 物理块大小Token 数。影响内存碎片率--num-gpu-blocks-overrideintNone手动指定 GPU KV Cache 块数跳过自动 profiling--swap-spaceint4CPU Swap 空间大小GB用于 KV Cache 换出--cpu-offload-gbfloat0CPU 卸载 KV Cache 的大小GB--enable-chunked-prefillflagFalse分块预填充长 Prompt 可降低峰值显存并减少 Decode 抢占5. 多模态参数类型默认值说明--limit-mm-per-promptjson{}每种模态每请求最大数量如{image: 6, video: 2}--mm-processor-kwargsjson{}传递给多模态预处理器的额外参数--disable-mm-preprocessor-cacheflagFalse禁用多模态预处理结果缓存6. 工具调用 (Function Calling)参数类型默认值说明--enable-auto-tool-choiceflagFalse启用原生工具调用解析引擎--tool-call-parserstrNone解析器类型hermes/llama3_json/mistral/qwen25等--chat-templatestrNone自定义 Jinja2 chat template 文件路径--default-chat-template-kwargsjson{}注入 chat template 的默认变量如{enable_thinking: false}--enable-reasoningflagFalse启用推理/思考模式部分模型支持--reasoning-parserstrNone思考内容解析器7. 网络与服务参数类型默认值说明--hoststrlocalhost监听地址。0.0.0.0表示所有网卡--portint8000服务端口--api-keystrNone设置 API Key 校验不设置则无鉴权--cors-allowed-originslist*CORS 允许的源--ssl-certfilestrNoneHTTPS 证书文件路径--ssl-keyfilestrNoneHTTPS 私钥文件路径--root-pathstr反向代理子路径前缀--middlewarestr/list[]自定义 ASGI 中间件模块路径--uvicorn-log-levelstrinfoUvicorn 日志级别8. 生成与采样默认值参数类型默认值说明--default-generation-configstrNone默认生成配置 JSON 文件路径--guided-decoding-backendstrauto结构化输出后端auto/outlines/lm-format-enforcer/xgrammar--logits-processor-patternstrNone允许使用的自定义 LogitsProcessor 正则白名单9. 性能调优与调试参数类型默认值说明--seedint0随机种子--disable-log-requestsflagFalse关闭请求日志高并发时减少 IO 开销--disable-log-statsflagFalse关闭定期统计日志--engine-use-rayflagFalse(已废弃) 引擎进程使用 Ray--disable-custom-all-reduceflagFalse禁用自定义 AllReduce kernel回退 NCCL--compilation-config/-Ojson/intNoneTorch Compile 优化级别0(关) / 1 / 2 / 3--speculative-modelstrNone投机解码草稿模型路径--num-speculative-tokensintNone投机解码步数--speculative-methodstrNone投机解码方法draft_model/medusa/eagle参数版本提示以上参数基于vLLM ≥ 0.7.x整理。不同版本间参数可能有增删改名如--enable-auto-tool-choice在 0.6.x 引入--data-parallel-size在 0.7 引入。建议通过以下命令查看你所安装版本的完整参数列
【大模型:部署】--使用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 PagedAttentiongithubhttps://github.com/vllm-project/vllm目录1.VLLM--框架简介2.VLLM--安装部署2.1.创建环境2.2.下载模型2.3.启动服务2.4.测试连接2.5.参数解析1. 模型与权重加载2. 并行与分布式3. 上下文长度与序列调度4. 显存与 KV Cache 管理5. 多模态6. 工具调用 (Function Calling)7. 网络与服务8. 生成与采样默认值9. 性能调优与调试1.VLLM--框架简介vLLMVirtual Large Language Model是一个开源的大语言模型LLM高性能推理与服务框架。它由加州大学伯克利分校 RISELab 团队于 2023 年开发核心目标是解决 LLM 推理过程中显存利用率低、吞吐量瓶颈两大难题刚兴趣的可以拜读论文借鉴操作系统虚拟内存分页机制将 KV Cache 切分为固定大小的Block类似内存页Block 之间无需物理连续通过 Block Table 进行逻辑映射按需动态分配几乎消除碎片支持跨请求Block 共享如相同 System Prompt 只需存储一份效果显存浪费降至 4%相同显存可容纳更多并发请求吞吐量提升 2-24 倍。2.VLLM--安装部署操作系统LinuxPython: 3.10 -- 3.132.1.创建环境conda create --name vllm python3.11 -y conda activate vllm pip install vllm2.2.下载模型可以直接到开源网站下载模型库首页 · 魔搭社区HF-Mirror直接下载模型到服务器上面2.3.启动服务创建文件 start_vllm_Qwen-VL-8B.sh运行#!/bin/bash # 1. 指定使用的显卡例如使用 4 张 GPU0, 1, 2, 3 export CUDA_VISIBLE_DEVICES4,5,6,7 # 2. 避免 transformers 联网加载超时 export TRANSFORMERS_OFFLINE1 export HF_DATASETS_OFFLINE1 # 建议保留验证 NCCL 确实走了 P2P 路径确认后可移除 export NCCL_DEBUGINFO #GPU4-7 同 NUMA PIX 连接P2P 正常不禁用以获得最佳带宽 export NCCL_P2P_DISABLE1 #可以删除 #单机无完整 IB 栈必须禁用 export NCCL_IB_DISABLE1 # 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_urlhttp://ip:8000/v1, api_keyEMPTY) response client.chat.completions.create( model/home/newuser002/guoyuping/Qwen/, # 与启动脚本中的 MODEL_PATH 一致 messages[{role: user, content: 用一句话介绍杭州}], streamTrue, ) print( 文本对话流式输出 ) for chunk in response: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue) print(\n)2.5.参数解析1. 模型与权重加载参数类型默认值说明--modelstr必填模型路径本地目录或 HF Hub ID。vLLM 以此作为 API 中的model字段匹配名--trust-remote-codeflagFalse允许执行模型仓库中的自定义 Python 代码。Qwen/Yi/GLM 等模型必加--served-model-namestr/listNoneAPI 对外暴露的模型别名可与--model不同支持多个别名--tokenizerstrNone单独指定 tokenizer 路径默认复用--model路径--tokenizer-modestrautotokenizer 加载模式auto/slow/mistral--revisionstrNoneHF Hub 模型的 git revision / branch / tag--code-revisionstrNone远程代码的 git revision--tokenizer-revisionstrNonetokenizer 的 git revision--quantization/-qstrNone量化方法awq/gptq/fp8/bitsandbytes等--dtype/-dtstrauto模型权重数据类型auto/half/float16/bfloat16/float32--load-formatstrauto权重加载格式auto/pt/safetensors/npcache/dummy--download-dirstrNoneHF 模型下载缓存目录--enforce-eagerflagFalse禁用 CUDA Graph使用 eager 模式。调试用生产环境会降低性能2. 并行与分布式参数类型默认值说明--tensor-parallel-size/-tpint1张量并行 GPU 数量。必须与CUDA_VISIBLE_DEVICES指定的卡数一致--pipeline-parallel-size/-ppint1流水线并行层数。通常仅多机部署时使用--data-parallel-size/-dpint1数据并行副本数vLLM ≥0.7 支持--distributed-executor-backendstrauto分布式后端auto/mp/ray--worker-use-rayflagFalse(已废弃) 使用 Ray 作为 worker 管理器--max-parallel-loading-workersintNone并行加载权重的 worker 数大模型可加速启动3. 上下文长度与序列调度参数类型默认值说明--max-model-lenintNone最大上下文窗口长度。限制此值可减少 KV Cache 预分配显存--max-num-seqsint256调度器允许同时处理的最大并发请求数--max-num-batched-tokensintNonePrefill 阶段单次迭代最大 Token 数。增大可提升吞吐但增加首字延迟--max-logprobsint20API 允许返回的最大 logprobs 数量--enable-prefix-cachingflagFalse开启前缀缓存相同 system prompt 的请求可复用 KV Cache--disable-sliding-windowflagFalse禁用滑动窗口注意力强制使用全量 KV Cache--rope-scalingjsonNoneRoPE 位置编码缩放配置JSON 字符串--rope-thetafloatNone覆盖模型默认的 RoPE theta 值4. 显存与 KV Cache 管理参数类型默认值说明--gpu-memory-utilizationfloat0.9GPU 显存用于 KV Cache 激活值的比例。降低可防 OOM--kv-cache-dtypestrautoKV Cache 数据类型auto/fp8/fp8_e5m2/fp8_e4m3。FP8 可节省约 50% KV Cache 显存--block-sizeint16KV Cache 物理块大小Token 数。影响内存碎片率--num-gpu-blocks-overrideintNone手动指定 GPU KV Cache 块数跳过自动 profiling--swap-spaceint4CPU Swap 空间大小GB用于 KV Cache 换出--cpu-offload-gbfloat0CPU 卸载 KV Cache 的大小GB--enable-chunked-prefillflagFalse分块预填充长 Prompt 可降低峰值显存并减少 Decode 抢占5. 多模态参数类型默认值说明--limit-mm-per-promptjson{}每种模态每请求最大数量如{image: 6, video: 2}--mm-processor-kwargsjson{}传递给多模态预处理器的额外参数--disable-mm-preprocessor-cacheflagFalse禁用多模态预处理结果缓存6. 工具调用 (Function Calling)参数类型默认值说明--enable-auto-tool-choiceflagFalse启用原生工具调用解析引擎--tool-call-parserstrNone解析器类型hermes/llama3_json/mistral/qwen25等--chat-templatestrNone自定义 Jinja2 chat template 文件路径--default-chat-template-kwargsjson{}注入 chat template 的默认变量如{enable_thinking: false}--enable-reasoningflagFalse启用推理/思考模式部分模型支持--reasoning-parserstrNone思考内容解析器7. 网络与服务参数类型默认值说明--hoststrlocalhost监听地址。0.0.0.0表示所有网卡--portint8000服务端口--api-keystrNone设置 API Key 校验不设置则无鉴权--cors-allowed-originslist*CORS 允许的源--ssl-certfilestrNoneHTTPS 证书文件路径--ssl-keyfilestrNoneHTTPS 私钥文件路径--root-pathstr反向代理子路径前缀--middlewarestr/list[]自定义 ASGI 中间件模块路径--uvicorn-log-levelstrinfoUvicorn 日志级别8. 生成与采样默认值参数类型默认值说明--default-generation-configstrNone默认生成配置 JSON 文件路径--guided-decoding-backendstrauto结构化输出后端auto/outlines/lm-format-enforcer/xgrammar--logits-processor-patternstrNone允许使用的自定义 LogitsProcessor 正则白名单9. 性能调优与调试参数类型默认值说明--seedint0随机种子--disable-log-requestsflagFalse关闭请求日志高并发时减少 IO 开销--disable-log-statsflagFalse关闭定期统计日志--engine-use-rayflagFalse(已废弃) 引擎进程使用 Ray--disable-custom-all-reduceflagFalse禁用自定义 AllReduce kernel回退 NCCL--compilation-config/-Ojson/intNoneTorch Compile 优化级别0(关) / 1 / 2 / 3--speculative-modelstrNone投机解码草稿模型路径--num-speculative-tokensintNone投机解码步数--speculative-methodstrNone投机解码方法draft_model/medusa/eagle参数版本提示以上参数基于vLLM ≥ 0.7.x整理。不同版本间参数可能有增删改名如--enable-auto-tool-choice在 0.6.x 引入--data-parallel-size在 0.7 引入。建议通过以下命令查看你所安装版本的完整参数列
