vLLM AI 性能测试与报告
执行真实测试并从证据生成报告。不得猜测模型、硬件、操作系统、测试位置、服务状态、监控数据或结论。
工作模式
先判断测试位置，再执行命令。
用户是第一次做测试或不熟悉命令行时，先完整阅读 references/beginner-guide.md。先收集客户提供的模型服务、测试位置、输入样本、负载上限和授权；信息不全时先提问，不得猜测或直接压测。
- 本地模式：模型服务和压测器位于同一台宿主机。可以用
--local-launch-command启动指定的 vLLM 或 Docker 命令；脚本只终止它自己启动的进程。必须先确认模型路径、加速卡可见性、端口、显存和容器运行时。 - 服务器模式：模型服务在另一台机器。必须取得用户对目标地址、压测窗口和负载上限的明确授权，并传入
--allow-remote。禁止尝试 SSH、启动/停止远端服务、修改远端配置或绕过认证。先检查/v1/models，连接失败时停止并报告原因。
需要在服务器自身执行 GuideLLM 时，使用 scripts/run_remote_guidellm_over_ssh.py。它要求客户提供 SSH 身份密钥、预先确认的 known_hosts、远端输出目录和批准的最大并发；必须同时传入 --authorize-remote-test --execute 才会实际发压。默认仅打印命令的 dry-run 不建立实际测试负载。
一次测试会产生 test_manifest.json、GuideLLM 的 benchmarks.json/csv 和可选图表。报告从这些文件读取事实，并将负责人固定为 AI Agent (automated)。测试结束后，HTTP 连接随请求关闭；Docker 模式使用 --rm 清理压测容器；脚本默认停止它启动的本地服务。远端服务不被脚本修改。
执行流程
- 阅读
references/input-contract.md，确认模型、目标地址、上下文长度、输出长度、并发点和C_max的来源。 - 本地模式执行设备与服务预检；远程模式先取得授权并确认网络、端口、服务模型名和 tokenizer 挂载路径。
- 用
scripts/run_guidellm_benchmark.py执行单个上下文测试。把每个长度输出到<results-root>/<context>/。 - 检查每个
benchmarks.json的错误数、完成数、运行参数和test_manifest.json。固定时长结束时的incomplete表示仍在飞行的请求，不自动等同失败。 - 从 vLLM 日志抄录每个长度的理论
C_max，创建 JSON 映射。不得用业务推荐并发替代它。 - 用
scripts/generate_ai_test_report.py --strict生成汇总报告。若环境具备matplotlib，加--render-details使用本 skill 自带的渲染器生成图表。 - 阅读报告的“校验与限制”和“溯源”章节。任何错误、缺失的监控数据或未完成请求都必须保留在最终报告中。
没有可用 GuideLLM 镜像或二进制时，优先使用 scripts/native_openai_benchmark.py。它不需要 Docker、GuideLLM、Python 第三方包或联网下载，直接测试客户提供的 OpenAI 兼容模型服务。客户必须提供具有代表性的 --prompt-file；脚本以流式响应 usage.completion_tokens 计算输出吞吐，服务没有该字段时将该请求记录为错误，避免伪造 token 指标。
运行 GuideLLM
Linux Docker 示例。本地服务先由 --local-launch-command 启动；远程服务省略该参数，并改为 --mode remote --allow-remote。
python3 skills/vllm-performance-report/scripts/run_guidellm_benchmark.py \
--mode local \
--local-launch-command '<已验证的 vLLM 启动命令>' \
--health-url http://127.0.0.1:8000/health \
--target http://127.0.0.1:8000/v1 \
--model '<服务模型名>' \
--processor '<tokenizer 或模型目录>' \
--prompt-tokens 1024 --output-tokens 200 \
--rates 1,10,20,40,60 \
--output-dir '<results-root>/1024' \
--guidellm-image '<客户提供的 GuideLLM 镜像>'
脚本在 Docker 模式默认使用 --network host。Windows Docker Desktop 和非 Linux 宿主机可能不能通过 127.0.0.1 访问宿主服务；此时先验证容器到服务端的网络路径，再使用可达 IP 或 host.docker.internal。不要根据猜测修改目标地址。
生成汇总报告
python3 skills/vllm-performance-report/scripts/generate_ai_test_report.py \
--results-root '<results-root>' \
--cmax-json '<cmax.json>' \
--environment-json '<environment.json>' \
--model '<模型名称>' \
--platform '<加速卡 / vLLM 版本>' \
--output '<报告路径>.md' \
--strict --render-details
仅在 Prometheus 保存了测试对应时间窗的历史数据时传入 --prometheus。仅在业务已明确 TTFT p95 SLO 时传入 --ttft-p95-slo-ms；没有 SLO 时不得生成“推荐并发”。
数据完整性规则
- 保留所有并发点。
errored > 0或successful = 0标为无效；incomplete > 0标为时间窗结束时仍在飞行。 - 正确标注 TTFT/TPOT 的 p50（中位数）与 p95，不得把中位数称为均值。
- 明确说明
输出吞吐 / 并发是推导的容量分摊，不是逐请求实测速度。 - 分开陈述理论
C_max、测得吞吐平台和基于 SLO 的推荐并发。 - 没有 Prometheus 历史数据时，KV Cache 列应为空并说明原因。
- 不同模型、权重量化、卡数、并行策略、vLLM 版本或输入输出长度的结果不能直接做等价横向比较。
输出要求
报告必须包含：AI 负责人、测试位置（本地/服务器）、目标地址、宿主机操作系统、显式环境配置、完整扫描序列、结果表、限制、输入文件 SHA-256 与可选图表。运行清单中的数据优先于人工描述；缺失字段显示“未提供”。
