vllm

vLLM 推理服务

使用此技能将 vLLM 作为生产级推理服务运行：通过 Docker 或 Kubernetes 部署，配置模型和引擎（量化、张量并行、KV 缓存、上下文长度），提供 OpenAI 兼容的 API 接口，使用可比较的证据对吞吐量和延迟进行基准测试，调整连续批处理，运维底层 GPU，并安全升级或回滚。这是一个针对某个指定引擎的工具技能。服务方法论——引擎选择、量化权衡、部署计划、回归问题排查——属于 ml-engineering；使用 llama.cpp 技术栈在本地单节点上提供 GGUF 服务，则属于 llama-cpp。此技能负责 vLLM 本身的日常运维。

运维约定

1. 调优前记录部署信息。 记录 vLLM 版本或镜像摘要、模型及其修订版本、量化方式、并行配置、max-model-len、KV 缓存设置、批处理上限、GPU 清单和工作负载。服务配置模板正是为此准备的。
2. 操作前确认目标、范围和回滚路径。 只读探查（健康探测、/metrics、nvidia-smi）无需确认即可进行。变更操作——重启服务、更改服务参数、扩展副本、升级镜像——必须获得明确的人类指示，并指定部署目标。
3. 服务有响应，不代表它正在提供服务。 /health 返回 200 只能证明服务存活，不能证明模型已加载或推理可用。应在交付边界验证：/v1/models 报告正在提供服务的模型，且代表性请求能够返回生成的 token。
4. 每次变更前后都要进行基准测试。 vLLM 的参数、默认值和行为会随版本变化；未经测量的调优只是猜测。只比较条件匹配的结果（版本、模型、GPU、上下文、批次、工作负载），并将证据记录在基准测试运行记录中。
5. 证据应有所限制。 对日志、配置和指标进行摘要；切勿在聊天中完整输出服务日志、.env 文件或 HF token。使用调试日志启用 --enable-log-requests 可能泄露提示词内容；在共享会话中应关闭请求日志，或对其进行脱敏。

vllm-health 脚本

scripts/vllm-health 是一个面向 Agent、用于探测正在运行的 vLLM 服务的只读工具。它只发送 GET 请求，不执行任何变更，并输出有界 JSON。

scripts/vllm-health --help                    # no server needed
scripts/vllm-health --url http://127.0.0.1:8000 --json
scripts/vllm-health --check health --check models --json
scripts/vllm-health --check metrics --timeout 10 --json

退出代码：0 表示所有检查均通过，1 表示发现问题或发生致命错误，2 表示用法错误，124 表示超时。检查项：health（/health）、version（/version）、models（/v1/models）、load（/load）和 metrics（/metrics 的有界前缀）。脚本不会向任何地方发送数据，也不会写入文件。

运维流程

1. 识别部署：确认 vLLM 版本或镜像摘要、模型及其修订版本、服务模型名称、并行配置，以及部署方式（裸机 vllm serve、Docker、Kubernetes）。
2. 收集证据：运行 vllm-health --json 检查健康状况、版本、模型和负载；查看 /metrics 计数器（vllm:num_requests_running、vllm:num_requests_waiting、vllm:gpu_cache_usage_perc）；使用 nvidia-smi 检查 GPU 状态。
3. 根据症状进行排查：将问题与证据对应起来（OOM → KV 缓存或 gpu_memory_utilization；延迟高 → 批处理、TTFT 与 TPOT；找不到模型 → 服务模型名称或聊天模板；启动慢 → 模型下载或编译缓存）。
4. 经确认后采取行动：收到人类指示后，执行范围明确、影响受限的变更，并先明确回滚路径。
5. 验证：重新运行探测，并在交付边界发送代表性请求；若变更会影响性能，则重新进行基准测试。

部署：Docker 和 Kubernetes

• Docker：官方镜像为 vllm/vllm-openai（Docker Hub）。运行时需启用 GPU 访问、挂载 Hugging Face 缓存、为受限模型提供 HF 令牌、发布端口 8000，并使用 --ipc=host（或 --shm-size），为张量并行所依赖的共享内存提供支持。请参阅 references/01-deployment.md。
• Kubernetes：使用包含 nvidia.com/gpu（或 amd.com/gpu）资源的 Deployment、用于模型缓存的 PVC、以 Memory 为后端并挂载到 /dev/shm 的 emptyDir、针对 8000 端口 /health 的存活和就绪探针，以及 Service。对于需要数分钟才能加载的大模型，请提高探针的 failureThreshold；过早终止会在容器日志中显示为 KeyboardInterrupt: terminated。
• 将镜像标签固定到某个发行版（例如 vllm/vllm-openai:v0.26.0），而不是使用 latest；并在重启期间持久化编译缓存（默认为 ~/.cache/vllm），以便重复使用 torch.compile 产物。

模型配置

