尧图网页设计 
简介面向具备一定Python基础的AI应用开发者这份项目实战包聚焦于使用vLLM框架部署通义千问Qwen大语言模型完整覆盖从模型加载、接口定义到服务启停的部署全流程。包内共9个文件包括6个Python脚本、2张架构示意图和1份Markdown说明文档脚本部分按用途分为服务端、客户端、离线推理、Web可视化界面及辅助工具等模块README则梳理了环境依赖安装、模型配置与性能调优步骤。压缩包仅433KB轻量且目录清晰便于快速定位所需模块。目前已有1491人学习下载适合希望在真实项目中快速搭建语言模型服务的个人或团队通过源码模板与教程对照可显著降低部署门槛并规避常见踩坑问题。1. 大模型部署没有想象中那么玄一套能跑起来的 Qwen vLLM 实战做 AI 应用的人迟早会撞上同一个问题在本地或私有服务器上部署一个大语言模型供自己的业务调用。网上教程很多但要么只讲概念不讲操作要么版本太老跑不通。通义千问 Qwen 是目前中文开源模型里社区最活跃、文档最全的选择之一而 vLLM 是大模型部署绕不开的高性能推理框架。这两者组合加上一套完整的项目源码和流程教程基本可以覆盖从零到能用的全部过程——包括环境配置、模型下载、服务启动、性能调优和常见坑位。这篇笔记能帮到两类人一类是刚接触大模型部署的开发者想快速跑通全流程另一类是有一定经验的工程师想对照检查自己的部署参数和排错思路。2. vLLM 与 Qwen 的选型逻辑为什么是这两个以及环境准备2.1 为什么选 Qwen 而不是其他开源模型当前开源大模型生态里Qwen通义千问系列在国内外的使用热度都很高。它由阿里开源覆盖从 0.5B 到 72B 多个参数规模包括 Base基座、Instruct指令微调、MoE混合专家等多种版本。相比同类开源模型Qwen 有几个明显优势。中文能力扎实在中文理解、写作、代码生成等任务上表现稳定模型格式统一兼容 Hugging Face Transformers 和 vLLM许可证友好支持商用这对企业内部私有化部署非常关键。部署环境方面Qwen 系列对硬件的适应范围很宽。小尺寸的 Qwen2.5-0.5B-Instruct 只需要 4GB 左右显存就能跑而 Qwen2.5-7B-Instruct 配合量化方案可以在 8GB 显存的消费级显卡上运行72B 级别则需要多卡 A100/H100 或者 A800 这类企业级显卡。这套资源主打的是主流场景——单卡或双卡部署 7B 到 14B 规模这个区间覆盖了大多数企业私有化的真实需求。有朋友会问为什么不直接用 DeepSeek 或者 LlamaDeepSeek 系列模型性能很强但它的 MoE 架构和 vLLM 的兼容性要求更精细的配置Llama 的中文能力需要额外做词表扩展和微调。Qwen 属于开箱即用那一类vLLM 官方对它的支持最完善社区排错经验也最丰富。对部署者来说选 Qwen 意味着把精力放在部署本身而不是花在适配模型架构上。2.2 vLLM 为什么比原生 transformers 更适合生产部署很多人第一次跑通大模型用的是 transformers 库写个 Python 脚本加载模型然后进入交互式对话。这种方式验证模型效果没问题但放到生产环境就撑不住了。transformers 默认的推理方式是动态图逐 token 生成每一轮都要重新计算注意力矩阵显存浪费严重并发吞吐极低。vLLM 的核心优化是 PagedAttention分页注意力。它把 KV Cache键值缓存划分成固定大小的块按需分配避免预分配导致的显存碎片。配合 Continuous Batching连续批处理vLLM 能在同一时刻处理多个请求而不是等一个请求生成完再处理下一个。实测数据上vLLM 的吞吐量比原生 transformers 高出 10 到 20 倍这是生产环境必须用它而不是自己写推理脚本的根本原因。vLLM 还自带 OpenAI 兼容的 API 服务启动之后可以直接用openai库或 HTTP 请求调用这意味着你不需要额外封装一层 API 服务——这是这套源码里一个重要模块。部署者只需要关注模型加载和参数配置后面的服务接入能省不少事。2.3 硬件与 CUDA 环境参数怎么定才不翻车部署大模型之前先核对硬件环境。vLLM 官方要求 Linux 系统Windows 可以通过 WSL2 跑但性能和稳定性不如 Linux、CUDA 11.8 或 12.1 及以上、Python 3.9 到 3.12、显存至少 8GB。注意这里说的显存不是内存是显卡显存。有些人拿 32GB 内存的机器跑 7B 模型加载阶段没报错一开始推理就卡死原因就是模型权重和 KV Cache 都压在 CPU 内存上速度根本扛不住。显卡方面NVIDIA 显卡是首选因为 CUDA 生态最成熟。AMD 显卡和 Apple Silicon 芯片也有对应的 vLLM 分支但这套资源和教程默认走 NVIDIA CUDA 路线。部署前用nvidia-smi确认驱动和显存状态至少留出模型权重 1.2 倍以上的空闲显存。例如 7B 模型用 FP16半精度加载权重约 15GB加上 KV Cache 和计算开销单卡 24GB 显存是舒适配置。如果只有 16GB可以用 AWQ 或 GPTQ 量化把显存占用压到 10GB 以内——后面第 4 章会详细讲量化参数。环境准备阶段还有一个容易忽视的点是 CUDA 版本和 PyTorch 版本的匹配。vLLM 安装时会基于当前 PyTorch 的 CUDA 版本编译如果 PyTorch 是 CPU 版vLLM 装上也会报错。所以安装顺序建议是先装 PyTorchGPU 版→ 再装 vLLM → 最后验证 CUDA 可用性三步走顺序不能反。3. 部署实战从下载源码到 vLLM 服务跑通3.1 项目源码的文件结构与核心模块这套资源解压之后目录结构清晰每个文件对应一个部署环节。先花两分钟熟悉结构后面操作不会迷路。project_root/ ├── docs/ # 流程教程文档 │ ├── 01_environment.md # 环境准备 │ ├── 02_install.md # vLLM 安装与验证 │ ├── 03_model_download.md # 模型权重下载 │ ├── 04_server_start.md # 启动服务 │ └── 05_tuning.md # 性能调优 ├── scripts/ │ ├── download_model.py # 模型下载脚本 │ ├── start_server.sh # 服务启动脚本 │ └── test_api.py # API 连通性测试 ├── src/ │ ├── vllm_config.py # 启动参数配置文件 │ └── openai_compat.py # OpenAI 兼容接口封装 └── requirements.txt # Python 依赖清单整个流程分四步环境准备 → 安装 vLLM → 下载模型权重 → 启动服务。每个目录都有对应脚本不需要自己从零写。requirements.txt里锁定了依赖版本建议直接用不要自作主张升级版本——大模型部署里版本错位是排错成本最高的问题之一。3.2 安装 vLLM 并验证 CUDA 环境先装 PyTorch GPU 版再装 vLLM。当前推荐的组合是 PyTorch 2.4.0 vLLM 0.6.x这个组合在 CUDA 12.1 环境下测试最充分。# 1. 安装 PyTorch GPU 版CUDA 12.1 pip install torch2.4.0 torchvision0.19.0 --index-url https://download.pytorch.org/whl/cu121 # 2. 安装 vLLM pip install vllm0.6.3 # 3. 验证 CUDA 可用性 python -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))第一段命令固定 PyTorch 版本为 2.4.0指定 CUDA 12.1 的索引源避免 pip 默认拿到 CPU 版。第二段安装 vLLM 0.6.3这个版本对 Qwen2.5 系列支持最稳定。第三段验证脚本是关键——如果打印False说明 PyTorch 没装对如果报 CUDA driver 版本不兼容需要用nvcc --version查一下 CUDA 工具链版本然后选择对应版本的 PyTorch 重新安装。vLLM 安装完成后做一个快速自检python -c from vllm import LLM; print(vLLM OK)这一步能跑通说明 vLLM 的 Python 绑定和 CUDA 扩展都编译成功了。如果这里报错先检查 Python 版本vLLM 0.6.x 需要 Python 3.9 到 3.12超出范围直接换环境。3.3 模型权重下载hf-mirror 与 ModelScope 两种方案模型权重下载是卡住最多人的环节。Qwen 官方权重在 Hugging Face 上但国内直连不稳定。这里有两条成熟的路一是用 hf-mirror.com 镜像站二是用阿里自家的 ModelScope。# 方案 Ahf-mirror 镜像下载推荐 export HF_ENDPOINThttps://hf-mirror.com pip install huggingface_hub huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct # 方案 BModelScope 下载国内速度更快 pip install modelscope modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct方案 A 通过设置HF_ENDPOINT环境变量把 Hugging Face 的下载请求转发到国内镜像文件内容和官方完全一致。方案 B 用 ModelScope 的下载工具国内服务器下载速度通常能到几十 MB/s。两种方案下载的权重文件格式一致都是标准的 Hugging Face 目录结构config.json、model.safetensors分片文件、tokenizer.json等。下载完成后验证文件完整性ls -lh ./models/Qwen2.5-7B-Instruct/ du -sh ./models/Qwen2.5-7B-Instruct/7B 模型的 FP16 权重在 15GB 左右如果你看到的总大小差得远比如只有几百 MB说明下载不完整需要重新下载。这个检查很值得做因为 vLLM 加载半截权重不会立刻报错而是在推理时出现乱码或者直接崩溃。3.4 启动 Qwen 推理服务权重就位后启动服务就是一条命令的事。vLLM 提供了vllm serve命令一行代码拉起 OpenAI 兼容 API 服务。python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen2.5-7B-Instruct \ --served-model-name qwen7b \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192 \ --enable-auto-tool-choice如果没有可用的 OpenAl 兼容接口需要在确认服务启动后等待日志出现Uvicorn running on http://0.0.0.0:8000字样然后进行 API 测试# 另开一个终端窗口测试 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen7b, messages: [{role: user, content: 你好}], max_tokens: 100}这段命令各参数含义要理解清楚。--model指定本地权重路径。--served-model-name是 API 调用时的模型别名方便客户端统一。--gpu-memory-utilization 0.9表示允许 vLLM 使用 90% 的显存剩下的留给 KV Cache 和其他开销。--max-model-len 8192是最大序列长度限制输入和输出的总 token 数这个值设太大会挤占 KV Cache 空间设太小长文本对话会被截断。--host 0.0.0.0允许外部机器访问如果只想本机调试改成127.0.0.1更安全。响应里出现content: 你好有什么可以帮你的吗这样正常的中文回复说明服务跑通了。到这里一个完整的 Qwen 推理服务就部署完成可以开始做性能调优和业务接入。4. 性能调优吞吐、延迟与显存怎么平衡4.1 关键启动参数与量化方案服务能跑只是第一步生产环境要关注的是“能扛多少并发”“每个请求多快返回”。vLLM 的调优参数集中在启动命令里每个参数都对应一组性能权衡。参数取值范围作用与建议--gpu-memory-utilization0.7~0.95越高 KV Cache 越大吞吐越高但过高会导致 OOM7B 模型单卡建议 0.9--max-model-len2048~32768越长单请求占用的 KV Cache 越多并发能力下降业务场景够用就行--max-num-seqs64~256单批次最大序列数越大吞吐越高但首 token 延迟也会升高--enforce-eager布尔值关闭 CUDA Graph 优化显存紧张时开启性能略降--quantizationawq/gptq/fp8量化方案显存不足时使用模型效果略有损失量化是显存不足时最有效的方案。以 Qwen2.5-7B-Instruct 为例FP16 权重占 15GB 显存用 AWQ 4bit 量化后降到约 4.5GB16GB 显存跑起来很轻松。vLLM 对 AWQ 支持最成熟量化后的模型在吞吐上比 FP16 提升约 20%因为显存带宽压力更小。# AWQ 量化模型启动需要预先下载量化权重 python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen2.5-7B-Instruct-AWQ \ --served-model-name qwen7b-awq \ --quantization awq \ --gpu-memory-utilization 0.9 \ --max-model-len 8192量化权重的下载方式和原版一致在 Hugging Face 或 ModelScope 上搜索Qwen2.5-7B-Instruct-AWQ即可。选择量化模型时要注意 AWQ 和 GPTQ 的差异AWQ 基于激活值感知推理速度更快GPTQ 压缩率略高但解码速度通常比 AWQ 慢 10% 左右。实操中我会优先选 AWQ。4.2 并发压测看吞吐还是看首字延迟压测是验证服务能不能上生产的必做环节。vLLM 官方推荐用benchmark_serving.py脚本也可以用简单的 Python 并发脚本模拟。压测关注两个核心指标吞吐Tokens/s和首 token 延迟TTFTTime To First Token。前者反映服务能处理多少请求后者反映用户体验——用户发出请求后等多久看到第一个字。import asyncio import aiohttp import time async def send_request(session, prompt): url http://localhost:8000/v1/chat/completions payload { model: qwen7b, messages: [{role: user, content: prompt}], max_tokens: 512 } start time.time() async with session.post(url, jsonpayload) as resp: data await resp.json() ttft data.get(timings, {}).get(first_token_sec, -1) total data.get(timings, {}).get(total_sec, -1) print(fTTFT: {ttft}s, Total: {total}s, 首字: {ttft*1000:.0f}ms) async def main(): prompts [请介绍一下人工智能] * 20 # 20 个并发请求 async with aiohttp.ClientSession() as session: await asyncio.gather(*[send_request(session, p) for p in prompts]) asyncio.run(main())压测时要注意一个常见误区单请求延迟和并发吞吐是两个维度的指标。vLLM 的 Continuous Batching 机制下并发请求越多总吞吐越高但单个请求的首 token 延迟也越高。如果你的业务是聊天机器人对首字延迟敏感应该限制--max-num-seqs在 64 左右如果是批量文本生成对吞吐更敏感可以调到 256。根据自己的业务场景选参数不要盲目追求某个指标的极致。4.3 与 Ollama / LM Studio 的对比什么时候别用 vLLM部署大模型还有另外两个常用工具Ollama 和 LM Studio。很多人的第一反应是这两个工具更简单为什么要折腾 vLLM这里做个对比便于选型。Ollama 和 LM Studio 的优势是安装简单、自带模型仓库、一条命令启动服务。它们底层用的推理引擎是 llama.cpp主要优化 CPU 和 Apple Silicon 上的推理显存利用率和并发处理能力远不如 vLLM。适用场景是个人电脑上的本机实验、轻量开发和模型效果验证。如果只是自己玩玩或者在笔记本上跑个小模型Ollama 体验更好。vLLM 的场景是企业私有化部署、多用户并发服务、高吞吐生产环境。它依赖 CUDA需要 Linux NVIDIA 显卡部署门槛更高但换来的是数量级的性能提升。业界一个粗估的参考同样的 7B 模型Ollama 单请求吞吐约 12~20 tokens/svLLM 开启 Continuous Batching 后并发 20 路时单用户仍能维持 30 tokens/s总吞吐可以到 600 tokens/s。这个差距在真实业务里非常明显。选择逻辑很简单个人用选 Ollama/LM Studio生产用选 vLLM。如果你的服务预期并发只有个位数且不需要对接高吞吐接口用 Ollama 完全够用没必要背上 vLLM 的运维成本。但如果你要做企业内部 API 服务或者要给多个应用共享模型推理能力vLLM 是更合适的选择。5. 部署避坑指南6 条实测踩坑记录5.1 显存明明够却 OOMgpu-memory-utilization设太高现象显存还有 6GB 空闲启动服务时报 CUDA Out of Memory。原因--gpu-memory-utilization设了 0.95vLLM 预分配的显存 模型权重 计算缓冲区超过物理显存上限但 PyTorch 的显存缓存让nvidia-smi显示的空闲值虚高。解决把gpu-memory-utilization降到 0.85或者先做量化降低权重占用。经验法则显存余量至少要留max-model-len / 1024 * 0.5GB的缓冲区间。5.2 并发一高响应就飘token 数上限被 KV Cache 挤爆现象单个请求一切正常并发 30 路之后响应时间从 1 秒飙到 30 秒甚至大量请求排队超时。原因--max-model-len设成 32768每个请求虽然只生成 200 token但 vLLM 按最大长度预分配 KV Cache显存很快耗尽后续请求只能排队。解决把max-model-len压到实际业务需要的长度比如 4096。同时观察vllm日志里的num_free_gpu_memory字段如果接近 0说明 KV Cache 不足需要调小max-model-len或增大gpu-memory-utilization。5.3 中文输出乱码或重复循环tokenizer 文件不完整现象模型启动正常但返回的中文内容出现乱码或者同一个词重复输出十几遍。原因tokenizer 文件tokenizer.json、tokenizer_config.json下载不完整或版本和模型权重不匹配导致 vocab 映射错位。解决重新下载模型目录下的*.json文件确认文件大小非空如果用的是 ModelScope 下载和 Hugging Face 上的 tokenizer 文件对比一下内容是否一致。检查方法是看模型目录里有没有tokenizer.json没有的话跑一遍huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct --include *.json。5.4 启动报AssertionError: Unsupported model architecture版本错配现象按教程装好 vLLM启动时提示模型架构不支持。原因vLLM 版本过老或过新对 Qwen2.5 架构的注册名不一致。老版本叫QwenForCausalLM新版本统一为Qwen2ForCausalLM版本之间也可能存在模型实现差异。解决固定 vLLM 版本为 0.6.x同时查看模型目录里的config.json确认architectures字段是Qwen2ForCausalLM还是QwenForCausalLM再到 vLLM 源码的model_executor/models/目录下查注册名。遇到这种情况最快的方案是pip install vllm0.6.3 --force-reinstall。5.5 端口被占用导致服务启动失败现象启动命令执行后日志报Address already in use或者前一个服务进程还在跑。原因默认端口 8000 被占用。解决换端口或用lsof -i :8000查看占用进程然后kill -9清理。规范的做法是启动脚本里加一个端口检查PORT8000 if lsof -i :$PORT /dev/null 21; then echo 端口 $PORT 已被占用请先清理进程或换端口 exit 1 fi5.6 模型加载极慢第一次启动要等 5 分钟现象启动命令执行后日志停留在Loading model weights很久以为卡死了。原因vLLM 第一次加载时不仅读取权重文件还要做 CUDA Graph 捕获和 kernel 编译这会额外耗时。解决耐心等待同时用watch -n 1 nvidia-smi观察显存占用是否在上涨——如果在涨说明正常加载。后续启动会快很多因为 kernel 编译结果有系统缓存。如果想跳过 CUDA Graph 编译可以加--enforce-eager但推理性能会下降约 30%不建议生产环境这么干。6. 把服务接入业务OpenAI 兼容 API 的量产验证6.1 用 OpenAI SDK 验证 API 连通性服务已经跑在 8000 端口上最后要验证的是业务代码能不能直接调用。vLLM 提供的 OpenAI 兼容 API 意味着你不需要改任何客户端代码只要把 API 的 base_url 指到本地服务即可。from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, # vLLM 本地服务不校验 key但字段不能缺 ) response client.chat.completions.create( modelqwen7b, messages[ {role: system, content: 你是一个运维助手回答要简洁。}, {role: user, content: 如何在 Linux 上查看端口占用情况} ], temperature0.7, max_tokens512, streamFalse ) print(response.choices[0].message.content)这个脚本验证了三件事服务端 API 路径正确、模型名字别名可用、业务代码不用改就能接入。参数temperature0.7控制生成随机性max_tokens512限制回复长度。如果你的业务是代码生成建议把temperature调到 0.2 以下减少随机错误。6.2 生产环境的附加配置服务验证通过之后有几个生产配置值得补上这些都是实际部署中血泪教训换来的。第一加一个启动守护脚本。vLLM 服务进程如果崩溃或被杀掉需要自动重启。用 systemd 管理 vLLM 服务是最规范的做法进程崩溃后会自动拉起服务器重启后也会自动启动服务。[Unit] DescriptionvLLM Qwen Server Afternetwork.target [Service] ExecStart/usr/bin/python -m vllm.entrypoints.openai.api_server --model ./models/Qwen2.5-7B-Instruct --served-model-name qwen7b --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.9 Restartalways RestartSec5 EnvironmentCUDA_VISIBLE_DEVICES0 [Install] WantedBymulti-user.target把这个文件放到/etc/systemd/system/vllm-qwen.service然后执行systemctl daemon-reload systemctl enable --now vllm-qwen。第二设置限流和超时。生产环境不设限流一旦突然有大流量进来vLLM 会积压大量请求最终全部超时。常见做法是在上层加 Nginx 反向代理配置proxy_read_timeout 300s和limit_req指令。第三监控显存和吞吐。用nvidia-smi -l 5定时记录显存使用或者接入 Prometheus Grafana。显存增长异常往往是服务泄漏的前兆提前发现能避免半夜接到告警电话。这套资源的真正价值在于它把部署流程和源码打包在一起跟着教程走一遍遇到问题能对照检查。我自己部署第三遍的时候才把 5.4 节那个模型架构版本错配的问题彻底搞明白后来每次装新环境都会强制走一遍torch → vLLM → 权重 → 服务的完整链路再上线。部署大模型不是一次性的活儿环境变了、版本升级了都可能翻车手里有一套能复现的流程和踩坑记录比什么都踏实。希望这份笔记能让你少走几步弯路把时间花在业务上而不是折腾环境上。本文还有配套的精品资源点击获取 Qwen + vLLM 大模型部署实战：从环境配置到性能调优
简介面向具备一定Python基础的AI应用开发者这份项目实战包聚焦于使用vLLM框架部署通义千问Qwen大语言模型完整覆盖从模型加载、接口定义到服务启停的部署全流程。包内共9个文件包括6个Python脚本、2张架构示意图和1份Markdown说明文档脚本部分按用途分为服务端、客户端、离线推理、Web可视化界面及辅助工具等模块README则梳理了环境依赖安装、模型配置与性能调优步骤。压缩包仅433KB轻量且目录清晰便于快速定位所需模块。目前已有1491人学习下载适合希望在真实项目中快速搭建语言模型服务的个人或团队通过源码模板与教程对照可显著降低部署门槛并规避常见踩坑问题。1. 大模型部署没有想象中那么玄一套能跑起来的 Qwen vLLM 实战做 AI 应用的人迟早会撞上同一个问题在本地或私有服务器上部署一个大语言模型供自己的业务调用。网上教程很多但要么只讲概念不讲操作要么版本太老跑不通。通义千问 Qwen 是目前中文开源模型里社区最活跃、文档最全的选择之一而 vLLM 是大模型部署绕不开的高性能推理框架。这两者组合加上一套完整的项目源码和流程教程基本可以覆盖从零到能用的全部过程——包括环境配置、模型下载、服务启动、性能调优和常见坑位。这篇笔记能帮到两类人一类是刚接触大模型部署的开发者想快速跑通全流程另一类是有一定经验的工程师想对照检查自己的部署参数和排错思路。2. vLLM 与 Qwen 的选型逻辑为什么是这两个以及环境准备2.1 为什么选 Qwen 而不是其他开源模型当前开源大模型生态里Qwen通义千问系列在国内外的使用热度都很高。它由阿里开源覆盖从 0.5B 到 72B 多个参数规模包括 Base基座、Instruct指令微调、MoE混合专家等多种版本。相比同类开源模型Qwen 有几个明显优势。中文能力扎实在中文理解、写作、代码生成等任务上表现稳定模型格式统一兼容 Hugging Face Transformers 和 vLLM许可证友好支持商用这对企业内部私有化部署非常关键。部署环境方面Qwen 系列对硬件的适应范围很宽。小尺寸的 Qwen2.5-0.5B-Instruct 只需要 4GB 左右显存就能跑而 Qwen2.5-7B-Instruct 配合量化方案可以在 8GB 显存的消费级显卡上运行72B 级别则需要多卡 A100/H100 或者 A800 这类企业级显卡。这套资源主打的是主流场景——单卡或双卡部署 7B 到 14B 规模这个区间覆盖了大多数企业私有化的真实需求。有朋友会问为什么不直接用 DeepSeek 或者 LlamaDeepSeek 系列模型性能很强但它的 MoE 架构和 vLLM 的兼容性要求更精细的配置Llama 的中文能力需要额外做词表扩展和微调。Qwen 属于开箱即用那一类vLLM 官方对它的支持最完善社区排错经验也最丰富。对部署者来说选 Qwen 意味着把精力放在部署本身而不是花在适配模型架构上。2.2 vLLM 为什么比原生 transformers 更适合生产部署很多人第一次跑通大模型用的是 transformers 库写个 Python 脚本加载模型然后进入交互式对话。这种方式验证模型效果没问题但放到生产环境就撑不住了。transformers 默认的推理方式是动态图逐 token 生成每一轮都要重新计算注意力矩阵显存浪费严重并发吞吐极低。vLLM 的核心优化是 PagedAttention分页注意力。它把 KV Cache键值缓存划分成固定大小的块按需分配避免预分配导致的显存碎片。配合 Continuous Batching连续批处理vLLM 能在同一时刻处理多个请求而不是等一个请求生成完再处理下一个。实测数据上vLLM 的吞吐量比原生 transformers 高出 10 到 20 倍这是生产环境必须用它而不是自己写推理脚本的根本原因。vLLM 还自带 OpenAI 兼容的 API 服务启动之后可以直接用openai库或 HTTP 请求调用这意味着你不需要额外封装一层 API 服务——这是这套源码里一个重要模块。部署者只需要关注模型加载和参数配置后面的服务接入能省不少事。2.3 硬件与 CUDA 环境参数怎么定才不翻车部署大模型之前先核对硬件环境。vLLM 官方要求 Linux 系统Windows 可以通过 WSL2 跑但性能和稳定性不如 Linux、CUDA 11.8 或 12.1 及以上、Python 3.9 到 3.12、显存至少 8GB。注意这里说的显存不是内存是显卡显存。有些人拿 32GB 内存的机器跑 7B 模型加载阶段没报错一开始推理就卡死原因就是模型权重和 KV Cache 都压在 CPU 内存上速度根本扛不住。显卡方面NVIDIA 显卡是首选因为 CUDA 生态最成熟。AMD 显卡和 Apple Silicon 芯片也有对应的 vLLM 分支但这套资源和教程默认走 NVIDIA CUDA 路线。部署前用nvidia-smi确认驱动和显存状态至少留出模型权重 1.2 倍以上的空闲显存。例如 7B 模型用 FP16半精度加载权重约 15GB加上 KV Cache 和计算开销单卡 24GB 显存是舒适配置。如果只有 16GB可以用 AWQ 或 GPTQ 量化把显存占用压到 10GB 以内——后面第 4 章会详细讲量化参数。环境准备阶段还有一个容易忽视的点是 CUDA 版本和 PyTorch 版本的匹配。vLLM 安装时会基于当前 PyTorch 的 CUDA 版本编译如果 PyTorch 是 CPU 版vLLM 装上也会报错。所以安装顺序建议是先装 PyTorchGPU 版→ 再装 vLLM → 最后验证 CUDA 可用性三步走顺序不能反。3. 部署实战从下载源码到 vLLM 服务跑通3.1 项目源码的文件结构与核心模块这套资源解压之后目录结构清晰每个文件对应一个部署环节。先花两分钟熟悉结构后面操作不会迷路。project_root/ ├── docs/ # 流程教程文档 │ ├── 01_environment.md # 环境准备 │ ├── 02_install.md # vLLM 安装与验证 │ ├── 03_model_download.md # 模型权重下载 │ ├── 04_server_start.md # 启动服务 │ └── 05_tuning.md # 性能调优 ├── scripts/ │ ├── download_model.py # 模型下载脚本 │ ├── start_server.sh # 服务启动脚本 │ └── test_api.py # API 连通性测试 ├── src/ │ ├── vllm_config.py # 启动参数配置文件 │ └── openai_compat.py # OpenAI 兼容接口封装 └── requirements.txt # Python 依赖清单整个流程分四步环境准备 → 安装 vLLM → 下载模型权重 → 启动服务。每个目录都有对应脚本不需要自己从零写。requirements.txt里锁定了依赖版本建议直接用不要自作主张升级版本——大模型部署里版本错位是排错成本最高的问题之一。3.2 安装 vLLM 并验证 CUDA 环境先装 PyTorch GPU 版再装 vLLM。当前推荐的组合是 PyTorch 2.4.0 vLLM 0.6.x这个组合在 CUDA 12.1 环境下测试最充分。# 1. 安装 PyTorch GPU 版CUDA 12.1 pip install torch2.4.0 torchvision0.19.0 --index-url https://download.pytorch.org/whl/cu121 # 2. 安装 vLLM pip install vllm0.6.3 # 3. 验证 CUDA 可用性 python -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))第一段命令固定 PyTorch 版本为 2.4.0指定 CUDA 12.1 的索引源避免 pip 默认拿到 CPU 版。第二段安装 vLLM 0.6.3这个版本对 Qwen2.5 系列支持最稳定。第三段验证脚本是关键——如果打印False说明 PyTorch 没装对如果报 CUDA driver 版本不兼容需要用nvcc --version查一下 CUDA 工具链版本然后选择对应版本的 PyTorch 重新安装。vLLM 安装完成后做一个快速自检python -c from vllm import LLM; print(vLLM OK)这一步能跑通说明 vLLM 的 Python 绑定和 CUDA 扩展都编译成功了。如果这里报错先检查 Python 版本vLLM 0.6.x 需要 Python 3.9 到 3.12超出范围直接换环境。3.3 模型权重下载hf-mirror 与 ModelScope 两种方案模型权重下载是卡住最多人的环节。Qwen 官方权重在 Hugging Face 上但国内直连不稳定。这里有两条成熟的路一是用 hf-mirror.com 镜像站二是用阿里自家的 ModelScope。# 方案 Ahf-mirror 镜像下载推荐 export HF_ENDPOINThttps://hf-mirror.com pip install huggingface_hub huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct # 方案 BModelScope 下载国内速度更快 pip install modelscope modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir ./models/Qwen2.5-7B-Instruct方案 A 通过设置HF_ENDPOINT环境变量把 Hugging Face 的下载请求转发到国内镜像文件内容和官方完全一致。方案 B 用 ModelScope 的下载工具国内服务器下载速度通常能到几十 MB/s。两种方案下载的权重文件格式一致都是标准的 Hugging Face 目录结构config.json、model.safetensors分片文件、tokenizer.json等。下载完成后验证文件完整性ls -lh ./models/Qwen2.5-7B-Instruct/ du -sh ./models/Qwen2.5-7B-Instruct/7B 模型的 FP16 权重在 15GB 左右如果你看到的总大小差得远比如只有几百 MB说明下载不完整需要重新下载。这个检查很值得做因为 vLLM 加载半截权重不会立刻报错而是在推理时出现乱码或者直接崩溃。3.4 启动 Qwen 推理服务权重就位后启动服务就是一条命令的事。vLLM 提供了vllm serve命令一行代码拉起 OpenAI 兼容 API 服务。python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen2.5-7B-Instruct \ --served-model-name qwen7b \ --host 0.0.0.0 \ --port 8000 \ --gpu-memory-utilization 0.9 \ --max-model-len 8192 \ --enable-auto-tool-choice如果没有可用的 OpenAl 兼容接口需要在确认服务启动后等待日志出现Uvicorn running on http://0.0.0.0:8000字样然后进行 API 测试# 另开一个终端窗口测试 curl http://localhost:8000/v1/chat/completions \ -H Content-Type: application/json \ -d {model: qwen7b, messages: [{role: user, content: 你好}], max_tokens: 100}这段命令各参数含义要理解清楚。--model指定本地权重路径。--served-model-name是 API 调用时的模型别名方便客户端统一。--gpu-memory-utilization 0.9表示允许 vLLM 使用 90% 的显存剩下的留给 KV Cache 和其他开销。--max-model-len 8192是最大序列长度限制输入和输出的总 token 数这个值设太大会挤占 KV Cache 空间设太小长文本对话会被截断。--host 0.0.0.0允许外部机器访问如果只想本机调试改成127.0.0.1更安全。响应里出现content: 你好有什么可以帮你的吗这样正常的中文回复说明服务跑通了。到这里一个完整的 Qwen 推理服务就部署完成可以开始做性能调优和业务接入。4. 性能调优吞吐、延迟与显存怎么平衡4.1 关键启动参数与量化方案服务能跑只是第一步生产环境要关注的是“能扛多少并发”“每个请求多快返回”。vLLM 的调优参数集中在启动命令里每个参数都对应一组性能权衡。参数取值范围作用与建议--gpu-memory-utilization0.7~0.95越高 KV Cache 越大吞吐越高但过高会导致 OOM7B 模型单卡建议 0.9--max-model-len2048~32768越长单请求占用的 KV Cache 越多并发能力下降业务场景够用就行--max-num-seqs64~256单批次最大序列数越大吞吐越高但首 token 延迟也会升高--enforce-eager布尔值关闭 CUDA Graph 优化显存紧张时开启性能略降--quantizationawq/gptq/fp8量化方案显存不足时使用模型效果略有损失量化是显存不足时最有效的方案。以 Qwen2.5-7B-Instruct 为例FP16 权重占 15GB 显存用 AWQ 4bit 量化后降到约 4.5GB16GB 显存跑起来很轻松。vLLM 对 AWQ 支持最成熟量化后的模型在吞吐上比 FP16 提升约 20%因为显存带宽压力更小。# AWQ 量化模型启动需要预先下载量化权重 python -m vllm.entrypoints.openai.api_server \ --model ./models/Qwen2.5-7B-Instruct-AWQ \ --served-model-name qwen7b-awq \ --quantization awq \ --gpu-memory-utilization 0.9 \ --max-model-len 8192量化权重的下载方式和原版一致在 Hugging Face 或 ModelScope 上搜索Qwen2.5-7B-Instruct-AWQ即可。选择量化模型时要注意 AWQ 和 GPTQ 的差异AWQ 基于激活值感知推理速度更快GPTQ 压缩率略高但解码速度通常比 AWQ 慢 10% 左右。实操中我会优先选 AWQ。4.2 并发压测看吞吐还是看首字延迟压测是验证服务能不能上生产的必做环节。vLLM 官方推荐用benchmark_serving.py脚本也可以用简单的 Python 并发脚本模拟。压测关注两个核心指标吞吐Tokens/s和首 token 延迟TTFTTime To First Token。前者反映服务能处理多少请求后者反映用户体验——用户发出请求后等多久看到第一个字。import asyncio import aiohttp import time async def send_request(session, prompt): url http://localhost:8000/v1/chat/completions payload { model: qwen7b, messages: [{role: user, content: prompt}], max_tokens: 512 } start time.time() async with session.post(url, jsonpayload) as resp: data await resp.json() ttft data.get(timings, {}).get(first_token_sec, -1) total data.get(timings, {}).get(total_sec, -1) print(fTTFT: {ttft}s, Total: {total}s, 首字: {ttft*1000:.0f}ms) async def main(): prompts [请介绍一下人工智能] * 20 # 20 个并发请求 async with aiohttp.ClientSession() as session: await asyncio.gather(*[send_request(session, p) for p in prompts]) asyncio.run(main())压测时要注意一个常见误区单请求延迟和并发吞吐是两个维度的指标。vLLM 的 Continuous Batching 机制下并发请求越多总吞吐越高但单个请求的首 token 延迟也越高。如果你的业务是聊天机器人对首字延迟敏感应该限制--max-num-seqs在 64 左右如果是批量文本生成对吞吐更敏感可以调到 256。根据自己的业务场景选参数不要盲目追求某个指标的极致。4.3 与 Ollama / LM Studio 的对比什么时候别用 vLLM部署大模型还有另外两个常用工具Ollama 和 LM Studio。很多人的第一反应是这两个工具更简单为什么要折腾 vLLM这里做个对比便于选型。Ollama 和 LM Studio 的优势是安装简单、自带模型仓库、一条命令启动服务。它们底层用的推理引擎是 llama.cpp主要优化 CPU 和 Apple Silicon 上的推理显存利用率和并发处理能力远不如 vLLM。适用场景是个人电脑上的本机实验、轻量开发和模型效果验证。如果只是自己玩玩或者在笔记本上跑个小模型Ollama 体验更好。vLLM 的场景是企业私有化部署、多用户并发服务、高吞吐生产环境。它依赖 CUDA需要 Linux NVIDIA 显卡部署门槛更高但换来的是数量级的性能提升。业界一个粗估的参考同样的 7B 模型Ollama 单请求吞吐约 12~20 tokens/svLLM 开启 Continuous Batching 后并发 20 路时单用户仍能维持 30 tokens/s总吞吐可以到 600 tokens/s。这个差距在真实业务里非常明显。选择逻辑很简单个人用选 Ollama/LM Studio生产用选 vLLM。如果你的服务预期并发只有个位数且不需要对接高吞吐接口用 Ollama 完全够用没必要背上 vLLM 的运维成本。但如果你要做企业内部 API 服务或者要给多个应用共享模型推理能力vLLM 是更合适的选择。5. 部署避坑指南6 条实测踩坑记录5.1 显存明明够却 OOMgpu-memory-utilization设太高现象显存还有 6GB 空闲启动服务时报 CUDA Out of Memory。原因--gpu-memory-utilization设了 0.95vLLM 预分配的显存 模型权重 计算缓冲区超过物理显存上限但 PyTorch 的显存缓存让nvidia-smi显示的空闲值虚高。解决把gpu-memory-utilization降到 0.85或者先做量化降低权重占用。经验法则显存余量至少要留max-model-len / 1024 * 0.5GB的缓冲区间。5.2 并发一高响应就飘token 数上限被 KV Cache 挤爆现象单个请求一切正常并发 30 路之后响应时间从 1 秒飙到 30 秒甚至大量请求排队超时。原因--max-model-len设成 32768每个请求虽然只生成 200 token但 vLLM 按最大长度预分配 KV Cache显存很快耗尽后续请求只能排队。解决把max-model-len压到实际业务需要的长度比如 4096。同时观察vllm日志里的num_free_gpu_memory字段如果接近 0说明 KV Cache 不足需要调小max-model-len或增大gpu-memory-utilization。5.3 中文输出乱码或重复循环tokenizer 文件不完整现象模型启动正常但返回的中文内容出现乱码或者同一个词重复输出十几遍。原因tokenizer 文件tokenizer.json、tokenizer_config.json下载不完整或版本和模型权重不匹配导致 vocab 映射错位。解决重新下载模型目录下的*.json文件确认文件大小非空如果用的是 ModelScope 下载和 Hugging Face 上的 tokenizer 文件对比一下内容是否一致。检查方法是看模型目录里有没有tokenizer.json没有的话跑一遍huggingface-cli download Qwen/Qwen2.5-7B-Instruct --local-dir ./models/Qwen2.5-7B-Instruct --include *.json。5.4 启动报AssertionError: Unsupported model architecture版本错配现象按教程装好 vLLM启动时提示模型架构不支持。原因vLLM 版本过老或过新对 Qwen2.5 架构的注册名不一致。老版本叫QwenForCausalLM新版本统一为Qwen2ForCausalLM版本之间也可能存在模型实现差异。解决固定 vLLM 版本为 0.6.x同时查看模型目录里的config.json确认architectures字段是Qwen2ForCausalLM还是QwenForCausalLM再到 vLLM 源码的model_executor/models/目录下查注册名。遇到这种情况最快的方案是pip install vllm0.6.3 --force-reinstall。5.5 端口被占用导致服务启动失败现象启动命令执行后日志报Address already in use或者前一个服务进程还在跑。原因默认端口 8000 被占用。解决换端口或用lsof -i :8000查看占用进程然后kill -9清理。规范的做法是启动脚本里加一个端口检查PORT8000 if lsof -i :$PORT /dev/null 21; then echo 端口 $PORT 已被占用请先清理进程或换端口 exit 1 fi5.6 模型加载极慢第一次启动要等 5 分钟现象启动命令执行后日志停留在Loading model weights很久以为卡死了。原因vLLM 第一次加载时不仅读取权重文件还要做 CUDA Graph 捕获和 kernel 编译这会额外耗时。解决耐心等待同时用watch -n 1 nvidia-smi观察显存占用是否在上涨——如果在涨说明正常加载。后续启动会快很多因为 kernel 编译结果有系统缓存。如果想跳过 CUDA Graph 编译可以加--enforce-eager但推理性能会下降约 30%不建议生产环境这么干。6. 把服务接入业务OpenAI 兼容 API 的量产验证6.1 用 OpenAI SDK 验证 API 连通性服务已经跑在 8000 端口上最后要验证的是业务代码能不能直接调用。vLLM 提供的 OpenAI 兼容 API 意味着你不需要改任何客户端代码只要把 API 的 base_url 指到本地服务即可。from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, # vLLM 本地服务不校验 key但字段不能缺 ) response client.chat.completions.create( modelqwen7b, messages[ {role: system, content: 你是一个运维助手回答要简洁。}, {role: user, content: 如何在 Linux 上查看端口占用情况} ], temperature0.7, max_tokens512, streamFalse ) print(response.choices[0].message.content)这个脚本验证了三件事服务端 API 路径正确、模型名字别名可用、业务代码不用改就能接入。参数temperature0.7控制生成随机性max_tokens512限制回复长度。如果你的业务是代码生成建议把temperature调到 0.2 以下减少随机错误。6.2 生产环境的附加配置服务验证通过之后有几个生产配置值得补上这些都是实际部署中血泪教训换来的。第一加一个启动守护脚本。vLLM 服务进程如果崩溃或被杀掉需要自动重启。用 systemd 管理 vLLM 服务是最规范的做法进程崩溃后会自动拉起服务器重启后也会自动启动服务。[Unit] DescriptionvLLM Qwen Server Afternetwork.target [Service] ExecStart/usr/bin/python -m vllm.entrypoints.openai.api_server --model ./models/Qwen2.5-7B-Instruct --served-model-name qwen7b --host 0.0.0.0 --port 8000 --gpu-memory-utilization 0.9 Restartalways RestartSec5 EnvironmentCUDA_VISIBLE_DEVICES0 [Install] WantedBymulti-user.target把这个文件放到/etc/systemd/system/vllm-qwen.service然后执行systemctl daemon-reload systemctl enable --now vllm-qwen。第二设置限流和超时。生产环境不设限流一旦突然有大流量进来vLLM 会积压大量请求最终全部超时。常见做法是在上层加 Nginx 反向代理配置proxy_read_timeout 300s和limit_req指令。第三监控显存和吞吐。用nvidia-smi -l 5定时记录显存使用或者接入 Prometheus Grafana。显存增长异常往往是服务泄漏的前兆提前发现能避免半夜接到告警电话。这套资源的真正价值在于它把部署流程和源码打包在一起跟着教程走一遍遇到问题能对照检查。我自己部署第三遍的时候才把 5.4 节那个模型架构版本错配的问题彻底搞明白后来每次装新环境都会强制走一遍torch → vLLM → 权重 → 服务的完整链路再上线。部署大模型不是一次性的活儿环境变了、版本升级了都可能翻车手里有一套能复现的流程和踩坑记录比什么都踏实。希望这份笔记能让你少走几步弯路把时间花在业务上而不是折腾环境上。本文还有配套的精品资源点击获取