面向 OpenAI-compatible 大模型服务的质量、性能与资源联合评测项目，并提供可选的部署网关与 单 GPU 可观测性参考栈。
InferScope 把请求级时延、SLO Goodput、实验有效性、环境指纹和可复核产物放进同一条流水线，用于展示 LLM inference benchmark 方法，而不是替代推理引擎。
快速开始 · 架构 · 部署方案 · Qwen3-1.7B 容量报告 · 方法论 · 配置 · RTX 4060 实验 · 文档导航 · 接口契约 · 面试问答
- 输入：OpenAI Chat Completions 兼容服务、YAML 实验配置和 SLO 阈值。
- 执行：按并发、固定速率或 Poisson 到达模型发送流式请求，同时采集客户端、 vLLM Prometheus 和可选 NVML 遥测。
- 输出：请求明细、聚合指标、有效性判定、环境清单、Markdown 报告和 SVG 图表。
- 与普通压测的区别：无效实验不会被包装成性能结论；吞吐之外还计算 TTFT、TPOT、 E2E、成功率和满足时延 SLO 的 Goodput。
状态口径在整个项目中一致：
| 状态 | 含义 |
|---|---|
| CPU Verified | 已在当前 CPU 开发环境真实运行，并有测试或本地产物证据 |
| GPU Verified | 已在声明的 GPU/模型/软件环境运行，并保留原始证据包 |
| Implemented | 代码与测试已存在，但尚未在目标 GPU 环境验证 |
| GPU Pending | GPU 入口已准备，但尚未收到目标硬件原始报告 |
| Planned | 尚未实现，不应当作已有能力描述 |
当前事实：RTX 4060 / Qwen3-1.7B BF16 的 direct-vLLM 与 Gateway 容量实验已完成：2 个 workload × 2 条路径 × 4 个并发档位 × 3 次重复，48/48 run 为 VALID；在预设 P95 SLO 下已验证到并发 8。
要求 Python 3.11–3.13，并推荐使用 uv。
git clone https://github.com/zhengwenze/zwz-infer-scope.git
cd zwz-infer-scope
uv sync --locked --all-groups终端 A 启动只用于链路验证的本地 fake server：
./scripts/serve_fake.sh终端 B 运行 smoke benchmark：
./scripts/run_smoke.sh查看某次运行的校验与聚合结果：
uv run inferscope benchmark show \
--run-id <run-id> \
--results-dir resultsfake server 只能证明请求、计时、聚合、校验和报告链路可运行，不能代表 GPU 或真实模型性能。 RTX 4060 的环境准备与运行方法见 RTX 4060 实验指南。
| 能力或结论 | 状态 | 当前证据 |
|---|---|---|
| CPU fake-server 端到端 smoke | CPU Verified | 120 项 unit/contract/integration 测试与 smoke 链 |
| SSE 增量解析、请求计时、指标聚合 | CPU Verified | unit / contract / integration tests |
| 配置校验、有效性门禁、产物落盘 | CPU Verified | unit / integration tests |
vLLM /metrics 解析与 NVML 采集 |
Implemented | 代码与模拟输入测试 |
| RTX 4060 + Qwen2.5-0.5B-Instruct 性能实验 | GPU Verified | 20-run 脱敏证据包：原始请求、客户端/vLLM/NVML 遥测、环境指纹、VALID 门禁与聚合结果 |
| RTX 4060 + Qwen3-1.7B direct/Gateway 容量实验 | GPU Verified | 容量报告与精简聚合证据 |
| Hugging Face backend、公平 A/B 对比 | Planned | 当前 runner 只执行 OpenAI Chat Completions |
| 自动参数搜索与回归门禁 | Planned | 尚无 CLI 工作流 |
| GSM8K、确定性数值评分器与逐样本证据 | GPU Verified | RTX 4060 全量 1,319 条：accuracy_all=41.47%，五条硬门禁 PASS |
| Pairwise Judge 与换位复评 | Planned | 无可靠 Judge 证据，不发布开放题主结论 |
CPU smoke 会遍历并发 1 / 2 / 4，每个实验生成请求/遥测 JSONL、validation.json、
aggregate.json 和 Markdown 报告。它的价值是验证证据链，不是提供可比较的性能数字。
真实 RTX 4060 性能结果（固定 ignore_eos=true、1024 input token、64 output token 的纯 Decode 合成负载）：
| GPU | 模型 | 配置 | TTFT / TPOT / Goodput | 结论 |
|---|---|---|---|---|
| RTX 4060 8 GB | Qwen2.5-0.5B-Instruct | 并发 1/2/4/8，各 5 次 | TTFT P50 36.4→58.7 ms；TPOT P50 13.4–14.2 ms；输出吞吐 70.7→509.7 tok/s | 20/20 VALID；仅限本配置 |
环境清单、原始请求明细、校验状态、聚合摘要和遥测见公开性能证据包；发布规则见结果证据说明。
固定 Qwen2.5-0.5B-Instruct revision、GSM8K test 1,319 条、BF16 和版本化 prompt/scorer 后，
RTX 4060 正式运行得到 41.47% accuracy_all（547/1,319）。请求成功率 100%，scoring
coverage 98.64%；4 条截断和 14 条不可抽取响应均按 0 分保留在主分母。
公开证据与协议限制见 GSM8K GPU 结果。官方 49.6 使用不同协议，只作外部背景，不宣称直接复现。
- 流式请求测量：解析跨 chunk SSE，分别记录连接开始、首个有效 token 和结束时间。
- 三种负载模型：闭环并发、固定请求速率、带 seed 的 Poisson 到达。
- SLO-aware 指标：TTFT、TPOT、E2E、请求吞吐、token 吞吐、成功率和 Goodput。
- 实验有效性门禁：检查预热、成功率、计时完整性、输出长度、token 可用性、 客户端 event-loop lag 和 GPU 隔离状态。
- 多源遥测：客户端单调时钟、vLLM Prometheus 指标和可选 NVML GPU 采样。
- 证据优先产物：原始样本、运行清单、聚合结果、验证报告、Markdown 摘要和 SVG 图。
本项目的工作量不在“复制一个 vLLM benchmark 脚本”，而在把测试方法变成可审计的工程闭环。
| 自研部分 | 复用部分 |
|---|---|
| 到达计划、SSE 状态机与请求级计时 | vLLM 等提供 OpenAI 兼容推理服务 |
| 指标定义、聚合、SLO Goodput | httpx 提供异步 HTTP 传输 |
| 有效性判定与错误状态 | Pydantic / PyYAML 提供配置解析与校验 |
| 环境指纹、遥测适配与证据产物 | Prometheus 文本格式与 NVML 作为观测接口 |
| 报告、图表和可复现实验脚本 | Typer / Rich 提供 CLI 交互 |
InferScope 不修改模型权重、CUDA kernel、vLLM scheduler 或 KV cache 实现；它负责在这些系统之上 构建“怎么压、怎么量、结果是否可信、证据如何复核”的实验基础设施。
flowchart LR
C["YAML config"] --> R["ExperimentRunner"]
W["Workload planner"] --> R
R --> T["OpenAI streaming transport"]
T --> S["Inference server"]
R --> O["Client / vLLM / NVML telemetry"]
T --> M["Request metrics"]
O --> V["Validation gates"]
M --> V
V --> A["Raw + processed artifacts"]
A --> P["Markdown report + SVG"]
一次 benchmark run 会为配置中的每个负载点建立到达计划，执行 warmup，再测量正式请求；
随后聚合指标、计算 Goodput、执行有效性门禁并写出证据。完整组件关系和失败路径见
架构文档。
| 指标 | 本项目口径 |
|---|---|
| TTFT | 发起请求到首个非空内容 token 的单调时钟差 |
| TPOT | 首 token 后的生成时间除以后续输出 token 数 |
| E2E | 发起请求到流结束 |
| Request throughput | 成功请求数 / 测量窗口秒数 |
| Token throughput | 成功请求输出 token 总数 / 测量窗口秒数 |
| Goodput | 同时满足 TTFT、TPOT 和运行级成功率 SLO 的请求速率 |
TPOT 需要至少两个输出 token；小样本 P99 只能用于链路检查。公式、百分位实现、测量窗口和 有效性规则以 Benchmark 方法论 为准。
默认机器产物与报告目录：
results/
├── raw/<run-id>/
│ ├── manifest.json
│ ├── config.resolved.yaml
│ ├── requests.jsonl
│ ├── client_metrics.jsonl
│ ├── server_metrics.jsonl
│ ├── gpu_metrics.jsonl
│ └── validation.json
├── processed/<run-id>/
│ ├── aggregate.json
│ └── summary.csv
├── charts/<experiment>.svg
├── experiments/<date>/ # 已完成实验快照
└── validation/<date>/ # 环境与 GPU 验证证据
reports/generated/
└── <run-id>.md
artifacts/published/<experiment-id>/ # 审核、脱敏后提交的冻结机器证据
reports/<report>.md # 人工审核后的公开结论
manifest.json 保存无密钥环境指纹和配置哈希，config.resolved.yaml 保存解析后配置，
requests.jsonl 保存请求级测量，
validation.json 决定结果是 VALID、INVALID 还是 INCONCLUSIVE。生成目录默认不提交，
避免把本机临时结果伪装成公开基准数据。
详细目录与发布约定见项目资产清单。
src/
├── inferscope/ # Benchmark、质量、分析和报告核心包
└── inferscope_gateway/ # 可选鉴权、准入、流式代理和服务指标包
deploy/ # vLLM + Gateway + Prometheus + Grafana 参考部署
artifacts/published/ # 经过审核的冻结机器证据
results/ # 默认忽略的本地运行产物
reports/ # 公开报告；generated/ 默认忽略
两个 Python 包共享 distribution 版本，但没有业务 import 依赖；详细规则见包边界。
本地非 GPU 门禁：
uv run pytest -m "not gpu" -q
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv build
bash -n scripts/*.sh测试分为 unit、contract 和 integration；GPU 测试单独标记，不能由 CPU mock 代替。仓库包含 GitHub Actions CPU 门禁；当前本地迁移验证为 120 tests、Ruff、MyPy strict、Shell 语法和构建 通过。远端 CI 状态需以本次推送后的 Actions 结果为准。开发约定和扩展流程见 开发指南。
仓库提供保守配置 configs/rtx4060_qwen05b.yaml 和启动脚本
scripts/serve_vllm_4060.sh。默认使用小模型、max-model-len=4096、
gpu-memory-utilization=0.80、max-num-seqs=8，用于降低首次实验的 OOM 风险。
该配置已在 RTX 4060 8 GB 上完成一次受控 20-run 实验；复现前仍应阅读 RTX 4060 指南，并保留失败实验与环境差异。公开数字只对应证据包中冻结的模型、版本与负载。
- 已发布的 RTX 4060 性能结论仅覆盖 Qwen2.5-0.5B-Instruct、
ignore_eos=true的固定长度合成负载，不代表真实对话或跨模型排名。 - runner 当前只执行 Chat Completions；配置中的 HF backend 与 completions 尚未接线。
mixedworkload、prompt/response 保存开关和多输出格式尚未形成完整执行路径。- token 数依赖服务端 usage；本地 tokenizer 与 token mismatch 门禁尚未接入。
- Pareto 与稳定性算法已有实现，但还没有完整 CLI 报告入口。
- GPU “干净环境”无法自动充分证明；缺少证据时结果会是
INCONCLUSIVE。 - 当前没有正式 release 和已验证的 GPU 容器镜像发布流程。
- 当前质量切片只实现 GSM8K numeric answer scorer；多数据集框架和 Judge 仍为 Planned。
- 在第二套 GPU/模型环境复现已发布结果，并增加自然 EOS 的真实对话负载。
- 实现固定数据集、逐样本质量结果和五类确定性评分器，并与性能结果按
candidate_id联合分析。 - 接入标准 Benchmark 交叉验证和配置化回归门禁；Judge 只作为带校准证据的可选层。
- 把 token mismatch、GPU 隔离和
/metrics缺失提升为更清晰的验证证据。 - 将 Pareto frontier 与多次重复稳定性分析接入 CLI 和报告。
- 实现独立 backend adapter 后，再进行 vLLM 与 Hugging Face 公平对照。
- 为已验证的 RTX 4060 实验发布可引用的 release。
统一入口见文档导航。其中配置字段、指标方法、架构、接口与资产规则各有唯一维护位置；
已完成的阶段计划和迁移记录已归入 docs/archive/，不再与当前状态混写。
Apache License 2.0，见 LICENSE。