• 模型标识：--model 是 HF 仓库或本地路径；--revision 用于固定确切的权重。--served-model-name 设置客户端在 /v1 请求中以及响应的 model 字段中必须使用的名称。某些模型仓库需要 --trust-remote-code，使用前应先审查相关代码。
• 上下文长度：--max-model-len 限制每个请求的提示词加输出长度。未设置时，该值根据模型配置确定；-1/auto 会选择 GPU 内存可容纳的最大长度。这是影响 KV 缓存大小的首要因素。
• 量化感知服务：仅当模型权重需要时才传入 --quantization（或 -q）（GPTQ/AWQ/GGUF 检查点会从配置中读取其方案）。权重类型和激活值数据类型必须与内核支持的类型匹配；以错误的数据类型提供量化模型会导致加载失败或性能悄然下降。硬件支持因方法而异（请参阅 references/02-model-configuration.md）。
• 张量并行：--tensor-parallel-size N 会将单个模型分片到同一节点上的 N 个 GPU；--pipeline-parallel-size 会将各层拆分到不同节点。TP 需要 NVLink/高速互连，并要求每个 GPU 的内存相同；启动日志会记录内存分析结果，这是模型能够装入显存的依据。
• KV 缓存：--gpu-memory-utilization（默认值为 0.92）限制模型和 KV 缓存可使用的 GPU 内存比例。在支持的 GPU 上，--kv-cache-dtype fp8 可缩小长上下文的缓存。引擎会记录 GPU KV cache size: N tokens 和相应的最大并发数——请记录这两个值；它们能说明该机器可同时处理多少个指定长度的请求。

兼容 OpenAI 的 API 接口

• 基本端点：/health（存活状态）、/version、/v1/models（所提供的模型）、/load（负载指标）、/metrics（Prometheus）。推理端点：/v1/completions 和 /v1/chat/completions（聊天功能要求模型自带聊天模板，或传入 --chat-template）；/v1/embeddings 用于池化模型；/v1/responses 用于 Responses API。
• 流式传输、工具调用（--enable-auto-tool-choice --tool-call-parser openai）、结构化输出和并行采样都是会改变请求/响应行为的服务端选项——请根据已安装的发行版逐一验证，不要假定它们完全兼容。
• 若要将服务暴露给环回接口之外的网络，必须明确决定绑定地址、API 密钥、TLS 或受信任的反向代理，以及防火墙规则。不得在生产环境中暴露仅用于开发的端点（/reset_prefix_cache、权重传输、性能分析）。

基准测试：吞吐量与延迟

• 在线服务基准测试：使用具有代表性的数据集（ShareGPT、本地 custom JSONL 或你自己的提示词），通过 vllm bench serve 对运行中的服务进行测试，并固定 --num-prompts、--request-rate 和 --max-concurrency。该命令会报告请求吞吐量（req/s）、输出令牌吞吐量（tok/s）、总令牌吞吐量，以及 TTFT/TPOT/ITL 百分位数。
• 离线吞吐量：vllm bench throughput 会测量不经过 HTTP 路径的原始引擎吞吐量；适用于仅比较引擎，不适用于衡量端到端用户延迟。
• 可比的测试依据：基准测试运行记录模板会固定版本、模型、量化、并行度、上下文、批处理、GPU、数据集和负载模式。绝不要把不同条件下的数字当作只有一个变量不同来比较。TTFT 是延迟指标；令牌吞吐量是吞吐量指标——有利于其中一项的优化可能会损害另一项。
• 对于生产环境的容量测试，vLLM 文档推荐使用独立的 GuideLLM 框架；本技能仅涵盖内置的 vllm bench 工具。

连续批处理调优

• vLLM 默认采用连续批处理：调度器会在容量释放时接收序列，并混合执行预填充和解码。--max-num-seqs 会限制每次迭代处理的序列数，--max-num-batched-tokens 会限制每次迭代处理的令牌数，而 --enable-chunked-prefill 允许预填充与解码在同一次迭代中执行。
• 从默认值开始，每次只调整一个参数，并使用固定的基准测试进行对比：提高 --max-num-seqs 会提升吞吐量，但会增加每个请求的延迟和 KV 缓存压力；降低该值则能提升延迟稳定性，但会降低利用率。
• --enable-prefix-caching 可在共享前缀的请求之间复用 KV 块（例如聊天系统提示词、RAG 上下文）；命中率可在 /metrics 和基准测试的输入令牌统计中查看。--performance-mode 会在内核层面权衡 interactivity（延迟）和 throughput。

GPU 运维

