尧图网站建设 
这次我们来看 vLLM 的版本更新。vLLM v0.28.0 这一版把重点放在了 Kimi-K3 和 DeepSeek V4 这两类新一代大模型上按发布主题来看核心方向是推理性能的大幅提升长上下文下 KV Cache 更省、MoE 架构下的调度更准、FP8 量化与多卡并行也更顺。简单说如果你之前用老版本跑这几类模型时总觉得显存不够、首字慢、并发一上去就卡这次更新值得关注。不过先提醒一句具体能提升多少倍、显存能省多少要以官方 release notes 和你本机实测为准。这篇文章会把 vLLM 部署大模型的完整流程拆开讲一遍环境准备、pip 和 Docker 启动、OpenAI 兼容 API 验证、批量任务思路、显存和延迟观察、常见问题排查。适合正在做本地大模型服务或者想把 Qwen、DeepSeek、Kimi 系列模型接到自己业务里的同学。整个验证流程都是通用套路先启动服务再确认模型加载然后走一遍 Chat Completion 接口最后观察显存和耗时。这些步骤看完你就能判断这个版本到底能不能用、怎么用、瓶颈在哪里。1. vLLM 是什么这版更新看什么vLLM 是目前社区里用得最多的开源 LLM 推理与服务引擎之一核心卖点有三个PagedAttention把 KV Cache 按页管理减少显存碎片长上下文场景下能塞进更多请求。Continuous Batching请求不用等一整批结束再处理空闲的显存和算力会被动态利用吞吐更稳。OpenAI 兼容 API启动后提供/v1/chat/completions、/v1/completions、/v1/models等接口可以直接被 LangChain、Open WebUI、Chatbox、CodeBuddy 这类工具对接。vLLM v0.28.0 这版从发布主题看主要围绕 Kimi-K3、DeepSeek V4 这类模型做了针对性优化。这类模型普遍有两个特点参数量非常大而且很多是 MoE 架构推理时不是把所有参数都激活。因此对推理框架的要求就变成了显存分配要够细、调度要够快、量化支持要够好。vLLM 的 PagedAttention 和 Continuous Batching 正好在这几个方向上发力所以新版本带来的感知变化通常就是显存占用下降、并发吞吐上升、首字延迟更可控。实际部署时更稳妥的判断方式是不要只盯着版本号先把服务跑起来用/v1/models确认模型加载成功再测几个固定问题观察耗时和显存最后再上批量任务。这一套流程走完这个版本适不适合你的硬件和模型就清楚了。2. 核心能力速览能力项说明项目类型开源大模型推理与服务框架主要功能OpenAI 兼容 API、高并发推理、Continuous Batching、PagedAttention、张量并行、量化推理支持平台Linux 为主NVIDIA GPU 场景最成熟ROCm、Ascend 有对应后端Windows 建议使用 WSL2 或 Docker推荐硬件NVIDIA GPU具体按模型量级决定单卡不够时用多卡张量并行显存占用与模型参数量、量化格式、上下文长度、并发数强相关需按实际模型测试启动方式命令行vllm serve、Docker 容器、脚本一键启动接口 APIOpenAI 兼容格式路径为/v1/models、/v1/chat/completions、/v1/completions批量任务支持高并发请求可通过并发客户端批量提交适合场景私有化部署、生产推理服务、批量评测、多模型接入、长上下文应用注意表格里没有写死显存数字因为不同模型的权重大小、KV Cache 分配和并发策略差太多了。比如一个 7B 模型和一个 27B MoE 模型显存需求完全是两个量级。部署前先确认模型格式和你的显卡总量再决定用不用量化、要不要上多卡。3. 适用场景与使用边界vLLM 适合这几类场景业务方需要一套自持的推理 API不想每次请求都走公网模型服务。有固定 GPU 资源希望把 Qwen、DeepSeek、Kimi 系列模型在本地跑成 OpenAI 兼容服务。需要做批量评测、批量生成对吞吐和并发有要求。需要把模型接入 LangChain、CodeBuddy、VS Code 插件、企业内部工具链。不太适合的场景没有 GPU 的纯 CPU 环境。虽然 vLLM 在特定版本支持 CPU 推理但性能远不如 GPU轻量场景建议直接走 llama.cpp 或 Ollama。只是为了玩一玩、不想管 CUDA 和依赖的环境。vLLM 更适合有一定运维能力的人。需要复杂多模态能力的项目。多模态模型支持要看具体版本和模型是否兼容不要默认都能跑。部署和使用时还要注意边界模型权重有各自的开源协议商用前先确认 license 是否允许尤其是 DeepSeek、Qwen、Kimi 系列不同版本的授权范围可能不同。服务一旦开成 HTTP 接口就相当于把模型能力暴露给了网络必须加访问控制不要直接裸奔到公网。如果业务数据涉及用户隐私、内部资料要先做脱敏再传给本地模型本地部署不等于可以随便处理敏感信息。如果接了工具调用、Agent、代码执行类功能要限制模型可调用的操作范围避免模型输出被直接执行。4. 本地部署环境准备4.1 硬件与系统检查部署 vLLM 前先确认几件事操作系统优先 Linux 服务器Ubuntu 20.04 / 22.04 比较常见。macOS 或 Windows 直接用 vLLM 会遇到不少编译和依赖问题Windows 建议用 WSL2 或 Docker。GPUNVIDIA 显卡显存越大越好。7B 模型建议 16G 以上27B 或 MoE 大模型建议 24G 以上或直接用多卡。驱动和 CUDA先确认nvidia-smi能正常输出驱动版本不要太老。Python建议 3.10 或 3.11降低依赖冲突概率。磁盘空间模型权重文件动辄几十 G预留至少模型体积两倍的剩余空间。先跑一遍检查命令nvidia-smi python --version pip --version如果nvidia-smi报错说明驱动没装好先处理 NVIDIA 驱动再继续部署。4.2 虚拟环境不建议直接往系统 Python 环境里装 vLLM依赖冲突会很难受。用一个独立虚拟环境python -m venv vllm-env source vllm-env/bin/activate后续所有安装和启动命令都在这个环境里执行。如果是 Docker 部署可以跳过虚拟环境这一步。5. 安装部署与启动方式5.1 pip 安装虚拟环境激活后直接安装pip install -U vllm如果你明确需要某个发布线比如标题中的 v0.28.0 版本可以锁定版本号安装pip install vllm0.28.0这里有个细节如果 PyPI 上找不到这个版本号说明该版本可能来自项目的分支发布或内部镜像以官方源能安装到的版本为准。版本号不同不影响下面的启动流程核心参数是通用的。安装完成后可以用vllm serve --help确认命令可用vllm serve --help5.2 Docker 启动生产环境我通常推荐 Docker依赖隔离最干净。官方提供了 OpenAI 兼容服务镜像docker pull vllm/vllm-openai:latest启动一个服务docker run --runtime nvidia --gpus all \ -v /data/models:/models \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model /models/deepseek-v4-flash \ --served-model-name deepseek-v4-flash \ --gpu-memory-utilization 0.9 \ --max-model-len 32768注意/models/deepseek-v4-flash只是示例路径你要替换成自己实际的模型目录。--served-model-name是给客户端看的模型名调用 API 时model字段要填这个名字。5.3 docker-compose 部署如果模型多、参数固定建议写一份docker-compose.yml管理services: vllm: image: vllm/vllm-openai:latest container_name: vllm-server command: --model /models/qwen3-27b-awq --served-model-name qwen3-27b --tensor-parallel-size 2 --gpu-memory-utilization 0.9 --max-model-len 32768 --port 8000 ports: - 8000:8000 volumes: - /data/models:/models deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped启动docker compose up -d查看日志docker compose logs -f5.4 常见启动参数参数作用--model模型路径或模型名--served-model-name对外暴露的模型名称--tensor-parallel-size张量并行卡数多卡时使用--gpu-memory-utilization单卡显存利用率上限默认 0.9--max-model-len最大上下文长度影响 KV Cache 分配--dtype推理精度可用auto、bfloat16等--quantization量化方式如awq、gptq、fp8--enable-prefix-caching开启前缀缓存重复 prompt 可提速--port/--host服务监听端口和地址--max-num-seqs同一时间最大处理序列数影响并发能力启动后立刻验证服务是否可用curl http://127.0.0.1:8000/v1/models如果返回模型列表说明服务已经起来了接下来进入功能测试。6. 功能测试与效果验证6.1 确认模型加载访问/v1/models是最直接的判断标准curl http://127.0.0.1:8000/v1/models输出里能看到你设置的served-model-name。如果这里是空列表说明模型没加载成功回去看启动日志。6.2 Chat Completion 接口测试用 curl 跑一个最简单的对话请求curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-27b, messages: [ {role: user, content: 用一句话解释什么是 PagedAttention} ], temperature: 0.7, max_tokens: 256 }返回结果里的choices[0].message.content就是模型输出。如果返回model字段和请求的模型名一致说明接口链路是通的。6.3 Python 请求测试import requests url http://127.0.0.1:8000/v1/chat/completions payload { model: qwen3-27b, messages: [ {role: system, content: 你是一个严谨的技术助手。}, {role: user, content: 介绍一下 Continuous Batching 的作用。} ], temperature: 0.3, max_tokens: 512 } resp requests.post(url, jsonpayload, timeout180) resp.raise_for_status() data resp.json() print(data[choices][0][message][content])6.4 OpenAI SDK 接入因为接口兼容 OpenAI直接用 OpenAI Python SDK 也能连from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY ) resp client.chat.completions.create( modelqwen3-27b, messages[{role: user, content: 写一段 Python 快速排序}], temperature0.2 ) print(resp.choices[0].message.content)api_key随便填一个字符串就行vLLM 主要做本地推理本身不校验 key 的合法性但这也意味着你如果暴露到公网必须自行加网关或鉴权。6.5 LangChain 接入from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen3-27b, base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, temperature0 ) print(llm.invoke(你好介绍一下你自己))到这里服务已经可以被各种 OpenAI 兼容工具接入了。7. 接口 API 与批量任务设计7.1 API 格式vLLM 对外接口和 OpenAI 基本一致常用三个路径GET /v1/models查看模型列表POST /v1/chat/completions对话补全POST /v1/completions文本补全请求体里常用的字段字段说明model服务暴露的模型名messageschat 格式的输入消息列表promptcompletions 格式的输入文本temperature温度控制随机性max_tokens最多生成 token 数top_p核采样参数stream是否流式返回stop停止词7.2 批量提交vLLM 本身支持并发请求不需要自己在服务端排队。批量任务的思路是客户端用多线程或多进程并发提交请求服务端通过 Continuous Batching 动态调度。一个简单的批量示例import concurrent.futures import requests URL http://127.0.0.1:8000/v1/chat/completions def run_one(prompt): payload { model: qwen3-27b, messages: [{role: user, content: prompt}], max_tokens: 256 } try: resp requests.post(URL, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[choices][0][message][content] except Exception as e: return fERROR: {e} prompts [ 问题一, 问题二, 问题三, ] with concurrent.futures.ThreadPoolExecutor(max_workers8) as pool: results list(pool.map(run_one, prompts)) for p, r in zip(prompts, results): print(p, , r)并发数不要一次开太大先观察服务端显存和 CPU 占用再逐步上调。大批量任务建议加日志、做结果落盘、对失败任务做重试。7.3 失败重试服务端在高并发下偶尔会返回超时或503批量任务需要做重试import time def run_with_retry(prompt, retries3, timeout120): for attempt in range(retries): try: resp requests.post(URL, json{ model: qwen3-27b, messages: [{role: user, content: prompt}], max_tokens: 256 }, timeouttimeout) resp.raise_for_status() return resp.json()[choices][0][message][content] except Exception as e: print(fattempt {attempt 1} failed: {e}) time.sleep(2 * (attempt 1)) return ERROR生产环境中更规范的做法是把任务写进队列由 worker 进程消费失败任务重新入队。8. 资源占用与性能观察8.1 显存观察启动服务后另开一个终端执行nvidia-smi重点看显存占用是否接近你设置的--gpu-memory-utilization。如果服务启动时模型就放不下会直接报 OOM如果生成到一半才 OOM很可能是 KV Cache 分配不足或并发开太大。显存占用不只由模型权重决定上下文长度、并发数、量化格式都有影响模型越大权重占的显存越多。--max-model-len越大KV Cache 预留越多。并发数越高KV Cache 占用越大。FP8 / AWQ 量化能明显降低权重占用但要注意硬件是否支持对应精度运算。8.2 性能指标vLLM 通过--enable-metrics可以暴露 Prometheus 指标版本支持的话访问curl http://127.0.0.1:8000/metrics如果版本不支持该参数先看vllm serve --help确认参数名。观察指标时重点关注TTFT首 token 延迟。首 token 慢通常是 prefill 阶段计算量太大、上下文过长、或者模型还在加载。TPS生成吞吐。连续请求下看每秒生成 token 数衡量服务处理能力。显存占用确认是否快接近上限。8.3 性能调优方向长上下文中重复前缀多开启--enable-prefix-caching。首 token 慢适当调小--max-model-len避免 KV Cache 过度预留。生成速度慢检查是否用了量化精度和硬件不匹配比如老显卡跑 FP8。并发上不去调整--max-num-seqs和--gpu-memory-utilization的平衡。单卡放不下模型用--tensor-parallel-size 2或更多卡但卡间通信会成为新瓶颈。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后 API 打不开端口被占用或服务未启动curl /v1/models、ss -lntp查端口换端口、重启容器显存不足直接退出模型太大或 KV Cache 分配过多nvidia-smi看可用显存用量化模型、调低 gpu-memory-utilization、拆多卡首 token 很慢prefill 过长、磁盘加载慢、前缀缓存未开用短 prompt 对比耗时调小 max-model-len、开启 prefix caching、换 SSDFP8 部署延迟偏高硬件不支持原生 FP8 运算nvidia-smi看显卡架构换bfloat16或换支持 FP8 的新显卡多卡双卡跑不起来张量并行参数没配置看启动日志中的 TP 报错加--tensor-parallel-size 2昇腾环境部署失败缺少 Ascend 后端支持查日志和后端插件使用 vllm-ascend 和对应 CANN 环境依赖安装失败Python 版本或 CUDA 版本不匹配查看 pip 报错信息换虚拟环境、升级驱动、按官方要求装 PyTorch模型文件找不到路径或模型名写错检查--model路径和目录权限修正路径、检查挂载卷本地模型需要联网吗不需要模型推理在本地完成看访问日志是否有外网请求默认不联网联网搜索是前端工具功能Continuous Batching 怎么设置默认已开启查看启动日志确认通过--max-num-seqs控制并发规模tool-call-parser 填什么客户端对接问题查工具文档和模型工具调用说明vLLM 侧开启 auto tool choiceparser 按模型选择--dp数据并行参数失效参数名随版本变化vllm serve --help查实际参数以当前版本的帮助输出为准有一个常见误解vLLM 的 Continuous Batching 不是手动开关是框架默认的调度策略。你不需要去打开它只需要通过--max-num-seqs、--max-model-len控制它能占用的资源大小。10. 最佳实践与使用建议第一第一次跑先用最小配置验证。不要一上来就开满并发和长上下文先把服务跑通再逐步加压。第二目录要分清楚。模型、日志、输出结果分开管理/data/models /data/logs /data/outputs第三批量任务必须加日志和重试。生成类任务偶发超时是常态没有重试机制的批量任务会在跑到一半时突然崩掉。第四接口服务要加访问控制。vLLM 默认不上鉴权如果服务只在内网用限制 IP 和端口访问如果公网可访问前面必须套网关、加 key、做限流。第五涉及模型输出和素材授权要谨慎。如果生成内容要做商用先确认模型权重协议、数据来源授权并安排人工复核。第六多卡部署前先确认通信方式。张量并行在 PCIe 上也能跑但通信开销比 NVLink 高如果跨机多卡网络延迟会进一步影响性能生产环境优先同机多卡。第七版本升级前保留旧配置。vllm serve --help输出的参数在不同版本间可能有差异升级前记录当前启动命令方便回退。11. 总结与下一步vLLM v0.28.0 这版最值得尝试的点是把 Kimi-K3、DeepSeek V4 这类新一代模型的部署过程做得更顺滑同时保留了 OpenAI 兼容 API 这条非常关键的接入路径。你不需要厂商的专用 SDK一个 base_url 就能把本地模型接到 LangChain、OpenWebUI、CodeBuddy 等工具里。最先应该验证的功能是/v1/models和/v1/chat/completions。这两个接口通说明模型加载正常、请求链路正常之后再去测并发和延迟才有意义。最容易踩的坑有三个一是显存设定太激进--gpu-memory-utilization和--max-model-len配得过大请求稍微一多就 OOM二是首 token 慢但不知道是 prefill 太长还是硬件不匹配三是多卡部署时--tensor-parallel-size忘配导致大模型直接放不下。这三块都可以用前面的排查流程处理。后续可以继续扩展的方向也很明确把/metrics接到 Prometheus 和 Grafana做长期性能监控把批量任务接到消息队列做成异步任务系统再往后就是用多模型路由、请求优先级和更细粒度的调度策略去完善自建推理平台。建议先把这套部署和验证流程跑一遍收藏备用后面模型再升级排查思路全都能复用。 vLLM v0.28.0部署实战：PagedAttention与Continuous Batching优化大模型推理
这次我们来看 vLLM 的版本更新。vLLM v0.28.0 这一版把重点放在了 Kimi-K3 和 DeepSeek V4 这两类新一代大模型上按发布主题来看核心方向是推理性能的大幅提升长上下文下 KV Cache 更省、MoE 架构下的调度更准、FP8 量化与多卡并行也更顺。简单说如果你之前用老版本跑这几类模型时总觉得显存不够、首字慢、并发一上去就卡这次更新值得关注。不过先提醒一句具体能提升多少倍、显存能省多少要以官方 release notes 和你本机实测为准。这篇文章会把 vLLM 部署大模型的完整流程拆开讲一遍环境准备、pip 和 Docker 启动、OpenAI 兼容 API 验证、批量任务思路、显存和延迟观察、常见问题排查。适合正在做本地大模型服务或者想把 Qwen、DeepSeek、Kimi 系列模型接到自己业务里的同学。整个验证流程都是通用套路先启动服务再确认模型加载然后走一遍 Chat Completion 接口最后观察显存和耗时。这些步骤看完你就能判断这个版本到底能不能用、怎么用、瓶颈在哪里。1. vLLM 是什么这版更新看什么vLLM 是目前社区里用得最多的开源 LLM 推理与服务引擎之一核心卖点有三个PagedAttention把 KV Cache 按页管理减少显存碎片长上下文场景下能塞进更多请求。Continuous Batching请求不用等一整批结束再处理空闲的显存和算力会被动态利用吞吐更稳。OpenAI 兼容 API启动后提供/v1/chat/completions、/v1/completions、/v1/models等接口可以直接被 LangChain、Open WebUI、Chatbox、CodeBuddy 这类工具对接。vLLM v0.28.0 这版从发布主题看主要围绕 Kimi-K3、DeepSeek V4 这类模型做了针对性优化。这类模型普遍有两个特点参数量非常大而且很多是 MoE 架构推理时不是把所有参数都激活。因此对推理框架的要求就变成了显存分配要够细、调度要够快、量化支持要够好。vLLM 的 PagedAttention 和 Continuous Batching 正好在这几个方向上发力所以新版本带来的感知变化通常就是显存占用下降、并发吞吐上升、首字延迟更可控。实际部署时更稳妥的判断方式是不要只盯着版本号先把服务跑起来用/v1/models确认模型加载成功再测几个固定问题观察耗时和显存最后再上批量任务。这一套流程走完这个版本适不适合你的硬件和模型就清楚了。2. 核心能力速览能力项说明项目类型开源大模型推理与服务框架主要功能OpenAI 兼容 API、高并发推理、Continuous Batching、PagedAttention、张量并行、量化推理支持平台Linux 为主NVIDIA GPU 场景最成熟ROCm、Ascend 有对应后端Windows 建议使用 WSL2 或 Docker推荐硬件NVIDIA GPU具体按模型量级决定单卡不够时用多卡张量并行显存占用与模型参数量、量化格式、上下文长度、并发数强相关需按实际模型测试启动方式命令行vllm serve、Docker 容器、脚本一键启动接口 APIOpenAI 兼容格式路径为/v1/models、/v1/chat/completions、/v1/completions批量任务支持高并发请求可通过并发客户端批量提交适合场景私有化部署、生产推理服务、批量评测、多模型接入、长上下文应用注意表格里没有写死显存数字因为不同模型的权重大小、KV Cache 分配和并发策略差太多了。比如一个 7B 模型和一个 27B MoE 模型显存需求完全是两个量级。部署前先确认模型格式和你的显卡总量再决定用不用量化、要不要上多卡。3. 适用场景与使用边界vLLM 适合这几类场景业务方需要一套自持的推理 API不想每次请求都走公网模型服务。有固定 GPU 资源希望把 Qwen、DeepSeek、Kimi 系列模型在本地跑成 OpenAI 兼容服务。需要做批量评测、批量生成对吞吐和并发有要求。需要把模型接入 LangChain、CodeBuddy、VS Code 插件、企业内部工具链。不太适合的场景没有 GPU 的纯 CPU 环境。虽然 vLLM 在特定版本支持 CPU 推理但性能远不如 GPU轻量场景建议直接走 llama.cpp 或 Ollama。只是为了玩一玩、不想管 CUDA 和依赖的环境。vLLM 更适合有一定运维能力的人。需要复杂多模态能力的项目。多模态模型支持要看具体版本和模型是否兼容不要默认都能跑。部署和使用时还要注意边界模型权重有各自的开源协议商用前先确认 license 是否允许尤其是 DeepSeek、Qwen、Kimi 系列不同版本的授权范围可能不同。服务一旦开成 HTTP 接口就相当于把模型能力暴露给了网络必须加访问控制不要直接裸奔到公网。如果业务数据涉及用户隐私、内部资料要先做脱敏再传给本地模型本地部署不等于可以随便处理敏感信息。如果接了工具调用、Agent、代码执行类功能要限制模型可调用的操作范围避免模型输出被直接执行。4. 本地部署环境准备4.1 硬件与系统检查部署 vLLM 前先确认几件事操作系统优先 Linux 服务器Ubuntu 20.04 / 22.04 比较常见。macOS 或 Windows 直接用 vLLM 会遇到不少编译和依赖问题Windows 建议用 WSL2 或 Docker。GPUNVIDIA 显卡显存越大越好。7B 模型建议 16G 以上27B 或 MoE 大模型建议 24G 以上或直接用多卡。驱动和 CUDA先确认nvidia-smi能正常输出驱动版本不要太老。Python建议 3.10 或 3.11降低依赖冲突概率。磁盘空间模型权重文件动辄几十 G预留至少模型体积两倍的剩余空间。先跑一遍检查命令nvidia-smi python --version pip --version如果nvidia-smi报错说明驱动没装好先处理 NVIDIA 驱动再继续部署。4.2 虚拟环境不建议直接往系统 Python 环境里装 vLLM依赖冲突会很难受。用一个独立虚拟环境python -m venv vllm-env source vllm-env/bin/activate后续所有安装和启动命令都在这个环境里执行。如果是 Docker 部署可以跳过虚拟环境这一步。5. 安装部署与启动方式5.1 pip 安装虚拟环境激活后直接安装pip install -U vllm如果你明确需要某个发布线比如标题中的 v0.28.0 版本可以锁定版本号安装pip install vllm0.28.0这里有个细节如果 PyPI 上找不到这个版本号说明该版本可能来自项目的分支发布或内部镜像以官方源能安装到的版本为准。版本号不同不影响下面的启动流程核心参数是通用的。安装完成后可以用vllm serve --help确认命令可用vllm serve --help5.2 Docker 启动生产环境我通常推荐 Docker依赖隔离最干净。官方提供了 OpenAI 兼容服务镜像docker pull vllm/vllm-openai:latest启动一个服务docker run --runtime nvidia --gpus all \ -v /data/models:/models \ -p 8000:8000 \ vllm/vllm-openai:latest \ --model /models/deepseek-v4-flash \ --served-model-name deepseek-v4-flash \ --gpu-memory-utilization 0.9 \ --max-model-len 32768注意/models/deepseek-v4-flash只是示例路径你要替换成自己实际的模型目录。--served-model-name是给客户端看的模型名调用 API 时model字段要填这个名字。5.3 docker-compose 部署如果模型多、参数固定建议写一份docker-compose.yml管理services: vllm: image: vllm/vllm-openai:latest container_name: vllm-server command: --model /models/qwen3-27b-awq --served-model-name qwen3-27b --tensor-parallel-size 2 --gpu-memory-utilization 0.9 --max-model-len 32768 --port 8000 ports: - 8000:8000 volumes: - /data/models:/models deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] restart: unless-stopped启动docker compose up -d查看日志docker compose logs -f5.4 常见启动参数参数作用--model模型路径或模型名--served-model-name对外暴露的模型名称--tensor-parallel-size张量并行卡数多卡时使用--gpu-memory-utilization单卡显存利用率上限默认 0.9--max-model-len最大上下文长度影响 KV Cache 分配--dtype推理精度可用auto、bfloat16等--quantization量化方式如awq、gptq、fp8--enable-prefix-caching开启前缀缓存重复 prompt 可提速--port/--host服务监听端口和地址--max-num-seqs同一时间最大处理序列数影响并发能力启动后立刻验证服务是否可用curl http://127.0.0.1:8000/v1/models如果返回模型列表说明服务已经起来了接下来进入功能测试。6. 功能测试与效果验证6.1 确认模型加载访问/v1/models是最直接的判断标准curl http://127.0.0.1:8000/v1/models输出里能看到你设置的served-model-name。如果这里是空列表说明模型没加载成功回去看启动日志。6.2 Chat Completion 接口测试用 curl 跑一个最简单的对话请求curl http://127.0.0.1:8000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: qwen3-27b, messages: [ {role: user, content: 用一句话解释什么是 PagedAttention} ], temperature: 0.7, max_tokens: 256 }返回结果里的choices[0].message.content就是模型输出。如果返回model字段和请求的模型名一致说明接口链路是通的。6.3 Python 请求测试import requests url http://127.0.0.1:8000/v1/chat/completions payload { model: qwen3-27b, messages: [ {role: system, content: 你是一个严谨的技术助手。}, {role: user, content: 介绍一下 Continuous Batching 的作用。} ], temperature: 0.3, max_tokens: 512 } resp requests.post(url, jsonpayload, timeout180) resp.raise_for_status() data resp.json() print(data[choices][0][message][content])6.4 OpenAI SDK 接入因为接口兼容 OpenAI直接用 OpenAI Python SDK 也能连from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY ) resp client.chat.completions.create( modelqwen3-27b, messages[{role: user, content: 写一段 Python 快速排序}], temperature0.2 ) print(resp.choices[0].message.content)api_key随便填一个字符串就行vLLM 主要做本地推理本身不校验 key 的合法性但这也意味着你如果暴露到公网必须自行加网关或鉴权。6.5 LangChain 接入from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen3-27b, base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY, temperature0 ) print(llm.invoke(你好介绍一下你自己))到这里服务已经可以被各种 OpenAI 兼容工具接入了。7. 接口 API 与批量任务设计7.1 API 格式vLLM 对外接口和 OpenAI 基本一致常用三个路径GET /v1/models查看模型列表POST /v1/chat/completions对话补全POST /v1/completions文本补全请求体里常用的字段字段说明model服务暴露的模型名messageschat 格式的输入消息列表promptcompletions 格式的输入文本temperature温度控制随机性max_tokens最多生成 token 数top_p核采样参数stream是否流式返回stop停止词7.2 批量提交vLLM 本身支持并发请求不需要自己在服务端排队。批量任务的思路是客户端用多线程或多进程并发提交请求服务端通过 Continuous Batching 动态调度。一个简单的批量示例import concurrent.futures import requests URL http://127.0.0.1:8000/v1/chat/completions def run_one(prompt): payload { model: qwen3-27b, messages: [{role: user, content: prompt}], max_tokens: 256 } try: resp requests.post(URL, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[choices][0][message][content] except Exception as e: return fERROR: {e} prompts [ 问题一, 问题二, 问题三, ] with concurrent.futures.ThreadPoolExecutor(max_workers8) as pool: results list(pool.map(run_one, prompts)) for p, r in zip(prompts, results): print(p, , r)并发数不要一次开太大先观察服务端显存和 CPU 占用再逐步上调。大批量任务建议加日志、做结果落盘、对失败任务做重试。7.3 失败重试服务端在高并发下偶尔会返回超时或503批量任务需要做重试import time def run_with_retry(prompt, retries3, timeout120): for attempt in range(retries): try: resp requests.post(URL, json{ model: qwen3-27b, messages: [{role: user, content: prompt}], max_tokens: 256 }, timeouttimeout) resp.raise_for_status() return resp.json()[choices][0][message][content] except Exception as e: print(fattempt {attempt 1} failed: {e}) time.sleep(2 * (attempt 1)) return ERROR生产环境中更规范的做法是把任务写进队列由 worker 进程消费失败任务重新入队。8. 资源占用与性能观察8.1 显存观察启动服务后另开一个终端执行nvidia-smi重点看显存占用是否接近你设置的--gpu-memory-utilization。如果服务启动时模型就放不下会直接报 OOM如果生成到一半才 OOM很可能是 KV Cache 分配不足或并发开太大。显存占用不只由模型权重决定上下文长度、并发数、量化格式都有影响模型越大权重占的显存越多。--max-model-len越大KV Cache 预留越多。并发数越高KV Cache 占用越大。FP8 / AWQ 量化能明显降低权重占用但要注意硬件是否支持对应精度运算。8.2 性能指标vLLM 通过--enable-metrics可以暴露 Prometheus 指标版本支持的话访问curl http://127.0.0.1:8000/metrics如果版本不支持该参数先看vllm serve --help确认参数名。观察指标时重点关注TTFT首 token 延迟。首 token 慢通常是 prefill 阶段计算量太大、上下文过长、或者模型还在加载。TPS生成吞吐。连续请求下看每秒生成 token 数衡量服务处理能力。显存占用确认是否快接近上限。8.3 性能调优方向长上下文中重复前缀多开启--enable-prefix-caching。首 token 慢适当调小--max-model-len避免 KV Cache 过度预留。生成速度慢检查是否用了量化精度和硬件不匹配比如老显卡跑 FP8。并发上不去调整--max-num-seqs和--gpu-memory-utilization的平衡。单卡放不下模型用--tensor-parallel-size 2或更多卡但卡间通信会成为新瓶颈。9. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后 API 打不开端口被占用或服务未启动curl /v1/models、ss -lntp查端口换端口、重启容器显存不足直接退出模型太大或 KV Cache 分配过多nvidia-smi看可用显存用量化模型、调低 gpu-memory-utilization、拆多卡首 token 很慢prefill 过长、磁盘加载慢、前缀缓存未开用短 prompt 对比耗时调小 max-model-len、开启 prefix caching、换 SSDFP8 部署延迟偏高硬件不支持原生 FP8 运算nvidia-smi看显卡架构换bfloat16或换支持 FP8 的新显卡多卡双卡跑不起来张量并行参数没配置看启动日志中的 TP 报错加--tensor-parallel-size 2昇腾环境部署失败缺少 Ascend 后端支持查日志和后端插件使用 vllm-ascend 和对应 CANN 环境依赖安装失败Python 版本或 CUDA 版本不匹配查看 pip 报错信息换虚拟环境、升级驱动、按官方要求装 PyTorch模型文件找不到路径或模型名写错检查--model路径和目录权限修正路径、检查挂载卷本地模型需要联网吗不需要模型推理在本地完成看访问日志是否有外网请求默认不联网联网搜索是前端工具功能Continuous Batching 怎么设置默认已开启查看启动日志确认通过--max-num-seqs控制并发规模tool-call-parser 填什么客户端对接问题查工具文档和模型工具调用说明vLLM 侧开启 auto tool choiceparser 按模型选择--dp数据并行参数失效参数名随版本变化vllm serve --help查实际参数以当前版本的帮助输出为准有一个常见误解vLLM 的 Continuous Batching 不是手动开关是框架默认的调度策略。你不需要去打开它只需要通过--max-num-seqs、--max-model-len控制它能占用的资源大小。10. 最佳实践与使用建议第一第一次跑先用最小配置验证。不要一上来就开满并发和长上下文先把服务跑通再逐步加压。第二目录要分清楚。模型、日志、输出结果分开管理/data/models /data/logs /data/outputs第三批量任务必须加日志和重试。生成类任务偶发超时是常态没有重试机制的批量任务会在跑到一半时突然崩掉。第四接口服务要加访问控制。vLLM 默认不上鉴权如果服务只在内网用限制 IP 和端口访问如果公网可访问前面必须套网关、加 key、做限流。第五涉及模型输出和素材授权要谨慎。如果生成内容要做商用先确认模型权重协议、数据来源授权并安排人工复核。第六多卡部署前先确认通信方式。张量并行在 PCIe 上也能跑但通信开销比 NVLink 高如果跨机多卡网络延迟会进一步影响性能生产环境优先同机多卡。第七版本升级前保留旧配置。vllm serve --help输出的参数在不同版本间可能有差异升级前记录当前启动命令方便回退。11. 总结与下一步vLLM v0.28.0 这版最值得尝试的点是把 Kimi-K3、DeepSeek V4 这类新一代模型的部署过程做得更顺滑同时保留了 OpenAI 兼容 API 这条非常关键的接入路径。你不需要厂商的专用 SDK一个 base_url 就能把本地模型接到 LangChain、OpenWebUI、CodeBuddy 等工具里。最先应该验证的功能是/v1/models和/v1/chat/completions。这两个接口通说明模型加载正常、请求链路正常之后再去测并发和延迟才有意义。最容易踩的坑有三个一是显存设定太激进--gpu-memory-utilization和--max-model-len配得过大请求稍微一多就 OOM二是首 token 慢但不知道是 prefill 太长还是硬件不匹配三是多卡部署时--tensor-parallel-size忘配导致大模型直接放不下。这三块都可以用前面的排查流程处理。后续可以继续扩展的方向也很明确把/metrics接到 Prometheus 和 Grafana做长期性能监控把批量任务接到消息队列做成异步任务系统再往后就是用多模型路由、请求优先级和更细粒度的调度策略去完善自建推理平台。建议先把这套部署和验证流程跑一遍收藏备用后面模型再升级排查思路全都能复用。