尧图网站建设 
vLLM 推理服务故障排查完全指南OOM、性能瓶颈与分布式部署的系统性排障手册【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLsvLLM 凭借 PagedAttention块式 KV Cache 管理与 continuous batching连续批处理成为生产环境高吞吐 LLM 服务的事实标准引擎但任何生产系统都会遇到显存耗尽、性能劣化、模型加载失败与分布式通信故障等问题。本篇指南以本仓库中 vLLM 排障文档 为核心骨架系统梳理 OOM、性能、模型加载、网络、量化、分布式六大类问题的症状—原因—解决方案并结合 vLLM 技能说明、性能优化指南、量化指南 与 服务部署模式 做纵深扩充。读完本文你将掌握一套从vllm serve启动到生产监控的完整排障方法论既能看到每个错误的直接修复命令也能理解其背后的 KV Cache 分配、PagedAttention、tensor parallelism 与 NCCL 通信原理从而具备独立诊断与调优 vLLM 服务的能力。前置知识vLLM 在本仓库中的定位与核心机制本仓库将 vLLM 封装为编号12-inference-serving下的一个 AI 技能Skill其入口为 12-inference-serving/vllm/SKILL.md技能描述定位为使用 vLLM 的 PagedAttention 与连续批处理以高吞吐量服务 LLM适用于生产 LLM API 部署、推理延迟/吞吐优化、GPU 显存受限场景支持 OpenAI 兼容端点、量化GPTQ/AWQ/FP8与张量并行。理解两个核心机制是读懂后续所有故障的前提PagedAttention将 KV Cache 划分为固定大小的块类似操作系统虚拟内存的分页机制从空闲块队列动态分配并可在不同序列间共享块服务于前缀缓存。相比传统连续内存的 KV Cache可减少约 50% 的碎片浪费——例如 70B 模型传统方式需要约 160GB KV Cache在 8×A100 上 OOMPagedAttention 下仅需约 80GB4×A100 即可承载。块大小默认 16 tokens可通过--block-size 16配置GPU 块数量由--gpu-memory-utilization自动计算。Continuous batching传统批处理要等批次内所有序列完成才释放槽位GPU 利用率仅 40%–60%连续批处理则在槽位空闲时立即接入新请求将 prefill新请求与 decode进行中请求混合同批执行GPU 利用率可超 90%吞吐提升约 4 倍。相关批处理容量由--max-num-seqs控制。快速验证环境是否正常pip install vllm # 离线推理 python -c from vllm import LLM, SamplingParams llm LLM(modelmeta-llama/Llama-3-8B-Instruct) sampling SamplingParams(temperature0.7, max_tokens256) outputs llm.generate([Explain quantum computing], sampling) print(outputs[0].outputs[0].text) # OpenAI 兼容服务 vllm serve meta-llama/Llama-3-8B-Instructvllm serve成功启动后默认监听http://localhost:8000提供/health、/v1/models、/v1/completions、/v1/chat/completions等端点——后文所有故障排查均围绕这个服务展开。本文排障命令与参数以仓库内文档为准具体默认值可能随 vLLM 版本演进而变化运行前可用vllm --version核对版本。一、显存不足OOM错误排查OOMOut of Memory是 vLLM 部署中最常见的一类故障。仓库排障文档将 OOM 细分为“模型加载阶段”“推理阶段”“量化模型”三种场景三者成因不同修复手段也不同。1.1 模型加载阶段的torch.cuda.OutOfMemoryError症状vllm serve启动加载权重时报torch.cuda.OutOfMemoryError。原因模型权重 KV Cache 的总显存需求超过单卡可用 VRAM。注意 vLLM 在启动时会按--gpu-memory-utilization的比例为 KV Cache 预留显存因此权重本身放得下、但加上 KV Cache 预留就会越界。解决方案按顺序尝试降低 GPU 显存利用率——把为 KV Cache 预留的比例从默认值调低vllm serve MODEL --gpu-memory-utilization 0.7 # Try 0.7, 0.75, 0.8减小最大序列长度——--max-model-len直接决定单条序列 KV Cache 的上限从 8192 降到 4096 可显著压缩预留vllm serve MODEL --max-model-len 4096 # Instead of 8192开启量化——4-bit 量化可将模型权重显存压缩约 4 倍vllm serve MODEL --quantization awq # 4x memory reduction使用张量并行多卡分摊——权重与 KV Cache 都会按张量并行度切分到多卡vllm serve MODEL --tensor-parallel-size 2 # Split across 2 GPUs降低最大并发序列数——--max-num-seqs决定同一时刻驻留 KV Cache 的序列上限默认 256可降到 128vllm serve MODEL --max-num-seqs 128 # Default is 2561.2 推理阶段的 OOM非模型加载症状服务启动成功、模型加载无异常但生成过程中出现 OOM。原因KV Cache 在持续生成中被填满典型触发场景是并发请求数过高或单请求max_tokens过长。解决方案# 降低 KV Cache 分配比例 vllm serve MODEL --gpu-memory-utilization 0.85 # 降低批处理容量 vllm serve MODEL --max-num-seqs 64 # 降低单请求最大 token 数 # 在客户端请求中设置: max_tokens512推理阶段 OOM 与--gpu-memory-utilization高度相关该参数越高KV Cache 可分配空间越大、批处理容量越大、吞吐越高但留给系统的余量越少、OOM 风险越高。调优本质是在吞吐与稳定性之间取平衡点详见 性能优化指南 中的“性能调优指南”一节Step 2从 0.7、0.85、0.9、0.95 逐档尝试。1.3 量化模型的 OOM症状使用量化模型时仍出现 OOM。原因量化标志与模型实际格式不匹配或 dtype 配置不当导致反量化/计算开销异常。解决方案# 确保量化标志与模型匹配——AWQ 模型必须显式指定 --quantization awq vllm serve TheBloke/Llama-2-70B-AWQ --quantization awq # Must specify # 尝试不同的 dtype vllm serve MODEL --quantization awq --dtype float161.4 内存预算参考与典型配置为什么“量化 单卡”能救 70B 模型量化指南 给出了一组直观的内存对比Llama 2 70B fp16: 140GB VRAM (4x A100 needed) Llama 2 70B AWQ: 35GB VRAM (1x A100 40GB) 4x memory reduction对应到仓库文档中“显存受限场景”的官方示例配置见 服务部署模式 的“生产配置示例”小节在 40GB 单卡上跑 70B 模型的完整方案是vllm serve TheBloke/Llama-2-70B-AWQ \ --quantization awq \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.95 \ --max-model-len 4096选型时还可参考 SKILL.md 的硬件建议7B–13B 小模型配 1×A1024GB或 A10040GB即可30B–40B 建议 2×A10040GB加张量并行70B 以上建议 4×A10040GB或 2×A10080GB并配合 AWQ/GPTQ 量化。二、性能问题定位与调优性能类问题通常表现为三类症状吞吐低、首 token 延迟TTFT高、token 生成速度慢。排障文档对每一类都给出了“诊断步骤 → 修复命令”的标准流程。2.1 低吞吐50 req/sec期望 100诊断步骤检查 GPU 利用率——这是判断“喂不饱 GPU”还是“显存瓶颈”的第一步watch -n 1 nvidia-smi # GPU utilization should be 80%若 GPU 利用率 80%说明并发请求不够、批处理没有满载应提高并发序列上限vllm serve MODEL --max-num-seqs 512 # Increase from 256判断是否显存受限——若显存已 100% 但 GPU 利用率 80%说明序列过长挤占了批容量应减小序列长度# 若显存 100% 但 GPU 80%减小序列长度 vllm serve MODEL --max-model-len 4096开启优化特性——前缀缓存与分块预填充可从两个方向提升吞吐vllm serve MODEL \ --enable-prefix-caching \ --enable-chunked-prefill \ --max-num-seqs 512核对张量并行设置——张量并行要求 GPU 数量为 2 的幂PagedAttention 的通信拓扑依赖# 必须使用 2 的幂次方 GPU 数量 vllm serve MODEL --tensor-parallel-size 4 # Not 3 or 52.2 高 TTFT首 token 延迟 1 秒TTFTTime to First Token由 prefill 阶段耗时决定排障文档按成因给出四类解法长提示词导致的 prefill 过慢——开启分块预填充将长 prefill 切成小块与 decode 交错执行降低首 token 等待vllm serve MODEL --enable-chunked-prefill未启用前缀缓存——对于系统提示词、few-shot 示例、RAG 共享上下文等重复前缀每次请求都在重复计算vllm serve MODEL --enable-prefix-caching # For repeated prompts并发请求过多——批容量过高会稀释单请求的 prefill 优先级降并发换延迟vllm serve MODEL --max-num-seqs 64 # Reduce to prioritize latency单卡装不下的大模型——prefill 阶段计算量巨大用张量并行摊薄vllm serve MODEL --tensor-parallel-size 2 # Parallelize prefill补充一点原理背景前缀缓存之所以显著提速是因为 vLLM 的 PagedAttention 允许不同序列共享同一批 KV Cache 块。以“系统提示词 500 tokens 用户输入 100 tokens”为例见 性能优化指南无缓存时每次请求计算 600 tokens有缓存时 500 tokens 只算一次、之后每请求仅算 100 tokensTTFT 可降低约 83%且前缀检测完全自动、无需改代码。2.3 Token 生成速度慢tokens/sec 低诊断# 检查模型尺寸是否正确日志中应能看到模型大小 vllm serve MODEL # Should see model size in logs # 检查投机解码speculative decoding vllm serve MODEL --speculative-model DRAFT_MODELH100 GPU 上优先启用 FP8——FP8 是 Hopper 架构的原生加速格式vllm serve MODEL --quantization fp8投机解码是提升 decode 速度的利器用一个小 5–10 倍的草稿模型draft model先快速提出 K 个 token目标模型一次前向并行验证全部 K 个 token接受验证通过的 token、从第一个被拒的 token 处重新开始可将单次前向推进 3–5 个 token、生成提速 2–3 倍。完整配置方式见 性能优化指南 的“投机解码设置”一节# 独立草稿模型 vllm serve meta-llama/Llama-3-70B-Instruct \ --speculative-model TinyLlama/TinyLlama-1.1B-Chat-v1.0 \ --num-speculative-tokens 5 # 无需额外模型的 n-gram 草稿 vllm serve MODEL \ --speculative-method ngram \ --num-speculative-tokens 3适用条件输出长度 100 tokens、草稿模型比目标模型小 5–10 倍、可接受 2–3% 的准确率折损。2.4 系统化性能调优流程性能优化指南 将调优固化为可复现的五步流程建议排障时照此执行测量基线运行vllm bench throughput记录吞吐、TTFT、tokens/sec 三项基线调优显存利用率--gpu-memory-utilization依次尝试 0.7、0.85、0.9、0.95更高值 更大批容量 更高吞吐但有 OOM 风险调优并发--max-num-seqs依次尝试 128、256、512、1024更高值 更多批处理机会但可能抬高延迟开启优化特性--enable-prefix-caching重复提示词--enable-chunked-prefill长提示词--gpu-memory-utilization 0.9--max-num-seqs 512复测对比目标为吞吐 30%–100%、TTFT -20%–50%、GPU 利用率 85%。三、模型加载错误3.1OSError: MODEL not found原因与解法模型名拼写错误——HuggingFace 模型名区分大小写# 核对 HuggingFace 上的精确模型名注意大小写 vllm serve meta-llama/Llama-3-8B-Instruct # Correct capitalization私有/门控模型gated model——需要先登录 HuggingFace 获取访问凭证# 先登录 HuggingFace huggingface-cli login # 再启动 vLLM vllm serve meta-llama/Llama-3-70B-Instruct自定义模型需要信任远程代码——模型仓库中带有自定义建模代码custom_modeling_*.py时vllm serve MODEL --trust-remote-code3.2ValueError: Tokenizer not found解法先用 transformers 手动下载 tokenizer再启动 vLLM# 先手动下载模型 python -c from transformers import AutoTokenizer; AutoTokenizer.from_pretrained(MODEL) # 再启动 vLLM vllm serve MODEL3.3ImportError: No module named flash_attn解法# 安装 flash attention pip install flash-attn --no-build-isolation # 或禁用 flash attention vllm serve MODEL --disable-flash-attn注意flash-attn 属于编译型依赖--no-build-isolation是让 pip 复用系统已有编译环境、避免隔离环境缺少构建依赖若构建失败可检查 CUDA 工具链版本后再重试。四、网络与连接问题4.1Connection refused连接被拒诊断三步确认服务在运行curl http://localhost:8000/health检查端口绑定——默认只绑定回环地址远程访问需显式绑定所有网卡同时排查端口占用# 绑定所有网卡以便远程访问 vllm serve MODEL --host 0.0.0.0 --port 8000 # 检查端口是否被占用 lsof -i :8000检查防火墙# 放行端口 sudo ufw allow 8000关于健康检查服务部署模式 还提供了更完整的就绪等待脚本Kubernetes readinessProbe 同款逻辑/health返回{status: ok}即代表模型加载完成、服务可接收流量。4.2 网络响应缓慢解决方案增大客户端超时——大模型生成动辄数十秒默认短超时会导致误判失败from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, timeout300.0 # 5 分钟超时 )检查网络延迟ping SERVER_IP # 局域网内应 10ms使用连接池与重试——高并发场景下复用 TCP 连接、对瞬时失败自动重试import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry session requests.Session() retries Retry(total3, backoff_factor1) session.mount(http://, HTTPAdapter(max_retriesretries))若要在多副本之间做负载均衡服务部署模式 提供了 Nginx 配置模板上游使用least_conn策略路由到多个 vLLM 实例如 localhost:8001/8002/8003并将proxy_read_timeout调大到 300s 以容忍长推理——这与第 1 点“增大超时”是同一思路的服务端实现。五、量化问题排查5.1RuntimeError: Quantization format not supported原因--quantization指定的方法与模型实际量化格式不一致。解法是让标志与模型格式严格对应# 确保量化方法与模型匹配 vllm serve MODEL --quantization awq # 针对 AWQ 模型 vllm serve MODEL --quantization gptq # 针对 GPTQ 模型 # 查看模型卡片确认量化类型5.2 量化后输出质量下降诊断验证模型确实被正确量化——检查下载缓存中的config.json是否含quantization_config字段# 检查模型 config.json 中的 quantization_config cat ~/.cache/huggingface/hub/models--MODEL/config.json尝试不同量化方法# 若 AWQ 质量不佳尝试 FP8仅 H100 vllm serve MODEL --quantization fp8 # 或使用更温和的量化甚至不量化 vllm serve MODEL # No quantization提高采样温度以增加多样性sampling_params SamplingParams(temperature0.8, top_p0.95)5.3 量化方法选型与准确率权衡量化问题的根源往往在选型阶段。 量化指南 给出了完整的选型矩阵方法压缩率精度损失速度最佳适用场景AWQ4-bit75%1%快70B 模型、生产环境GPTQ4-bit75%1-2%快模型支持面最广FP88-bit50%0.5%最快仅限 H100 GPUSqueezeLLM3-4 bit75-80%2-3%中极限压缩官方推荐生产环境 70B 模型用 AWQH100 用 FP8 换取最佳速度追求最大兼容性用 GPTQ极限压缩用 SqueezeLLM。FP8 需要 H100/H800 GPU CUDA 12.3推荐 12.8且支持运行时动态量化无需预量化模型直接vllm serve MODEL --quantization fp8即可。准确率验证有一套标准流程同样来自 量化指南先测 FP16 基线准确率 → 量化 → 在同一评测集上对比 → 若退化幅度 1%–2% 阈值则判定可上生产。量化模型的校准数据建议取 128–512 条目标领域多样样本数据质量直接决定量化后精度。六、分布式服务问题6.1RuntimeError: Distributed init failed诊断检查环境变量一致性——分布式初始化依赖四件套必须逐节点核对# 在所有节点上 echo $MASTER_ADDR # 各节点应相同主节点地址 echo $MASTER_PORT # 各节点应相同 echo $RANK # 每节点应唯一0, 1, 2, ... echo $WORLD_SIZE # 各节点应相同总节点数检查网络连通性# 从节点 1 ping 节点 2 ping NODE2_IP nc -zv NODE2_IP 29500 # 检查端口可达性检查 NCCL 设置export NCCL_DEBUGINFO export NCCL_SOCKET_IFNAMEeth0 # 或你的实际网卡名 vllm serve MODEL --tensor-parallel-size 86.2NCCL error: unhandled cuda error解决方案# 指定正确的网卡接口 export NCCL_SOCKET_IFNAMEeth0 # 替换为你的网卡名 # 增大超时 export NCCL_TIMEOUT1800 # 30 分钟 # 强制关闭 P2P 用于调试 export NCCL_P2P_DISABLE16.3 多节点部署环境核对清单分布式初始化失败大多是环境不一致所致服务部署模式 给出了多节点张量/流水线并行的完整样板可直接作为核对基线——以 2 节点、每节点 8 卡、70B 模型为例Node 1主节点export MASTER_ADDR192.168.1.10 export MASTER_PORT29500 export RANK0 export WORLD_SIZE2 vllm serve meta-llama/Llama-2-70b-hf \ --tensor-parallel-size 8 \ --pipeline-parallel-size 2Node 2工作节点export MASTER_ADDR192.168.1.10 export MASTER_PORT29500 export RANK1 export WORLD_SIZE2 vllm serve meta-llama/Llama-2-70b-hf \ --tensor-parallel-size 8 \ --pipeline-parallel-size 2排障时逐项对照MASTER_ADDR/MASTER_PORT/WORLD_SIZE是否全集群一致、RANK是否唯一、NCCL_SOCKET_IFNAME是否指向真实可用的高速网卡。若启用 InfiniBand还需确认NCCL_IB_DISABLE0。七、调试工具与命令速查7.1 开启 Debug 日志export VLLM_LOGGING_LEVELDEBUG vllm serve MODEL7.2 监控 GPU 使用# 实时 GPU 监控 watch -n 1 nvidia-smi # 内存明细 nvidia-smi --query-gpumemory.used,memory.free --formatcsv -l 17.3 性能基准测试vLLM 内置基准工具可分别压测吞吐与延迟# 内置吞吐基准 vllm bench throughput \ --model MODEL \ --input-tokens 128 \ --output-tokens 256 \ --num-prompts 100 # 内置延迟基准 vllm bench latency \ --model MODEL \ --input-tokens 128 \ --output-tokens 256 \ --batch-size 87.4 Prometheus 指标检查vLLM 默认暴露 Prometheus 指标端点是量化“是否健康”的客观依据# Prometheus 指标 curl http://localhost:9090/metrics # 过滤特定指标 curl http://localhost:9090/metrics | grep vllm_time_to_first_token # 关键监控指标: # - vllm_time_to_first_token_seconds 首 token 延迟 # - vllm_time_per_output_token_seconds 每输出 token 耗时 # - vllm_num_requests_running 运行中请求数 # - vllm_gpu_cache_usage_perc KV Cache 利用率 # - vllm_request_success_total 成功请求总数对应到 服务部署模式 的 Grafana 面板公式请求 QPS 用rate(vllm_request_success_total[5m])TTFT p50/p99 用histogram_quantile(0.5/0.99, vllm_time_to_first_token_seconds_bucket)结合vllm_gpu_cache_usage_perc可判断是否临近 OOM 水位。7.5 服务健康测试# 健康检查 curl http://localhost:8000/health # 模型信息 curl http://localhost:8000/v1/models # 测试补全接口 curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: MODEL, prompt: Hello, max_tokens: 10 }7.6 常用环境变量# CUDA 设置 export CUDA_VISIBLE_DEVICES0,1,2,3 # 限定使用指定 GPU # vLLM 设置 export VLLM_LOGGING_LEVELDEBUG export VLLM_TRACE_FUNCTION1 # 函数级性能剖析 export VLLM_USE_V11 # 使用 v1.0 引擎更快 # NCCL 设置分布式 export NCCL_DEBUGINFO export NCCL_SOCKET_IFNAMEeth0 export NCCL_IB_DISABLE0 # 启用 InfiniBand7.7 收集 Bug 报告诊断信息向社区或团队提交 Bug 报告时按此清单收集证据保证可复现# 系统信息 nvidia-smi python --version pip show vllm # vLLM 版本与配置 vllm --version python -c import vllm; print(vllm.__version__) # 带 Debug 日志运行并落盘 export VLLM_LOGGING_LEVELDEBUG vllm serve MODEL 21 | tee vllm_debug.log # 报告中应包含: # - vllm_debug.log # - nvidia-smi 输出 # - 完整启动命令 # - 期望行为与实际行为附录排障速查表与参考文档按症状索引的快速定位表症状首选手段对应章节加载时 OOM降--gpu-memory-utilization、--max-model-len上量化第一章推理时 OOM降--max-num-seqs、客户端限max_tokens第一章吞吐 50 req/sec提--max-num-seqs、开前缀缓存、核对 GPU 利用率第二章TTFT 1 秒--enable-chunked-prefill、--enable-prefix-caching第二章生成慢投机解码、H100 上 FP8第二章模型找不到核对拼写、huggingface-cli login、--trust-remote-code第三章连接被拒/health探测、--host 0.0.0.0、防火墙第四章量化格式不支持让--quantization与模型格式严格一致第五章分布式初始化失败核对MASTER_*/RANK/WORLD_SIZE、NCCL 设置第六章本仓库相关参考文档以仓库根目录为起点的相对路径vLLM 排障文档本文核心来源vLLM 技能说明与快速上手性能优化指南PagedAttention、连续批处理、前缀缓存、投机解码、基准数据量化指南AWQ/GPTQ/FP8 选型、模型制备、准确率权衡服务部署模式Docker、Kubernetes、Nginx 负载均衡、多节点部署、监控本仓库同为推理服务类的技能还包括 sglang、tensorrt-llm、llama-cpp 等若 vLLM 的排障手段不足以满足特定场景如 CPU/边缘部署、NVIDIA 极限性能可交叉查阅对应技能文档。牢记排障的第一原则先量化看指标、再定位分场景、后调参一次只改一个变量配合本文的调试工具清单绝大多数 vLLM 生产问题都可以在十分钟内收敛。【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 vLLM 推理服务故障排查完全指南：OOM、性能瓶颈与分布式部署的系统性排障手册
vLLM 推理服务故障排查完全指南OOM、性能瓶颈与分布式部署的系统性排障手册【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLsvLLM 凭借 PagedAttention块式 KV Cache 管理与 continuous batching连续批处理成为生产环境高吞吐 LLM 服务的事实标准引擎但任何生产系统都会遇到显存耗尽、性能劣化、模型加载失败与分布式通信故障等问题。本篇指南以本仓库中 vLLM 排障文档 为核心骨架系统梳理 OOM、性能、模型加载、网络、量化、分布式六大类问题的症状—原因—解决方案并结合 vLLM 技能说明、性能优化指南、量化指南 与 服务部署模式 做纵深扩充。读完本文你将掌握一套从vllm serve启动到生产监控的完整排障方法论既能看到每个错误的直接修复命令也能理解其背后的 KV Cache 分配、PagedAttention、tensor parallelism 与 NCCL 通信原理从而具备独立诊断与调优 vLLM 服务的能力。前置知识vLLM 在本仓库中的定位与核心机制本仓库将 vLLM 封装为编号12-inference-serving下的一个 AI 技能Skill其入口为 12-inference-serving/vllm/SKILL.md技能描述定位为使用 vLLM 的 PagedAttention 与连续批处理以高吞吐量服务 LLM适用于生产 LLM API 部署、推理延迟/吞吐优化、GPU 显存受限场景支持 OpenAI 兼容端点、量化GPTQ/AWQ/FP8与张量并行。理解两个核心机制是读懂后续所有故障的前提PagedAttention将 KV Cache 划分为固定大小的块类似操作系统虚拟内存的分页机制从空闲块队列动态分配并可在不同序列间共享块服务于前缀缓存。相比传统连续内存的 KV Cache可减少约 50% 的碎片浪费——例如 70B 模型传统方式需要约 160GB KV Cache在 8×A100 上 OOMPagedAttention 下仅需约 80GB4×A100 即可承载。块大小默认 16 tokens可通过--block-size 16配置GPU 块数量由--gpu-memory-utilization自动计算。Continuous batching传统批处理要等批次内所有序列完成才释放槽位GPU 利用率仅 40%–60%连续批处理则在槽位空闲时立即接入新请求将 prefill新请求与 decode进行中请求混合同批执行GPU 利用率可超 90%吞吐提升约 4 倍。相关批处理容量由--max-num-seqs控制。快速验证环境是否正常pip install vllm # 离线推理 python -c from vllm import LLM, SamplingParams llm LLM(modelmeta-llama/Llama-3-8B-Instruct) sampling SamplingParams(temperature0.7, max_tokens256) outputs llm.generate([Explain quantum computing], sampling) print(outputs[0].outputs[0].text) # OpenAI 兼容服务 vllm serve meta-llama/Llama-3-8B-Instructvllm serve成功启动后默认监听http://localhost:8000提供/health、/v1/models、/v1/completions、/v1/chat/completions等端点——后文所有故障排查均围绕这个服务展开。本文排障命令与参数以仓库内文档为准具体默认值可能随 vLLM 版本演进而变化运行前可用vllm --version核对版本。一、显存不足OOM错误排查OOMOut of Memory是 vLLM 部署中最常见的一类故障。仓库排障文档将 OOM 细分为“模型加载阶段”“推理阶段”“量化模型”三种场景三者成因不同修复手段也不同。1.1 模型加载阶段的torch.cuda.OutOfMemoryError症状vllm serve启动加载权重时报torch.cuda.OutOfMemoryError。原因模型权重 KV Cache 的总显存需求超过单卡可用 VRAM。注意 vLLM 在启动时会按--gpu-memory-utilization的比例为 KV Cache 预留显存因此权重本身放得下、但加上 KV Cache 预留就会越界。解决方案按顺序尝试降低 GPU 显存利用率——把为 KV Cache 预留的比例从默认值调低vllm serve MODEL --gpu-memory-utilization 0.7 # Try 0.7, 0.75, 0.8减小最大序列长度——--max-model-len直接决定单条序列 KV Cache 的上限从 8192 降到 4096 可显著压缩预留vllm serve MODEL --max-model-len 4096 # Instead of 8192开启量化——4-bit 量化可将模型权重显存压缩约 4 倍vllm serve MODEL --quantization awq # 4x memory reduction使用张量并行多卡分摊——权重与 KV Cache 都会按张量并行度切分到多卡vllm serve MODEL --tensor-parallel-size 2 # Split across 2 GPUs降低最大并发序列数——--max-num-seqs决定同一时刻驻留 KV Cache 的序列上限默认 256可降到 128vllm serve MODEL --max-num-seqs 128 # Default is 2561.2 推理阶段的 OOM非模型加载症状服务启动成功、模型加载无异常但生成过程中出现 OOM。原因KV Cache 在持续生成中被填满典型触发场景是并发请求数过高或单请求max_tokens过长。解决方案# 降低 KV Cache 分配比例 vllm serve MODEL --gpu-memory-utilization 0.85 # 降低批处理容量 vllm serve MODEL --max-num-seqs 64 # 降低单请求最大 token 数 # 在客户端请求中设置: max_tokens512推理阶段 OOM 与--gpu-memory-utilization高度相关该参数越高KV Cache 可分配空间越大、批处理容量越大、吞吐越高但留给系统的余量越少、OOM 风险越高。调优本质是在吞吐与稳定性之间取平衡点详见 性能优化指南 中的“性能调优指南”一节Step 2从 0.7、0.85、0.9、0.95 逐档尝试。1.3 量化模型的 OOM症状使用量化模型时仍出现 OOM。原因量化标志与模型实际格式不匹配或 dtype 配置不当导致反量化/计算开销异常。解决方案# 确保量化标志与模型匹配——AWQ 模型必须显式指定 --quantization awq vllm serve TheBloke/Llama-2-70B-AWQ --quantization awq # Must specify # 尝试不同的 dtype vllm serve MODEL --quantization awq --dtype float161.4 内存预算参考与典型配置为什么“量化 单卡”能救 70B 模型量化指南 给出了一组直观的内存对比Llama 2 70B fp16: 140GB VRAM (4x A100 needed) Llama 2 70B AWQ: 35GB VRAM (1x A100 40GB) 4x memory reduction对应到仓库文档中“显存受限场景”的官方示例配置见 服务部署模式 的“生产配置示例”小节在 40GB 单卡上跑 70B 模型的完整方案是vllm serve TheBloke/Llama-2-70B-AWQ \ --quantization awq \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.95 \ --max-model-len 4096选型时还可参考 SKILL.md 的硬件建议7B–13B 小模型配 1×A1024GB或 A10040GB即可30B–40B 建议 2×A10040GB加张量并行70B 以上建议 4×A10040GB或 2×A10080GB并配合 AWQ/GPTQ 量化。二、性能问题定位与调优性能类问题通常表现为三类症状吞吐低、首 token 延迟TTFT高、token 生成速度慢。排障文档对每一类都给出了“诊断步骤 → 修复命令”的标准流程。2.1 低吞吐50 req/sec期望 100诊断步骤检查 GPU 利用率——这是判断“喂不饱 GPU”还是“显存瓶颈”的第一步watch -n 1 nvidia-smi # GPU utilization should be 80%若 GPU 利用率 80%说明并发请求不够、批处理没有满载应提高并发序列上限vllm serve MODEL --max-num-seqs 512 # Increase from 256判断是否显存受限——若显存已 100% 但 GPU 利用率 80%说明序列过长挤占了批容量应减小序列长度# 若显存 100% 但 GPU 80%减小序列长度 vllm serve MODEL --max-model-len 4096开启优化特性——前缀缓存与分块预填充可从两个方向提升吞吐vllm serve MODEL \ --enable-prefix-caching \ --enable-chunked-prefill \ --max-num-seqs 512核对张量并行设置——张量并行要求 GPU 数量为 2 的幂PagedAttention 的通信拓扑依赖# 必须使用 2 的幂次方 GPU 数量 vllm serve MODEL --tensor-parallel-size 4 # Not 3 or 52.2 高 TTFT首 token 延迟 1 秒TTFTTime to First Token由 prefill 阶段耗时决定排障文档按成因给出四类解法长提示词导致的 prefill 过慢——开启分块预填充将长 prefill 切成小块与 decode 交错执行降低首 token 等待vllm serve MODEL --enable-chunked-prefill未启用前缀缓存——对于系统提示词、few-shot 示例、RAG 共享上下文等重复前缀每次请求都在重复计算vllm serve MODEL --enable-prefix-caching # For repeated prompts并发请求过多——批容量过高会稀释单请求的 prefill 优先级降并发换延迟vllm serve MODEL --max-num-seqs 64 # Reduce to prioritize latency单卡装不下的大模型——prefill 阶段计算量巨大用张量并行摊薄vllm serve MODEL --tensor-parallel-size 2 # Parallelize prefill补充一点原理背景前缀缓存之所以显著提速是因为 vLLM 的 PagedAttention 允许不同序列共享同一批 KV Cache 块。以“系统提示词 500 tokens 用户输入 100 tokens”为例见 性能优化指南无缓存时每次请求计算 600 tokens有缓存时 500 tokens 只算一次、之后每请求仅算 100 tokensTTFT 可降低约 83%且前缀检测完全自动、无需改代码。2.3 Token 生成速度慢tokens/sec 低诊断# 检查模型尺寸是否正确日志中应能看到模型大小 vllm serve MODEL # Should see model size in logs # 检查投机解码speculative decoding vllm serve MODEL --speculative-model DRAFT_MODELH100 GPU 上优先启用 FP8——FP8 是 Hopper 架构的原生加速格式vllm serve MODEL --quantization fp8投机解码是提升 decode 速度的利器用一个小 5–10 倍的草稿模型draft model先快速提出 K 个 token目标模型一次前向并行验证全部 K 个 token接受验证通过的 token、从第一个被拒的 token 处重新开始可将单次前向推进 3–5 个 token、生成提速 2–3 倍。完整配置方式见 性能优化指南 的“投机解码设置”一节# 独立草稿模型 vllm serve meta-llama/Llama-3-70B-Instruct \ --speculative-model TinyLlama/TinyLlama-1.1B-Chat-v1.0 \ --num-speculative-tokens 5 # 无需额外模型的 n-gram 草稿 vllm serve MODEL \ --speculative-method ngram \ --num-speculative-tokens 3适用条件输出长度 100 tokens、草稿模型比目标模型小 5–10 倍、可接受 2–3% 的准确率折损。2.4 系统化性能调优流程性能优化指南 将调优固化为可复现的五步流程建议排障时照此执行测量基线运行vllm bench throughput记录吞吐、TTFT、tokens/sec 三项基线调优显存利用率--gpu-memory-utilization依次尝试 0.7、0.85、0.9、0.95更高值 更大批容量 更高吞吐但有 OOM 风险调优并发--max-num-seqs依次尝试 128、256、512、1024更高值 更多批处理机会但可能抬高延迟开启优化特性--enable-prefix-caching重复提示词--enable-chunked-prefill长提示词--gpu-memory-utilization 0.9--max-num-seqs 512复测对比目标为吞吐 30%–100%、TTFT -20%–50%、GPU 利用率 85%。三、模型加载错误3.1OSError: MODEL not found原因与解法模型名拼写错误——HuggingFace 模型名区分大小写# 核对 HuggingFace 上的精确模型名注意大小写 vllm serve meta-llama/Llama-3-8B-Instruct # Correct capitalization私有/门控模型gated model——需要先登录 HuggingFace 获取访问凭证# 先登录 HuggingFace huggingface-cli login # 再启动 vLLM vllm serve meta-llama/Llama-3-70B-Instruct自定义模型需要信任远程代码——模型仓库中带有自定义建模代码custom_modeling_*.py时vllm serve MODEL --trust-remote-code3.2ValueError: Tokenizer not found解法先用 transformers 手动下载 tokenizer再启动 vLLM# 先手动下载模型 python -c from transformers import AutoTokenizer; AutoTokenizer.from_pretrained(MODEL) # 再启动 vLLM vllm serve MODEL3.3ImportError: No module named flash_attn解法# 安装 flash attention pip install flash-attn --no-build-isolation # 或禁用 flash attention vllm serve MODEL --disable-flash-attn注意flash-attn 属于编译型依赖--no-build-isolation是让 pip 复用系统已有编译环境、避免隔离环境缺少构建依赖若构建失败可检查 CUDA 工具链版本后再重试。四、网络与连接问题4.1Connection refused连接被拒诊断三步确认服务在运行curl http://localhost:8000/health检查端口绑定——默认只绑定回环地址远程访问需显式绑定所有网卡同时排查端口占用# 绑定所有网卡以便远程访问 vllm serve MODEL --host 0.0.0.0 --port 8000 # 检查端口是否被占用 lsof -i :8000检查防火墙# 放行端口 sudo ufw allow 8000关于健康检查服务部署模式 还提供了更完整的就绪等待脚本Kubernetes readinessProbe 同款逻辑/health返回{status: ok}即代表模型加载完成、服务可接收流量。4.2 网络响应缓慢解决方案增大客户端超时——大模型生成动辄数十秒默认短超时会导致误判失败from openai import OpenAI client OpenAI( base_urlhttp://localhost:8000/v1, api_keyEMPTY, timeout300.0 # 5 分钟超时 )检查网络延迟ping SERVER_IP # 局域网内应 10ms使用连接池与重试——高并发场景下复用 TCP 连接、对瞬时失败自动重试import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry session requests.Session() retries Retry(total3, backoff_factor1) session.mount(http://, HTTPAdapter(max_retriesretries))若要在多副本之间做负载均衡服务部署模式 提供了 Nginx 配置模板上游使用least_conn策略路由到多个 vLLM 实例如 localhost:8001/8002/8003并将proxy_read_timeout调大到 300s 以容忍长推理——这与第 1 点“增大超时”是同一思路的服务端实现。五、量化问题排查5.1RuntimeError: Quantization format not supported原因--quantization指定的方法与模型实际量化格式不一致。解法是让标志与模型格式严格对应# 确保量化方法与模型匹配 vllm serve MODEL --quantization awq # 针对 AWQ 模型 vllm serve MODEL --quantization gptq # 针对 GPTQ 模型 # 查看模型卡片确认量化类型5.2 量化后输出质量下降诊断验证模型确实被正确量化——检查下载缓存中的config.json是否含quantization_config字段# 检查模型 config.json 中的 quantization_config cat ~/.cache/huggingface/hub/models--MODEL/config.json尝试不同量化方法# 若 AWQ 质量不佳尝试 FP8仅 H100 vllm serve MODEL --quantization fp8 # 或使用更温和的量化甚至不量化 vllm serve MODEL # No quantization提高采样温度以增加多样性sampling_params SamplingParams(temperature0.8, top_p0.95)5.3 量化方法选型与准确率权衡量化问题的根源往往在选型阶段。 量化指南 给出了完整的选型矩阵方法压缩率精度损失速度最佳适用场景AWQ4-bit75%1%快70B 模型、生产环境GPTQ4-bit75%1-2%快模型支持面最广FP88-bit50%0.5%最快仅限 H100 GPUSqueezeLLM3-4 bit75-80%2-3%中极限压缩官方推荐生产环境 70B 模型用 AWQH100 用 FP8 换取最佳速度追求最大兼容性用 GPTQ极限压缩用 SqueezeLLM。FP8 需要 H100/H800 GPU CUDA 12.3推荐 12.8且支持运行时动态量化无需预量化模型直接vllm serve MODEL --quantization fp8即可。准确率验证有一套标准流程同样来自 量化指南先测 FP16 基线准确率 → 量化 → 在同一评测集上对比 → 若退化幅度 1%–2% 阈值则判定可上生产。量化模型的校准数据建议取 128–512 条目标领域多样样本数据质量直接决定量化后精度。六、分布式服务问题6.1RuntimeError: Distributed init failed诊断检查环境变量一致性——分布式初始化依赖四件套必须逐节点核对# 在所有节点上 echo $MASTER_ADDR # 各节点应相同主节点地址 echo $MASTER_PORT # 各节点应相同 echo $RANK # 每节点应唯一0, 1, 2, ... echo $WORLD_SIZE # 各节点应相同总节点数检查网络连通性# 从节点 1 ping 节点 2 ping NODE2_IP nc -zv NODE2_IP 29500 # 检查端口可达性检查 NCCL 设置export NCCL_DEBUGINFO export NCCL_SOCKET_IFNAMEeth0 # 或你的实际网卡名 vllm serve MODEL --tensor-parallel-size 86.2NCCL error: unhandled cuda error解决方案# 指定正确的网卡接口 export NCCL_SOCKET_IFNAMEeth0 # 替换为你的网卡名 # 增大超时 export NCCL_TIMEOUT1800 # 30 分钟 # 强制关闭 P2P 用于调试 export NCCL_P2P_DISABLE16.3 多节点部署环境核对清单分布式初始化失败大多是环境不一致所致服务部署模式 给出了多节点张量/流水线并行的完整样板可直接作为核对基线——以 2 节点、每节点 8 卡、70B 模型为例Node 1主节点export MASTER_ADDR192.168.1.10 export MASTER_PORT29500 export RANK0 export WORLD_SIZE2 vllm serve meta-llama/Llama-2-70b-hf \ --tensor-parallel-size 8 \ --pipeline-parallel-size 2Node 2工作节点export MASTER_ADDR192.168.1.10 export MASTER_PORT29500 export RANK1 export WORLD_SIZE2 vllm serve meta-llama/Llama-2-70b-hf \ --tensor-parallel-size 8 \ --pipeline-parallel-size 2排障时逐项对照MASTER_ADDR/MASTER_PORT/WORLD_SIZE是否全集群一致、RANK是否唯一、NCCL_SOCKET_IFNAME是否指向真实可用的高速网卡。若启用 InfiniBand还需确认NCCL_IB_DISABLE0。七、调试工具与命令速查7.1 开启 Debug 日志export VLLM_LOGGING_LEVELDEBUG vllm serve MODEL7.2 监控 GPU 使用# 实时 GPU 监控 watch -n 1 nvidia-smi # 内存明细 nvidia-smi --query-gpumemory.used,memory.free --formatcsv -l 17.3 性能基准测试vLLM 内置基准工具可分别压测吞吐与延迟# 内置吞吐基准 vllm bench throughput \ --model MODEL \ --input-tokens 128 \ --output-tokens 256 \ --num-prompts 100 # 内置延迟基准 vllm bench latency \ --model MODEL \ --input-tokens 128 \ --output-tokens 256 \ --batch-size 87.4 Prometheus 指标检查vLLM 默认暴露 Prometheus 指标端点是量化“是否健康”的客观依据# Prometheus 指标 curl http://localhost:9090/metrics # 过滤特定指标 curl http://localhost:9090/metrics | grep vllm_time_to_first_token # 关键监控指标: # - vllm_time_to_first_token_seconds 首 token 延迟 # - vllm_time_per_output_token_seconds 每输出 token 耗时 # - vllm_num_requests_running 运行中请求数 # - vllm_gpu_cache_usage_perc KV Cache 利用率 # - vllm_request_success_total 成功请求总数对应到 服务部署模式 的 Grafana 面板公式请求 QPS 用rate(vllm_request_success_total[5m])TTFT p50/p99 用histogram_quantile(0.5/0.99, vllm_time_to_first_token_seconds_bucket)结合vllm_gpu_cache_usage_perc可判断是否临近 OOM 水位。7.5 服务健康测试# 健康检查 curl http://localhost:8000/health # 模型信息 curl http://localhost:8000/v1/models # 测试补全接口 curl http://localhost:8000/v1/completions \ -H Content-Type: application/json \ -d { model: MODEL, prompt: Hello, max_tokens: 10 }7.6 常用环境变量# CUDA 设置 export CUDA_VISIBLE_DEVICES0,1,2,3 # 限定使用指定 GPU # vLLM 设置 export VLLM_LOGGING_LEVELDEBUG export VLLM_TRACE_FUNCTION1 # 函数级性能剖析 export VLLM_USE_V11 # 使用 v1.0 引擎更快 # NCCL 设置分布式 export NCCL_DEBUGINFO export NCCL_SOCKET_IFNAMEeth0 export NCCL_IB_DISABLE0 # 启用 InfiniBand7.7 收集 Bug 报告诊断信息向社区或团队提交 Bug 报告时按此清单收集证据保证可复现# 系统信息 nvidia-smi python --version pip show vllm # vLLM 版本与配置 vllm --version python -c import vllm; print(vllm.__version__) # 带 Debug 日志运行并落盘 export VLLM_LOGGING_LEVELDEBUG vllm serve MODEL 21 | tee vllm_debug.log # 报告中应包含: # - vllm_debug.log # - nvidia-smi 输出 # - 完整启动命令 # - 期望行为与实际行为附录排障速查表与参考文档按症状索引的快速定位表症状首选手段对应章节加载时 OOM降--gpu-memory-utilization、--max-model-len上量化第一章推理时 OOM降--max-num-seqs、客户端限max_tokens第一章吞吐 50 req/sec提--max-num-seqs、开前缀缓存、核对 GPU 利用率第二章TTFT 1 秒--enable-chunked-prefill、--enable-prefix-caching第二章生成慢投机解码、H100 上 FP8第二章模型找不到核对拼写、huggingface-cli login、--trust-remote-code第三章连接被拒/health探测、--host 0.0.0.0、防火墙第四章量化格式不支持让--quantization与模型格式严格一致第五章分布式初始化失败核对MASTER_*/RANK/WORLD_SIZE、NCCL 设置第六章本仓库相关参考文档以仓库根目录为起点的相对路径vLLM 排障文档本文核心来源vLLM 技能说明与快速上手性能优化指南PagedAttention、连续批处理、前缀缓存、投机解码、基准数据量化指南AWQ/GPTQ/FP8 选型、模型制备、准确率权衡服务部署模式Docker、Kubernetes、Nginx 负载均衡、多节点部署、监控本仓库同为推理服务类的技能还包括 sglang、tensorrt-llm、llama-cpp 等若 vLLM 的排障手段不足以满足特定场景如 CPU/边缘部署、NVIDIA 极限性能可交叉查阅对应技能文档。牢记排障的第一原则先量化看指标、再定位分场景、后调参一次只改一个变量配合本文的调试工具清单绝大多数 vLLM 生产问题都可以在十分钟内收敛。【免费下载链接】AI-Research-SKILLsComprehensive open-source library of AI research and engineering skills for any AI model. Package the skills and your claude code/codex/gemini agent will be an AI research agent with full horsepower. Maintained by Orchestra Research.项目地址: https://gitcode.com/gh_mirrors/ai/AI-Research-SKILLs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考