简介这是一份围绕大模型部署实战的开源资料包聚焦如何基于vLLM框架部署通义千问Qwen语言模型适合有Python基础、希望快速上手推理服务搭建的AI开发者和运维人员。包内共9个文件包括6个Python脚本、2张示意图和1份README说明其中vllm_server、vllm_client、vllm_wrapper、vllm_offline等脚本分别覆盖服务启动、客户端调用、封装对接与离线推理配合gradio_webui可快速搭建可视化交互界面。压缩包仅433KB结构紧凑流程教程从环境依赖、模型加载到接口测试与性能调优均有涉及。资料已有1488人学习内容经过筛选验证适合作为从源码到服务的完整参考模板帮助读者少走弯路。1. 用vLLM部署通义千问Qwen大语言模型先把账算清楚再动手基于vLLM部署通义千问Qwen大语言模型这件事听起来是一行命令的事实际落地时卡人的全是显存、上下文长度和并发调度这些细账。vLLM选对了Qwen从0.5B到72B能在一台或几台机器上跑成OpenAI兼容服务给RAG、Agent、内部工具链当底座选错了服务起不来、吞吐上不去、长对话崩全得靠日志猜。这篇文章面向两类人手里有卡想本地部署大模型并交付给团队调用的工程师以及正在比较vLLM和ollama、llama.cpp、SGLang这几个框架的选型者。我会把从选型到压测的全流程拆开写每步都能照做坑也一并标出来。2. 部署前先选型Qwen型号、vLLM版本和CUDA环境的三角关系部署大语言模型最忌讳一上来就pip install vllm然后随便拉一个模型开始跑。vLLM的调度策略、KVCache管理和量化支持都很吃环境和模型格式的匹配提前把这层关系理顺后面所有命令都是顺水推舟。选型就三件事选哪个Qwen、装哪个vLLM、从哪下模型。2.1 Qwen型号怎么选0.5B到72B的显存账本Qwen 2.5系列从0.5B一直排到72B选型的第一原则是先看手里显存再定模型。FP16精度下模型权重约占参数量的2倍字节7B模型权重大约15GB加上KVCache和中间激活24G单卡能跑但余量不大14B权重约28GB基本要40G卡起步32B权重约64GB单卡只有靠量化否则得上两张80G做张量并行。72B就别想单卡了至少四张A100/H100或者直接上AWQ量化把权重压到4bit。下表是我按FP16权重估算的选型参考不含KVCache和激活开销模型权重估算推荐显存常见场景Qwen2.5-0.5B-Instruct约1GB4~8G边缘设备、CPU兜底Qwen2.5-1.5B-Instruct约3GB8G简单对话、文本分类Qwen2.5-3B-Instruct约6GB12G轻量Agent、函数调用Qwen2.5-7B-Instruct约15GB24G本地部署的主流甜点Qwen2.5-14B-Instruct约28GB40G/A30需要更强推理质量Qwen2.5-32B-Instruct约64GB多卡或量化后40G高质量私有底座Qwen2.5-72B-Instruct约144GB多卡80G企业级大规模服务注意这里推荐的是Instruct版本它自带对话模板vLLM加载后会按模板组织prompt。Base版本是纯语言模型接对话服务还要自己拼模板和停词新手直接用Instruct最省事。至于上下文长度Qwen 2.5系列官方标称128K但本地部署能不能开满取决于KVCache预分配和显存余量这个在第3章参数部分细说。2.2 vLLM与CUDA版本版本差一档服务起不来vLLM是编译型依赖它对PyTorch和CUDA运行时的版本很敏感。最省事的做法是直接用官方Docker镜像镜像里CUDA、torch、vLLM三者已经匹配好如果选择pip安装先确认nvidia-smi显示的驱动能支撑目标CUDA版本再建虚拟环境装。比如CUDA 12.4要求驱动版本不低于525驱动太老torch能import但一加载模型就报CUDA error。# 第一步确认驱动和CUDA版本记录下nvidia-smi里的Driver Version nvidia-smi # 第二步新建Python虚拟环境避免和系统环境互相污染 python -m venv .venv source .venv/bin/activate # 第三步安装vLLM它会连带安装匹配的torch pip install vllm # 第四步验证vLLM能正常import并打印版本号 python -c import vllm; print(vllm.__version__)这四步里最容易翻车的是第三步pip为了满足依赖可能会把torch升级到和你驱动不匹配的版本。所以我的习惯是装完后立刻跑第四步如果import报CUDA相关错误先回退torch版本而不是去动驱动。驱动升级代价大、影响面广尽量通过固定vLLM版本和torch版本来匹配现有驱动这是生产环境更稳妥的做法。另外vLLM官方文档标注了每个版本对应的CUDA和Python版本范围安装前花两分钟对照一下能省掉后面一整天的排错。2.3 模型从哪下、下什么格式ModelScope与HuggingFace的取舍模型下载渠道直接决定你部署的顺畅程度。HuggingFace是模型最全的地方但国内网络环境下载大模型经常断流ModelScope上有Qwen官方账号同步的全部版本国内下载速度快很多而且命令行工具支持断点续传适合几GB到上百GB的模型。实际操作中我的默认选择是ModelScope除非需要某个只在HuggingFace上发布的第三方微调版本才考虑从HuggingFace拉。# 先安装ModelScope客户端 pip install modelscope # 下载Qwen2.5-7B-Instruct到当前目录 # --model指定仓库名--local_dir指定本地目录名 modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./Qwen2.5-7B-Instruct参数说明--local_dir如果不写模型会落到ModelScope的默认缓存目录部署时还要去翻缓存路径建议每次都显式指定。下载完成后检查目录里的config.json和safetensors文件是否齐全如果中断过重新执行同一条命令断点续传会自动补齐缺失分片。另外格式上要特别注意vLLM原生支持HuggingFace的safetensors格式和AWQ/GPTQ量化格式GGUF是ollama和llama.cpp用的格式不能直接喂给vLLM。如果你以前用ollama本地部署大模型比较多习惯了GGUF的方便换到vLLM时模型源要从头重新下这是很多人卡住的地方。3. 最小部署命令一行命令把Qwen部署成大模型服务选型做完下一步就是把模型跑起来。所谓项目源码和流程教程核心其实就是这一章的启动命令、参数配置和请求脚本把它们按顺序存下来就是一份完整可复用的部署方案。我会用Qwen2.5-7B-Instruct配合单张24G显卡演示最小可运行配置然后再把三个最容易改错的参数单独拆开讲。3.1 启动OpenAI兼容服务的最小命令vLLM提供了OpenAI兼容的API Server这意味着你原来写给GPT的代码只需要改base_url就能切到本地Qwen。启动命令如下# 最小启动命令在项目目录下执行 python -m vllm.entrypoints.openai.api_server \ --model ./Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b \ --host 0.0.0.0 \ --port 8000 \ --max-model-len 32768 \ --gpu-memory-utilization 0.9这段命令的逻辑--model指定模型目录本地路径和HuggingFace仓库名都可以--served-model-name是对外暴露的模型名客户端请求时model字段要和它一致--host 0.0.0.0让服务监听所有网卡这样局域网内其他机器也能访问--max-model-len控制最大上下文长度我设了32K而不是128K因为7B模型开满128K的KVCache会直接撑爆24G显存--gpu-memory-utilization设置显存利用率上限。--host 0.0.0.0是部署服务的常用做法但要注意安全如果机器有公网IP建议配合防火墙或内网环境使用。启动成功的标志是日志里出现Uvicorn running on http://0.0.0.0:8000同时会打印模型名称和GPU显存分配信息。新版vLLM也支持vllm serve短命令效果和上面一样但传参语法略有差异用vllm serve --help先看一眼再写。3.2 三个必调参数的边界max-model-len、gpu-memory-utilization和tensor-parallel-size这三个参数是vLLM部署大模型时最容易改出问题的我把它们的行为边界列成表对照着调会快很多。参数作用常见值调大后的代价max-model-len最大上下文字符数8192~32768KVCache按此预分配显存设太大直接OOMgpu-memory-utilizationvLLM可用的显存上限0.85~0.92接近1时挤占框架预留空间推理报错tensor-parallel-size张量并行卡数2/4/8卡间通信开销剧增小模型反而变慢max-model-len的原理是vLLM启动时按这个长度预分配KVCache不是按实际对话长度动态增长。所以你设64K但实际只用2K显存照样被预占掉。这也是为什么很多人部署Qwen时不敢开满128K因为7B模型在24G卡上开满128K权重加KVCache直接超了。实用做法是先在24G卡上从16384开始能稳定跑再往上加。gpu-memory-utilization设到0.95以上风险很大vLLM除了模型和KVCache还需要给CUDA context和框架本身留余量。低于0.8又浪费显存我一般默认0.9遇到多并发报显存错误再往0.85降。注意这个参数控制的是vLLM进程的显存水位如果同一张卡上还有别的任务要按比例调低。tensor-parallel-size只在多卡时用原理是把模型参数切到多张卡上并行计算。但7B这种规模的模型单卡能放下时加TP只会增加NCCL通信开销吞吐反而下降。这个参数的正确用法是模型单卡放不下时才开启比如32B模型在两张40G卡上设2。另外tensor-parallel-size必须整除实际卡数设错会在启动时报GPU vLLM tensor parallel size相关错误。3.3 用OpenAI兼容接口验收部署curl探活与Python请求服务起来后先别急着接业务用OpenAI客户端协议验一遍接口通不通。第一条命令探活看模型是否注册成功# 查看服务端注册的模型列表 curl http://localhost:8000/v1/models/v1/models会返回JSON列表里面包含你设置的qwen2.5-7b。如果返回404或空列表多半是--served-model-name拼写问题或者服务还没完全就绪。日志出现ready字样后再探活比较稳。接着发一个chat补全请求# 发送一条对话补全请求验证生成链路 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen2.5-7b, messages: [{role: user, content: 用一句话介绍vLLM}], max_tokens: 256, temperature: 0.7 }这个请求走的是OpenAI的chat协议vLLM内部会把messages按Qwen的chat模板拼装后送进模型。max_tokens限制生成长度temperature控制随机性这两个字段和OpenAI的含义完全一致你的业务代码几乎零改动就能切过来。如果返回一个带choices[0].message.content的JSON说明链路通了。接下来用Python脚本化验证方便后面集成到自动化测试里from openai import OpenAI # base_url指向vLLM服务api_key随意填vLLM默认不做鉴权 client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) resp client.chat.completions.create( modelqwen2.5-7b, messages[{role: user, content: 用一句话介绍vLLM}], max_tokens256, temperature0.7, ) print(resp.choices[0].message.content)这段代码里api_keyEMPTY是vLLM的默认行为它不校验key内容但字段必须带上否则openai客户端会报401。如果你后续要给服务加鉴权vLLM也支持通过--api-key参数开启简单校验生产环境建议开启不然内网里谁都能白嫖你的算力。部署验证到这里就算完成接下来要回答一个更关键的问题这个服务到底能扛多大并发、吞吐达不达标。4. 部署完了怎么验收吞吐、首Token延迟与并发压测三条线很多教程到服务启动成功就结束了但作为交付项目你还需要给团队一份性能数据否则别人不敢把流量切过来。这一章讲三条验收线单请求硬吞吐、并发表现、运行时监控。这三条线分别对应模型本身跑多快、服务扛不扛得住、以及瓶颈在哪。4.1 用vLLM自带的benchmark脚本打一遍硬吞吐vLLM安装包里带了吞吐基准脚本它绕过HTTP层直接驱动引擎测的是模型和框架的纯生成能力适合评估单机上限# 测硬吞吐100条prompt输入1024 token输出512 token python -m vllm.benchmark.benchmark_throughput \ --model ./Qwen2.5-7B-Instruct \ --input-len 1024 \ --output-len 512 \ --num-prompts 100 \ --trust-remote-code参数逻辑--input-len和--output-len模拟真实对话的长度分布--num-prompts控制并发prompt数量。脚本会在结束前打印Throughput: xx tokens/s这就是单机硬吞吐。比如Qwen2.5-7B-Instruct在单张24G卡上通常能跑到每秒几千token这个数字可以作为后续调优的基准线。如果脚本报No module named vllm.benchmark说明你的vLLM版本改了路径跑python -m vllm.benchmark --help看可用子命令或者直接升级到新版本。注意benchmark脚本和你实际服务的数字会有差距因为脚本不经过网络栈和OpenAI协议转换也不受max-num-seqs等调度参数限制。它的作用是快速验证硬件和框架本身有没有问题比如两张卡对比时一张卡吞吐异常低那肯定是散热或驱动问题而不是代码问题。4.2 自己写并发压测看调度排队和超时表现硬吞吐测完还要测服务在真实HTTP并发下的行为。核心指标是首Token延迟TTFT和每个请求的端到端耗时。下面这段脚本用AsyncOpenAI并发发20个请求统计总耗时和P50延迟import asyncio import time from openai import AsyncOpenAI # 异步客户端配合asyncio实现并发请求 client AsyncOpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, ) async def one_request(i: int): t0 time.time() resp await client.chat.completions.create( modelqwen2.5-7b, messages[{role: user, content: f第{i}个请求请只回复收到}], max_tokens64, temperature0.3, ) return time.time() - t0 async def main(): start time.time() times await asyncio.gather(*[one_request(i) for i in range(20)]) total time.time() - start times.sort() print(f总耗时: {total:.2f}s) print(fP50延迟: {times[len(times)//2]:.2f}s) print(f最慢请求: {times[-1]:.2f}s) asyncio.run(main())这段脚本的关节在于asyncio.gather会把20个请求同时打到vLLMvLLM的调度器收到后会按continuous batching策略把请求塞进同一个batch。判断部署质量的标准是总耗时接近单请求耗时的1.5到2倍算健康如果20个并发让总耗时变成单请求的10倍以上说明调度或显存已经到瓶颈。想要更细的首Token延迟数据可以把streamTrue打开用流式响应掐表算首包到达时间那才是用户真实感知的响应快慢。4.3 从/metrics读KVCache利用率和排队数vLLM提供了Prometheus格式的metrics端点一条curl就能拉到运行时的核心状态# 拉取运行时指标配合grep过滤关键项 curl -s http://localhost:8000/metrics | grep -E gpu_cache_usage_perc|num_requests_waiting|num_requests_running三个指标的含义gpu_cache_usage_perc是KVCache使用率长期接近100%说明并发已经顶到显存上限再增加请求只能排队num_requests_waiting是等待中的请求数这个值持续大于0说明prefill或decode处理不过来num_requests_running是正在跑的请求数正常应接近--max-num-seqs的设定值。这几个指标也对应eenginecore与scheduler、executor交互流程的外部表现scheduler决定谁能进batchexecutor真正跑CUDA kernelmetrics反映的就是排队策略是否健康。压测时把这几个数和第4.1节的硬吞吐对照看就能区分瓶颈在调度还是显存还是模型本身。5. vLLM部署Qwen避坑指南五个常见的翻车点与解法这一章写的是我在vLLM部署Qwen过程中真实遇到过的踩坑记录按“现象→原因→解决”的格式整理。你大概率会踩中其中一两个先看目录再对号入座能省半天排错时间。5.1 显存明明够服务却报No available memory现象24G卡部署Qwen2.5-7B-Instruct按网上推荐的参数设--gpu-memory-utilization 0.95 --max-model-len 32768启动时报No available memory for the cache blocks然后进程退出。原因KVCache预分配不是按模型权重算的而是按max_model_len × 最大batch数 × 层数 × 头数计算的vLLM默认附带--max-num-seqs和预填充token数相关的并发余量。0.95的显存利用率看似留了5%但加上CUDA context和PyTorch预留预分配计算时已经超额。解决把--gpu-memory-utilization降到0.85--max-model-len从32768降到16384启动后再慢慢往上调。这是vLLM部署大模型最经典的玄学现场遇到OOM先降这两个值不要想着去改PyTorch的显存池配置那是改不动的。5.2 多卡部署后吞吐不升反降现象拿两张24G卡部署Qwen2.5-7B-Instruct--tensor-parallel-size 2启动成功但跑第4.1节的benchmark吞吐比单卡还低20%。原因张量并行要把层参数切到多卡每次forward都要跨卡同步7B模型本身单卡能装下时通信开销大于并行收益。vLLM社区里这个现象很常见模型规模越小越明显。解决7B模型用单卡跑不要把显存浪费在并行上。张量并行只留给32B以上或单卡放不下的模型。如果你的目标是提升Qwen-7B并发能力正确做法是部署两个独立vLLM实例在前端加负载均衡而不是开TP。多卡唯一靠谱的场景是单卡装不下同一个模型此时TP才划算。5.3 长对话到一半报input too long或输出乱码现象对话变长后请求返回带input too long的错误或者生成到一半内容变成重复的乱码看起来像模型“傻了”。原因--max-model-len设成了8192而messages拼接后的token数超过这个值vLLM直接拒绝请求。乱码则是另一种情况上下文长度正好卡在边界模型在截断位置继续生成注意力分布被切坏的KVCache干扰。解决把--max-model-len调到模型支持的上限内。Qwen2.5-7B官方支持128K但24G卡开不到那么长可行方案是降并发或换AWQ量化版本省出显存给KVCache。一句话原则实际服务里的最大prompt长度建议不超过--max-model-len的80%留出生成空间否则输出阶段随时可能撞墙。5.4 换版本、换镜像后性能下降或直接起不来现象升级vLLM一个小版本后同样的Qwen模型、同样的参数benchmark吞吐掉了10%到15%或者把docker镜像从固定版本换成latest后加载模型时报算子不匹配错误。原因vLLM版本迭代时attention backend和调度逻辑经常调整flash-attention版本也不断更换。“vllm新版本性能下降”在社区是高频话题新特性引入回归并不罕见。生产环境追latest等于让版本漂移帮你挑风险。解决锁版本号。用docker镜像时固定tag比如vllm/vllm-openai:0.6.2不要用latestpip安装时在requirements里写好vllm对应版本。升级前先看release notes里有没有涉及scheduler逻辑和attention实现的变更再决定要不要升。社区里也经常看到“GLM用什么版本的vLLM镜像”这类问题答案永远是去看模型卡上标注的测试版本而不是自己猜新版更兼容。另外docker启动后秒退日志只留一行错误多半是挂载路径问题# 用固定版本镜像和显式挂载路径避免相对路径坑 docker run -d --gpus all \ -v ~/models:/model \ -p 8000:8000 \ vllm/vllm-openai:0.6.2 \ --model /model/Qwen2.5-7B-Instruct \ --served-model-name qwen2.5-7b这个例子把模型目录显式挂载到容器内的/model容器内路径必须和--model参数完全一致相对路径在容器里经常解析到不存在的目录导致“秒退”假象。日志里如果出现Error loading model第一反应查挂载而不是查模型。5.5 并发一高首Token延迟失控prefill在挤占decode现象单请求首Token延迟只有300ms并发从1升到10首Token延迟变成3秒以上体验明显卡顿。原因vLLM虽然是continuous batching但prefill阶段计算量大长prompt的prefill会阻塞batch里其他请求的decode步骤。scheduler在分配批次时如果不对prefill做切分一个大prompt进来就像高速公路上并入了辆卡车整个batch的节奏被打乱。解决给scheduler加约束。新版vLLM支持--max-num-prefill-tokens限制单次prefill的token总量设置后用带chunked prefill的机制把大prompt切成小块混进decode的空隙里。只设--max-num-seqs限制最大batch数也有帮助相当于从源头控制卡车数量。这类问题盯metrics就行num_requests_waiting飙升而GPU算力没满十有八九是prefill没切分。6. 进阶部署技巧量化、LoRA和Docker镜像三条路怎么选基础服务稳定后下一个问题通常是显存不够用怎么办、微调模型怎么接、多人协作环境怎么统一。这一章讲三条可落地的进阶路线按推荐顺序排。6.1 AWQ量化部署显存砍半代价可控如果你的Qwen-7B在24G卡上开32K上下文总在OOM边缘首选方案是换AWQ量化版本。AWQ把权重压到4bit显存占用大约降一半推理速度损失在个位数百分比是性价比最高的降本手段。启动命令只需改模型路径和指定量化方式python -m vllm.entrypoints.openai.api_server \ --model ./Qwen2.5-7B-Instruct-AWQ \ --served-model-name qwen2.5-7b-awq \ --max-model-len 32768 \ --quantization awq \ --gpu-memory-utilization 0.9ModelScope上官方维护了AWQ版本文件名带AWQ后缀下载后--quantization awq告诉vLLM用AWQ算子解码。切换后原代码零改动--served-model-name变了客户端记得同步。量化后模型质量会有轻微损失如果下游是强逻辑任务先在离线测试集上对比几个关键case再切。6.2 LoRA微调模型接入vLLM关键在 --enable-lora如果你做的是Qwen2.5-7B微调行业大模型训练完拿到的是LoRA adapter不是完整模型文件。vLLM原生支持部署base模型叠加LoRA启动时加两个参数python -m vllm.entrypoints.openai.api_server \ --model Qwen/Qwen2.5-7B-Instruct \ --enable-lora \ --lora-modules my-lora/path/to/adapter \ --served-model-name qwen2.5-7b-lora--enable-lora打开适配器加载能力--lora-modules指定别名和adapter路径请求时model字段传my-lora就能走微调后的行为。注意显存账要同时算base模型和adapteradapter本身不大几十到几百MB但base模型该占的显存一分不少。如果微调时改了词表或使用了自定义chat模板部署前确认这些配置和base模型兼容否则推理结果会在模板拼接阶段变形。6.3 生产环境为什么我最终还是回到Docker镜像我是从pip安装开始用vLLM的踩过几次版本和驱动匹配问题的坑后生产环境最终还是固定成Docker镜像方式部署。原因很朴素镜像把CUDA、torch、vLLM、flash-attention的匹配关系固化好了换机器部署时不用重新排错一遍版本号写在镜像tag里回滚就是重启一个旧tag容器。团队协作时一个docker run命令就是全部的环境文档新手照着跑不会在第一步就因为驱动版本起不来。我现在的固定流程是ModelScope下载模型Docker镜像启动服务metrics探活benchmark留底。每次部署前把vLLM版本、模型路径、三个关键参数表格贴到项目说明里翻车时先对照参数再查日志这个习惯帮我省了太多无头绪的调试时间。部署框架这东西选定一条路径走到黑比反复横跳有效率得多。希望帮到你。本文还有配套的精品资源点击获取