• 使用 nvidia-smi（AMD GPU 使用 rocm-smi）检查 GPU：在更改前后查看设备列表、内存、利用率、温度和 ECC 错误。CUDA_VISIBLE_DEVICES 用于选择 vllm serve 进程可见的 GPU；张量并行的 rank 会按顺序映射到可见设备。
• 监控 /metrics 中的 vllm:gpu_cache_usage_perc（KV 缓存压力）、vllm:num_requests_running/waiting 和 vllm:generation_tokens_total。如果缓存使用率接近 1.0 且有请求等待，说明部署已达到容量上限——应扩容或降低 max-model-len/并发数，而不是超额分配。
• 启动时发生 OOM 通常意味着模型和 KV 缓存无法装入显存：如果仅权重就超出显存，降低 --gpu-memory-utilization 并无帮助——应降低 --max-model-len、切换量化方式或增加 GPU。运行中发生 OOM 则表示 KV 缓存压力过大：应缩小上下文、降低并发数或收紧批处理限制。

升级与回滚

• 固定所有版本：镜像标签或 pip install vllm==<version>、模型修订版本，以及完整的服务命令。使用 latest 镜像和未固定的修订版本会使回滚变得不可能，也无法复现升级。
• 升级路径：阅读整个版本跨度内的发行说明，检查已更改或移除的标志（--engine-args 经常变更），在临时实例上使用真实模型和工作负载验证新版本，重新运行固定的基准测试，然后在准备好回滚方案后切换：确保旧镜像标签和旧服务配置随时可重新应用。
• 回滚：由于配置已纳入版本管理，回滚只需重新部署之前固定版本的镜像和配置。不同发行版之间 KV 缓存布局、默认值和标志名称可能变化——未经重新验证和重新测试，不要假设在 v0.25.x 上运行的配置在 v0.26.x 上表现完全相同。

参考资料路由

加载时机	参考资料
来源、版本观察、刷新流程	references/00-source-index.md
Docker 和 Kubernetes 部署、镜像固定、探针、存储	references/01-deployment.md
模型配置：量化、张量并行、KV 缓存、内存预算	references/02-model-configuration.md
OpenAI 兼容的 API 接口、聊天模板、工具、身份验证	references/03-openai-api.md
基准测试方法和 vllm bench 命令	references/04-benchmarking.md
连续批处理、分块预填充、前缀缓存、性能模式	references/05-batching-and-tuning.md
GPU 运维、可观测性、升级/回滚、故障排查	references/06-gpu-ops-and-lifecycle.md

所含工件

• scripts/vllm-health：只读的健康状态/版本/模型/负载/指标探测工具（仅使用标准库，支持 --json、--check 子集，以及无需连接服务即可使用的 --help）。
• tests/test_vllm_health.py：针对本地模拟 HTTP 服务的确定性测试，包括只读约束。
• templates/serving-config.md 和 templates/benchmark-run-record.md：可填写的记录模板，可确保部署可复现、基准测试证据可比较。
• references/：七份按日期编制、设有来源索引的参考资料，涵盖上述运维主题。
• evals/evals.json：用于 Agent 运行的六个输出质量评估用例。

验证边界

声明	最低证据要求
服务处于运行状态	vllm-health --check health 报告 /health 返回 200
提供的是正确模型	/v1/models 列出预期的服务模型名称
推理正常工作	有代表性的 /v1/chat/completions 或 /v1/completions 请求返回生成的令牌，并包含 finish_reason
模型能够装入	启动日志显示内存分析已完成，并针对所配置的并行度显示 GPU KV cache size: N tokens
调优改动有所帮助	冻结的基准测试显示指定指标有所改善，测试条件匹配且报告了方差
部署可升级	已记录之前固定的镜像和服务配置，并在临时实例上演练了升级
诊断结论可靠	在作出结论前已收集证据，且已通过重新运行探测和基准测试验证修复

硬性边界

• 未经人工明确指示（需指明目标并说明回滚路径），绝不重启、重新部署、扩缩或升级 vLLM 部署。可自由进行只读探查。
• 绝不意外将未经身份验证的服务暴露到 loopback 以外；仅用于开发的端点和性能分析路由必须保持在生产入口之外。
• 绝不打印或提交 HF 令牌、.env 内容或完整服务日志；应改为总结证据。
• 绝不将不同版本、模型、量化方式、并行度、上下文、批次或工作负载的基准测试数据当作只有一个变量发生变化来比较。
• 绝不将 vllm-health 用作只读探测以外的工具。它不具备任何修改能力。

不适用场景

• 模型训练、微调、评估集设计、量化决策和服务方法 — 这些属于 ml-engineering。
• llama.cpp 技术栈（llama-cli、llama-server、GGUF 转换与量化、本地 Metal/CUDA 构建）— 这些属于 llama-cpp。
• 其他推理引擎（TGI、Ollama、Triton；vLLM 仅用于嵌入/重排序的工作负载属于适用范围，但不包括在这些引擎中进行选择）— 引擎选择的权衡属于 ml-engineering。
• Kubernetes 和 Docker 基础知识（清单、RBAC、镜像仓库、GPU 设备插件）— 这些属于 kubernetes 和 docker-compose。
• GPU 基础设施配置（驱动程序、集群调度、容量规划）— 这些属于 platform-engineering；此技能负责运维 vLLM 服务已指定使用的 GPU。