ttftkit 0.2.1__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. {ttftkit-0.2.1 → ttftkit-0.4.0}/PKG-INFO +70 -7
  2. {ttftkit-0.2.1 → ttftkit-0.4.0}/README.md +69 -6
  3. {ttftkit-0.2.1 → ttftkit-0.4.0}/pyproject.toml +1 -1
  4. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/__init__.py +1 -1
  5. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/cli.py +113 -1
  6. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/client.py +18 -6
  7. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/gate.py +360 -4
  8. ttftkit-0.4.0/src/ttftkit/lag.py +88 -0
  9. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/metrics.py +77 -0
  10. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/models.py +3 -0
  11. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/report.py +65 -3
  12. ttftkit-0.4.0/src/ttftkit/runner.py +158 -0
  13. ttftkit-0.4.0/src/ttftkit/scan.py +205 -0
  14. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/PKG-INFO +70 -7
  15. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/SOURCES.txt +18 -0
  16. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_client.py +33 -0
  17. ttftkit-0.4.0/tests/test_client_lag_gate.py +77 -0
  18. ttftkit-0.4.0/tests/test_gate_invariance.py +103 -0
  19. ttftkit-0.4.0/tests/test_gate_p99_basis.py +51 -0
  20. ttftkit-0.4.0/tests/test_gate_server_env.py +119 -0
  21. ttftkit-0.4.0/tests/test_gate_stability.py +124 -0
  22. ttftkit-0.4.0/tests/test_gate_stability_power.py +87 -0
  23. ttftkit-0.4.0/tests/test_gate_wilson.py +94 -0
  24. ttftkit-0.4.0/tests/test_lag.py +105 -0
  25. ttftkit-0.4.0/tests/test_metrics_ci.py +64 -0
  26. ttftkit-0.4.0/tests/test_metrics_p99_basis.py +32 -0
  27. ttftkit-0.4.0/tests/test_queries40_prompts.py +44 -0
  28. ttftkit-0.4.0/tests/test_queries40_report.py +137 -0
  29. ttftkit-0.4.0/tests/test_runner_capture.py +32 -0
  30. ttftkit-0.4.0/tests/test_runner_multiprompt.py +97 -0
  31. ttftkit-0.4.0/tests/test_runner_sampling.py +108 -0
  32. ttftkit-0.4.0/tests/test_scan.py +129 -0
  33. ttftkit-0.2.1/src/ttftkit/runner.py +0 -88
  34. {ttftkit-0.2.1 → ttftkit-0.4.0}/LICENSE +0 -0
  35. {ttftkit-0.2.1 → ttftkit-0.4.0}/setup.cfg +0 -0
  36. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/__main__.py +0 -0
  37. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit/hardware.py +0 -0
  38. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/dependency_links.txt +0 -0
  39. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/entry_points.txt +0 -0
  40. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/requires.txt +0 -0
  41. {ttftkit-0.2.1 → ttftkit-0.4.0}/src/ttftkit.egg-info/top_level.txt +0 -0
  42. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_baseline_policy.py +0 -0
  43. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_cli.py +0 -0
  44. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_cli_hardware.py +0 -0
  45. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_client_hardening.py +0 -0
  46. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_gate.py +0 -0
  47. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_gate_failclosed.py +0 -0
  48. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_gate_hardware.py +0 -0
  49. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_hardware.py +0 -0
  50. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_invalid.py +0 -0
  51. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_models.py +0 -0
  52. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_package.py +0 -0
  53. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_report.py +0 -0
  54. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_runner_hardware.py +0 -0
  55. {ttftkit-0.2.1 → ttftkit-0.4.0}/tests/test_shadow_gate.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ttftkit
3
- Version: 0.2.1
3
+ Version: 0.4.0
4
4
  Summary: LLM serving benchmark harness and release gate: TTFT / TPOT / throughput / stability, CI-ready
5
5
  Author: aidless
6
6
  License-Expression: Apache-2.0
@@ -31,13 +31,16 @@ Dynamic: license-file
31
31
  v0.2 加了两块:**GPU 显存/利用率采样**(`--gpu auto|none|command`,验收标准是「注入已知泄漏必须看得见单调上涨」)与**影子门禁**(先在 CI 里只留读数、不拦人,观察误报后再收紧)。想按 JD 一条条练,见 [`docs/labs.md`](docs/labs.md)。
32
32
 
33
33
  ```bash
34
- pip install -e .
34
+ pip install ttftkit # PyPI 0.4.0(含 scan / gate / report)
35
+ pip install -e . # 或:git clone 后装源码版
35
36
  ttftkit run --endpoint http://127.0.0.1:8000/v1/chat/completions \
36
37
  --model Qwen/Qwen2.5-7B-Instruct --requests 32 --concurrency 8 \
37
38
  --max-tokens 128 --profile rtx4090-vllm-0.6.3 --output results/run.json
38
39
  ttftkit gate results/run.json --policy configs/policy.json --baseline baselines/main.json
39
40
  ```
40
41
 
42
+ > **结论索引:见 [docs/FINDINGS.md](docs/FINDINGS.md)** —— 每条实测结论(F1–F7)+ 数字 + 证据文件 + 复现命令,含三条「不要这样引用」的坑(flag=0 的分叉不是缺陷、8 条 query 的 3/8 不是总体率、n<20 的 p99 不是分位数)。
43
+
41
44
  ## 为什么不用现成的
42
45
 
43
46
  | 工具 | 强项 | ttftkit 的定位 |
@@ -58,22 +61,56 @@ ttftkit 刻意做小:**只测一个端点、只做闭环并发、只输出可
58
61
  | 错误率 | 失败请求 / 全部请求 | 失败请求不参与延迟统计,但**一定要进分母** |
59
62
  | 稳定性 | `latency_ms.cv`、`degradation_ratio`(后 1/4 ÷ 前 1/4 延迟) | 后者专抓跑久了变慢(显存泄漏、KV 碎片、降频) |
60
63
  | 显存增长 | `mem_used_peak_mb − mem_used_baseline_mb` | 没采到样时是 `null`,**不是 0**;`0 MB` 会被读成「测到了、没占显存」 |
64
+ | 客户端 lag | 测量窗口内事件循环的唤醒延迟 p50/p95/max | 单进程 asyncio 客户端的**自身排队**会混进 TTFT/TPOT;它是「测量上界」的证据,不是服务端性能 |
65
+ | 分位数置信区间 | p50/p95 的 percentile bootstrap 95% 区间(种子固定 0) | 样本 < 20 条时给 `null`;8 条记录的 p95 其实就是最大值,套区间是假精确 |
61
66
 
62
67
  一个 SSE 块可能含多个 token,所以块间隔只作为传输层观测记录(`chunk_gap_ms`),**不叫 ITL**。详细推导与对齐说明见 [`docs/metrics.md`](docs/metrics.md)。
63
68
 
64
69
  ## 门禁
65
70
 
66
- 策略文件支持两种规则,可同时使用:
71
+ 策略文件支持三种规则,可同时使用:
67
72
 
68
73
  ```json
69
74
  {
70
75
  "limits": { "ttft_ms.p95": 800, "tpot_ms.p95": 60, "error_rate": 0.0 },
71
- "regressions": { "ttft_ms.p95": 10, "output_tokens_per_s": 5 }
76
+ "regressions": { "ttft_ms.p95": 10, "output_tokens_per_s": 5 },
77
+ "invariance": { "against_baseline": true }
72
78
  }
73
79
  ```
74
80
 
75
81
  - `limits`:绝对上限/下限,越界即 FAIL。
76
82
  - `regressions`:相对基线允许的退化百分比(延迟类越小越好、吞吐类越大越好,方向内置)。
83
+ - `invariance`(batch 不变性,v0.4):要求 `--baseline`,candidate 与 baseline 两份报告的捕获输出**逐字节一致**。基准跑 `concurrency=1`,候选跑目标 batch;跑基准/候选时都要 `capture_outputs=True`(报告里才有 `outputs`)。可比性只要求 `protocol / model / max_tokens / prompt_sha256` 一致——`concurrency / requests` 是 batch 形态本身,允许不同。任何一侧缺 `outputs` 都是「没测」(`2`),不是通过。
84
+
85
+ > **实弹判决(2026-11-10)**:RTX 3060 6GB / vLLM 0.33.0 / Qwen3-4B-AWQ,c=1 与 c=16 的 8/8 输出逐字节一致(贪心解码口径),闸 PASS。判决书与原始报告见 [results/invariance-2026-11-10/](results/invariance-2026-11-10/verdict.md),复现脚本 [scripts/invariance_run.py](scripts/invariance_run.py)。
86
+
87
+ > **采样解码支持(v0.3.0 后)**:`run` 新增 `--temperature/--top-p/--seed`(默认 temperature=0 贪心,与历史行为一致)。采样参数进报告 `config`,gate 的可比性检查会把「不同采样参数」的报告判为不可比——不同解码路径的报告放一起比延迟是假比较。
88
+
89
+ > **stability 规则(采样解码分布稳定性)**:`{"stability": {"against_baseline": true, "max_divergence_rate": 0.2}}`。采样解码(temperature>0)下连续批处理的浮点噪声会被采样放大,逐字节一致(invariance)是错误预期;stability 改判**分歧率**——candidate 与 baseline 输出不一致的占比 ≤ 上限(0.0 退化为硬一致)。可比性键比 invariance 多三个采样参数(temperature/top_p/seed)。实测依据:贪心 8/8 逐字节一致 vs 采样 0.7+seed 7/8 一致(index=2 第 46 token 分叉),见 [results/invariance-2026-11-10/verdict-sampled.md](results/invariance-2026-11-10/verdict-sampled.md)。
90
+ >
91
+ > **stability 口径 caveat(单 prompt 复制)**:单 prompt × 单 seed 的 N 个请求是同一 query 的 N 份拷贝(实测 8 条输出全同),此时 divergence_rate 的分母是 batch 槽位数、不是独立 query——量的是「槽位对同一 fork 点的翻与不翻」。要测 query 级分歧率,用 `run_benchmark(prompts=[...])`(每请求独立 prompt,seed+i 独立种子),config 的 `prompt_sha256` 变为逐请求哈希串联,可比性检查照常生效。查询级三次独立跑(带 tag 留档,同一组 8 条 prompt)稳定读数:c=4 分歧 3/8=0.375、c=16 分歧 4/8=0.500,且 c=1 baseline 跨跑 8/8 逐字节可复现;翻转集中在固定 query(c=4 的 0/2/3、c=16 的 0/2/3/4 每跑必翻),说明是 query 自身的近并列 fork 点被 batch 放大,不是随机噪声。两种口径(槽位拷贝 vs 独立 query)量纲不同,不可相减。见 [verdict-queries-multirun.md](results/invariance-2026-11-10/verdict-queries-multirun.md)。
92
+ >
93
+ > **服务端配置声明 `server_env`(2026-11-17)**:`VLLM_BATCH_INVARIANT`(vLLM 文档
94
+ > [docs/features/batch_invariance.md](https://github.com/vllm-project/vllm/blob/main/docs/features/batch_invariance.md))
95
+ > 直接改写「batch 改变输出」的语义——**flag=0(默认)时那是设计行为,flag=1 时才承诺
96
+ > 输出与 batch 大小/顺序无关**。因此服务端配置必须进可比性键:`run --server-env VLLM_BATCH_INVARIANT=1`
97
+ > 写进报告 `config.server_env`,invariance / stability 两侧声明不同即判**不可比(退出码 2)**。
98
+ > 不声明保持缺键(=未声明),与同为未声明的一侧可比;`server_env: {}` 与缺键等价。
99
+ > 少了这一项,闸会把「配置不同」误判成「实现违反不变性」——方向最坏的误判(编排/实验噪声被读成缺陷)。
100
+
101
+ > **40 条独立 query × 两个 flag 值实测(2026-11-17)**:`VLLM_BATCH_INVARIANT=0`(默认)下
102
+ > c=4 与 c=16 各 2/40 = 0.050(Wilson [0.014, 0.165]);`=1` 下两组都是 **0/40**(上界 **0.088** < 0.2)——
103
+ > 决定性 PASS,即 vLLM 文档承诺的 batch 不变性在**消费级 Ampere(sm_86,不在 tuned matmul 表里)+ AWQ +
104
+ > `--enforce-eager`** 这个上游没测过的组合上仍然成立。代价实测:TPOT 约 2.7×(61→175 ms)、
105
+ > 吞吐 −58~−63%、TTFT 基本不变、整轮墙钟 2.6×。**同时登记一次预注册未命中**:跑前按 8 条 query 的
106
+ > 3/8 外推期望 15/40 `FAIL_DECISIVE`,实测 2/40 方向相反——8 样本点估计不可外推,判据没改、读数照写。
107
+ > 见 [verdict-queries40-pair.md](results/invariance-2026-11-10/verdict-queries40-pair.md)。
108
+
109
+ > **stability 功效见证**:n=8 时即便 0/8 分歧,Wilson 95% 上界仍有 0.324 > 上限 0.2,PASS 不是「rate ≤ 上限」的证据。gate 在 PASS 且上界超过上限时自动附一条 kind=power 见证检查(不改判决),并给出零分歧下把上界压到限内所需的样本数(0.2 档为 n≥16 条**不同** query)。反向亦然:3/8 的 Wilson 下界 0.137 ≤ 0.2,FAIL 也不必然是总体超限;见证只挂 PASS 是 fail-closed 取舍(PASS 放行部署才是危险方向)。重复跑同一组 8 条 query 不能把分母乘 3。要机械判定某个分歧率上限,先铺够独立 prompt。
110
+ >
111
+ > **p99_basis**:分布节点(count<20)带 `"p99_basis": "max"`——此时 p99 由末位 1–2 个样本主导,不是可分位估计,数值也未必等于 max(canonical runD 实测 8 样本 p99=123.7 而 max=123.9;另一次 p99/max≈583 把 c=4 判得比 c=16 还慢)。gate 对引用 `*.p99` 的上限规则自动附一条 basis 见证检查(不改判决),延迟结论请引 p50。
112
+
113
+ > **采样不变性实弹(2026-11-10)**:temperature=0.7 + seed=1234 下 c=1 vs c=16 **7/8 一致、index=2 在第 46 个 token 分叉**——采样解码下 batch 不变性不成立(浮点归约顺序随批形态变化,采样把微小 logits 差异放大成分叉)。贪心 8/8 一致 vs 采样 7/8:invariance 闸适用边界=temperature=0;采样解码要用分布稳定性判据(未实现,见 [results/invariance-2026-11-10/verdict-sampled.md](results/invariance-2026-11-10/verdict-sampled.md))。
77
114
  - 退出码:`0` 通过(可能带 WARN 贴边提示)|`1` 有规则不通过、失败数超过预算(默认 0)、或缺指标|`2` 策略/报告无效,或两次测量不可比。
78
115
 
79
116
  **fail-closed 的地方**(这些都是踩过的坑,不是设计洁癖):
@@ -88,6 +125,24 @@ ttftkit 刻意做小:**只测一个端点、只做闭环并发、只输出可
88
125
 
89
126
  策略写法与取舍见 [`docs/gate.md`](docs/gate.md)。
90
127
 
128
+ ## SLO 负载扫描(v0.3)
129
+
130
+ 「满负载下多少 tok/s」是个容易误导人的数:牺牲延迟换来的吞吐也会被算进去。`scan` 反过来问——**在延迟/错误率约束下,能撑到多少负载**(SLO-qualified goodput,见 [`docs/papers.md`](docs/papers.md) C1)。
131
+
132
+ ```bash
133
+ ttftkit scan --endpoint http://127.0.0.1:8000/v1/chat/completions --model Qwen/Qwen2.5-7B-Instruct \
134
+ --levels 1,2,4,8,16 --slo-ttft 800 --slo-tpot 60 --slo-error-rate 0.0 \
135
+ --requests 16 --max-tokens 128 --profile rtx4090-vllm-0.6.3 --output results/scan.json
136
+ ```
137
+
138
+ 输出:逐级一行(并发 / 是否满足 / req/s / tok/s / TTFT p95 / TPOT p95 / 违反了哪条),加一句「满足 SLO 的最高负载」。三条纪律:
139
+
140
+ 1. **违反的那一级留在报告里**(`stopped_at` + `violations`)——只报好看的数字等于自欺。
141
+ 2. **一级违反即停**,继续往上扫只会把超时和崩溃混进数据。
142
+ 3. **没有证据不算通过**:某一级缺 p95(`null`)记为「不满足」,不当作默认达标。
143
+
144
+ `scan` 报告**不能直接过门禁**(`kind: "scan"` → 退出码 `2`):它是多级聚合,请挑一级的 `levels[i].summary` 当单次测量再判。
145
+
91
146
  ## 显存与 GPU 采样(v0.2)
92
147
 
93
148
  ```bash
@@ -127,6 +182,10 @@ CI 里先用**影子模式**(`scripts/shadow_gate.py` 不带 `--strict` 时恒
127
182
  - name: Release gate
128
183
  run: ttftkit gate results/run.json --policy configs/policy.json --baseline baselines/main.json
129
184
  # 或者先用影子门禁:只记录读数,不阻断
185
+ # SLO 扫描(可选):只记录,不比绝对值
186
+ - name: SLO scan
187
+ run: ttftkit scan --endpoint "$ENDPOINT" --model "$MODEL" --levels 1,2,4,8 \
188
+ --slo-ttft 800 --profile "$PROFILE" --output results/scan.json
130
189
  - name: Shadow gate (non-blocking)
131
190
  continue-on-error: true
132
191
  run: python scripts/shadow_gate.py --report results/run.json --baseline baselines/main.json --policy configs/policy.baseline.json
@@ -161,8 +220,9 @@ Ryzen 5800H / 无 GPU / ollama `qwen2.5-coder:0.5b`,3 请求、并发 1、`max
161
220
  在真实本地 SSE 服务上跑通(`tests/` 含真实本地 SSE 服务用例)。
162
221
  - 门禁**fail-closed**:指标缺失/`NaN`/`inf`/字符串/布尔 → 不通过;空策略/未知指标名 → 配置错误(`2`);
163
222
  相对比较要求协议/模型/并发/token/请求数/prompt 哈希/指纹完全一致,否则不可比。
164
- - 已知退化**会被拦住**:`scripts/red_check.py` 逐条回退 32 处修复,对应用例全部变红(32/32),
223
+ - 已知退化**会被拦住**:`scripts/red_check.py` 逐条回退 64 处修复,对应用例全部变红(64/64),
165
224
  证明这些判定不是摆设。
225
+ - **SLO 扫描与客户端污染可判定**:`scan` 违反即停且保留坏级别、`null` 不当通过;`client.lag` 能测到人为阻塞(`time.sleep(0.08)` → `max_ms ≥ 30`),且门禁拒绝「summary 声称 lag 但没有 `client` 块」。
166
226
  - 硬件块**自洽且可溯源**:`delta == peak − baseline`、负数/超设备总量 → 配置错误、
167
227
  `config.hardware` 必须等于用块重算的指纹(防改块绕过可比性门禁)。
168
228
  - 基线与阈值**来自同机 5 次实测**,不是拍的:`baselines/README.md` 给出 5 次全表 + 复现命令,
@@ -176,6 +236,9 @@ Ryzen 5800H / 无 GPU / ollama `qwen2.5-coder:0.5b`,3 请求、并发 1、`max
176
236
  - 显存是**设备级 + 轮询**:同卡其他进程的变化会混进 `delta`,间隔内的单次尖峰可能被漏掉(见 [`docs/hardware.md`](docs/hardware.md))。
177
237
  - 闭环固定并发,**不模拟泊松到达或真实流量分布**;要那个用 `aiperf`。
178
238
  - TPOT 是**客户端近似**:同一 SSE 块内的 token 时间无法拆分。
239
+ - 客户端 lag 只是**上界的一半**:同一台机器上别的进程也在抢 CPU;它不是「服务端慢了多少」的分解。
240
+ - `scan` 的结论仍是**闭环**结论(「K 个并发客户端下」),不是生产到达率下的容量;要开环到达率请用 `aiperf` / `guidellm`。
241
+ - 分位数置信区间是**分位数本身的不确定性**,不是「下一次测量的预测区间」,别拿它当 SLO 余量。
179
242
  - **不做分布式多机压测**,不测第三方付费 API 的绝对性能(网络抖动会污染结果)。
180
243
 
181
244
  ## 开发
@@ -186,9 +249,9 @@ python3 -m ruff check src tests scripts
186
249
  python3 scripts/red_check.py # RED 反证:把修复回退后,对应测试必须变红
187
250
  ```
188
251
 
189
- `red_check.py` 是变异检查的自动化版本:在临时副本上逐条回退修复(TTFT 取值时机、门禁边界、吞吐分母、token 口径、坏 `choices`、总时限、错误串回显、非字符串 `content`、残缺报告、warmup 退出码、`count=0` 带分位数、显存 `null`→`0`、硬件可比性、影子门禁退出码、label 恒 PASS、利用率方向、stop 截断、单样本 delta、零样本块、指纹 `none`、证据链不一致、影子读坏输入、指纹溯源、截断读数、物理不可能值、Collector 参数),跑对应用例并断言它**失败**。当前 32/32 全部变红——修复若只是摆设,这一步会变绿并报错。
252
+ `red_check.py` 是变异检查的自动化版本:在临时副本上逐条回退修复(TTFT 取值时机、门禁边界、吞吐分母、token 口径、坏 `choices`、总时限、错误串回显、非字符串 `content`、残缺报告、warmup 退出码、`count=0` 带分位数、显存 `null`→`0`、硬件可比性、影子门禁退出码、label 恒 PASS、利用率方向、stop 截断、单样本 delta、零样本块、指纹 `none`、证据链不一致、影子读坏输入、指纹溯源、截断读数、物理不可能值、Collector 参数、lag 空样本 `null`、lag 真能测到阻塞、扫描违反即停、缺证据不算通过、scan 不可过门禁、lag 无来源、bootstrap 种子、小样本不给区间、client 块形状、server_env 可比性键、server_env 缺键回落、build_report 读真字段),跑对应用例并断言它**失败**。当前 **64/64** 全部变红——修复若只是摆设,这一步会变绿并报错。
190
253
 
191
- 按 JD 练习的路径见 [`docs/labs.md`](docs/labs.md)(8 个实验,每个都有可复跑的通过判据)。
254
+ 按 JD 练习的路径见 [`docs/labs.md`](docs/labs.md)(10 个实验,每个都有可复跑的通过判据);这些能力的文献依据与「哪些只是文档、哪些真实现了」见 [`docs/papers.md`](docs/papers.md)。
192
255
 
193
256
  ## License
194
257
 
@@ -9,13 +9,16 @@
9
9
  v0.2 加了两块:**GPU 显存/利用率采样**(`--gpu auto|none|command`,验收标准是「注入已知泄漏必须看得见单调上涨」)与**影子门禁**(先在 CI 里只留读数、不拦人,观察误报后再收紧)。想按 JD 一条条练,见 [`docs/labs.md`](docs/labs.md)。
10
10
 
11
11
  ```bash
12
- pip install -e .
12
+ pip install ttftkit # PyPI 0.4.0(含 scan / gate / report)
13
+ pip install -e . # 或:git clone 后装源码版
13
14
  ttftkit run --endpoint http://127.0.0.1:8000/v1/chat/completions \
14
15
  --model Qwen/Qwen2.5-7B-Instruct --requests 32 --concurrency 8 \
15
16
  --max-tokens 128 --profile rtx4090-vllm-0.6.3 --output results/run.json
16
17
  ttftkit gate results/run.json --policy configs/policy.json --baseline baselines/main.json
17
18
  ```
18
19
 
20
+ > **结论索引:见 [docs/FINDINGS.md](docs/FINDINGS.md)** —— 每条实测结论(F1–F7)+ 数字 + 证据文件 + 复现命令,含三条「不要这样引用」的坑(flag=0 的分叉不是缺陷、8 条 query 的 3/8 不是总体率、n<20 的 p99 不是分位数)。
21
+
19
22
  ## 为什么不用现成的
20
23
 
21
24
  | 工具 | 强项 | ttftkit 的定位 |
@@ -36,22 +39,56 @@ ttftkit 刻意做小:**只测一个端点、只做闭环并发、只输出可
36
39
  | 错误率 | 失败请求 / 全部请求 | 失败请求不参与延迟统计,但**一定要进分母** |
37
40
  | 稳定性 | `latency_ms.cv`、`degradation_ratio`(后 1/4 ÷ 前 1/4 延迟) | 后者专抓跑久了变慢(显存泄漏、KV 碎片、降频) |
38
41
  | 显存增长 | `mem_used_peak_mb − mem_used_baseline_mb` | 没采到样时是 `null`,**不是 0**;`0 MB` 会被读成「测到了、没占显存」 |
42
+ | 客户端 lag | 测量窗口内事件循环的唤醒延迟 p50/p95/max | 单进程 asyncio 客户端的**自身排队**会混进 TTFT/TPOT;它是「测量上界」的证据,不是服务端性能 |
43
+ | 分位数置信区间 | p50/p95 的 percentile bootstrap 95% 区间(种子固定 0) | 样本 < 20 条时给 `null`;8 条记录的 p95 其实就是最大值,套区间是假精确 |
39
44
 
40
45
  一个 SSE 块可能含多个 token,所以块间隔只作为传输层观测记录(`chunk_gap_ms`),**不叫 ITL**。详细推导与对齐说明见 [`docs/metrics.md`](docs/metrics.md)。
41
46
 
42
47
  ## 门禁
43
48
 
44
- 策略文件支持两种规则,可同时使用:
49
+ 策略文件支持三种规则,可同时使用:
45
50
 
46
51
  ```json
47
52
  {
48
53
  "limits": { "ttft_ms.p95": 800, "tpot_ms.p95": 60, "error_rate": 0.0 },
49
- "regressions": { "ttft_ms.p95": 10, "output_tokens_per_s": 5 }
54
+ "regressions": { "ttft_ms.p95": 10, "output_tokens_per_s": 5 },
55
+ "invariance": { "against_baseline": true }
50
56
  }
51
57
  ```
52
58
 
53
59
  - `limits`:绝对上限/下限,越界即 FAIL。
54
60
  - `regressions`:相对基线允许的退化百分比(延迟类越小越好、吞吐类越大越好,方向内置)。
61
+ - `invariance`(batch 不变性,v0.4):要求 `--baseline`,candidate 与 baseline 两份报告的捕获输出**逐字节一致**。基准跑 `concurrency=1`,候选跑目标 batch;跑基准/候选时都要 `capture_outputs=True`(报告里才有 `outputs`)。可比性只要求 `protocol / model / max_tokens / prompt_sha256` 一致——`concurrency / requests` 是 batch 形态本身,允许不同。任何一侧缺 `outputs` 都是「没测」(`2`),不是通过。
62
+
63
+ > **实弹判决(2026-11-10)**:RTX 3060 6GB / vLLM 0.33.0 / Qwen3-4B-AWQ,c=1 与 c=16 的 8/8 输出逐字节一致(贪心解码口径),闸 PASS。判决书与原始报告见 [results/invariance-2026-11-10/](results/invariance-2026-11-10/verdict.md),复现脚本 [scripts/invariance_run.py](scripts/invariance_run.py)。
64
+
65
+ > **采样解码支持(v0.3.0 后)**:`run` 新增 `--temperature/--top-p/--seed`(默认 temperature=0 贪心,与历史行为一致)。采样参数进报告 `config`,gate 的可比性检查会把「不同采样参数」的报告判为不可比——不同解码路径的报告放一起比延迟是假比较。
66
+
67
+ > **stability 规则(采样解码分布稳定性)**:`{"stability": {"against_baseline": true, "max_divergence_rate": 0.2}}`。采样解码(temperature>0)下连续批处理的浮点噪声会被采样放大,逐字节一致(invariance)是错误预期;stability 改判**分歧率**——candidate 与 baseline 输出不一致的占比 ≤ 上限(0.0 退化为硬一致)。可比性键比 invariance 多三个采样参数(temperature/top_p/seed)。实测依据:贪心 8/8 逐字节一致 vs 采样 0.7+seed 7/8 一致(index=2 第 46 token 分叉),见 [results/invariance-2026-11-10/verdict-sampled.md](results/invariance-2026-11-10/verdict-sampled.md)。
68
+ >
69
+ > **stability 口径 caveat(单 prompt 复制)**:单 prompt × 单 seed 的 N 个请求是同一 query 的 N 份拷贝(实测 8 条输出全同),此时 divergence_rate 的分母是 batch 槽位数、不是独立 query——量的是「槽位对同一 fork 点的翻与不翻」。要测 query 级分歧率,用 `run_benchmark(prompts=[...])`(每请求独立 prompt,seed+i 独立种子),config 的 `prompt_sha256` 变为逐请求哈希串联,可比性检查照常生效。查询级三次独立跑(带 tag 留档,同一组 8 条 prompt)稳定读数:c=4 分歧 3/8=0.375、c=16 分歧 4/8=0.500,且 c=1 baseline 跨跑 8/8 逐字节可复现;翻转集中在固定 query(c=4 的 0/2/3、c=16 的 0/2/3/4 每跑必翻),说明是 query 自身的近并列 fork 点被 batch 放大,不是随机噪声。两种口径(槽位拷贝 vs 独立 query)量纲不同,不可相减。见 [verdict-queries-multirun.md](results/invariance-2026-11-10/verdict-queries-multirun.md)。
70
+ >
71
+ > **服务端配置声明 `server_env`(2026-11-17)**:`VLLM_BATCH_INVARIANT`(vLLM 文档
72
+ > [docs/features/batch_invariance.md](https://github.com/vllm-project/vllm/blob/main/docs/features/batch_invariance.md))
73
+ > 直接改写「batch 改变输出」的语义——**flag=0(默认)时那是设计行为,flag=1 时才承诺
74
+ > 输出与 batch 大小/顺序无关**。因此服务端配置必须进可比性键:`run --server-env VLLM_BATCH_INVARIANT=1`
75
+ > 写进报告 `config.server_env`,invariance / stability 两侧声明不同即判**不可比(退出码 2)**。
76
+ > 不声明保持缺键(=未声明),与同为未声明的一侧可比;`server_env: {}` 与缺键等价。
77
+ > 少了这一项,闸会把「配置不同」误判成「实现违反不变性」——方向最坏的误判(编排/实验噪声被读成缺陷)。
78
+
79
+ > **40 条独立 query × 两个 flag 值实测(2026-11-17)**:`VLLM_BATCH_INVARIANT=0`(默认)下
80
+ > c=4 与 c=16 各 2/40 = 0.050(Wilson [0.014, 0.165]);`=1` 下两组都是 **0/40**(上界 **0.088** < 0.2)——
81
+ > 决定性 PASS,即 vLLM 文档承诺的 batch 不变性在**消费级 Ampere(sm_86,不在 tuned matmul 表里)+ AWQ +
82
+ > `--enforce-eager`** 这个上游没测过的组合上仍然成立。代价实测:TPOT 约 2.7×(61→175 ms)、
83
+ > 吞吐 −58~−63%、TTFT 基本不变、整轮墙钟 2.6×。**同时登记一次预注册未命中**:跑前按 8 条 query 的
84
+ > 3/8 外推期望 15/40 `FAIL_DECISIVE`,实测 2/40 方向相反——8 样本点估计不可外推,判据没改、读数照写。
85
+ > 见 [verdict-queries40-pair.md](results/invariance-2026-11-10/verdict-queries40-pair.md)。
86
+
87
+ > **stability 功效见证**:n=8 时即便 0/8 分歧,Wilson 95% 上界仍有 0.324 > 上限 0.2,PASS 不是「rate ≤ 上限」的证据。gate 在 PASS 且上界超过上限时自动附一条 kind=power 见证检查(不改判决),并给出零分歧下把上界压到限内所需的样本数(0.2 档为 n≥16 条**不同** query)。反向亦然:3/8 的 Wilson 下界 0.137 ≤ 0.2,FAIL 也不必然是总体超限;见证只挂 PASS 是 fail-closed 取舍(PASS 放行部署才是危险方向)。重复跑同一组 8 条 query 不能把分母乘 3。要机械判定某个分歧率上限,先铺够独立 prompt。
88
+ >
89
+ > **p99_basis**:分布节点(count<20)带 `"p99_basis": "max"`——此时 p99 由末位 1–2 个样本主导,不是可分位估计,数值也未必等于 max(canonical runD 实测 8 样本 p99=123.7 而 max=123.9;另一次 p99/max≈583 把 c=4 判得比 c=16 还慢)。gate 对引用 `*.p99` 的上限规则自动附一条 basis 见证检查(不改判决),延迟结论请引 p50。
90
+
91
+ > **采样不变性实弹(2026-11-10)**:temperature=0.7 + seed=1234 下 c=1 vs c=16 **7/8 一致、index=2 在第 46 个 token 分叉**——采样解码下 batch 不变性不成立(浮点归约顺序随批形态变化,采样把微小 logits 差异放大成分叉)。贪心 8/8 一致 vs 采样 7/8:invariance 闸适用边界=temperature=0;采样解码要用分布稳定性判据(未实现,见 [results/invariance-2026-11-10/verdict-sampled.md](results/invariance-2026-11-10/verdict-sampled.md))。
55
92
  - 退出码:`0` 通过(可能带 WARN 贴边提示)|`1` 有规则不通过、失败数超过预算(默认 0)、或缺指标|`2` 策略/报告无效,或两次测量不可比。
56
93
 
57
94
  **fail-closed 的地方**(这些都是踩过的坑,不是设计洁癖):
@@ -66,6 +103,24 @@ ttftkit 刻意做小:**只测一个端点、只做闭环并发、只输出可
66
103
 
67
104
  策略写法与取舍见 [`docs/gate.md`](docs/gate.md)。
68
105
 
106
+ ## SLO 负载扫描(v0.3)
107
+
108
+ 「满负载下多少 tok/s」是个容易误导人的数:牺牲延迟换来的吞吐也会被算进去。`scan` 反过来问——**在延迟/错误率约束下,能撑到多少负载**(SLO-qualified goodput,见 [`docs/papers.md`](docs/papers.md) C1)。
109
+
110
+ ```bash
111
+ ttftkit scan --endpoint http://127.0.0.1:8000/v1/chat/completions --model Qwen/Qwen2.5-7B-Instruct \
112
+ --levels 1,2,4,8,16 --slo-ttft 800 --slo-tpot 60 --slo-error-rate 0.0 \
113
+ --requests 16 --max-tokens 128 --profile rtx4090-vllm-0.6.3 --output results/scan.json
114
+ ```
115
+
116
+ 输出:逐级一行(并发 / 是否满足 / req/s / tok/s / TTFT p95 / TPOT p95 / 违反了哪条),加一句「满足 SLO 的最高负载」。三条纪律:
117
+
118
+ 1. **违反的那一级留在报告里**(`stopped_at` + `violations`)——只报好看的数字等于自欺。
119
+ 2. **一级违反即停**,继续往上扫只会把超时和崩溃混进数据。
120
+ 3. **没有证据不算通过**:某一级缺 p95(`null`)记为「不满足」,不当作默认达标。
121
+
122
+ `scan` 报告**不能直接过门禁**(`kind: "scan"` → 退出码 `2`):它是多级聚合,请挑一级的 `levels[i].summary` 当单次测量再判。
123
+
69
124
  ## 显存与 GPU 采样(v0.2)
70
125
 
71
126
  ```bash
@@ -105,6 +160,10 @@ CI 里先用**影子模式**(`scripts/shadow_gate.py` 不带 `--strict` 时恒
105
160
  - name: Release gate
106
161
  run: ttftkit gate results/run.json --policy configs/policy.json --baseline baselines/main.json
107
162
  # 或者先用影子门禁:只记录读数,不阻断
163
+ # SLO 扫描(可选):只记录,不比绝对值
164
+ - name: SLO scan
165
+ run: ttftkit scan --endpoint "$ENDPOINT" --model "$MODEL" --levels 1,2,4,8 \
166
+ --slo-ttft 800 --profile "$PROFILE" --output results/scan.json
108
167
  - name: Shadow gate (non-blocking)
109
168
  continue-on-error: true
110
169
  run: python scripts/shadow_gate.py --report results/run.json --baseline baselines/main.json --policy configs/policy.baseline.json
@@ -139,8 +198,9 @@ Ryzen 5800H / 无 GPU / ollama `qwen2.5-coder:0.5b`,3 请求、并发 1、`max
139
198
  在真实本地 SSE 服务上跑通(`tests/` 含真实本地 SSE 服务用例)。
140
199
  - 门禁**fail-closed**:指标缺失/`NaN`/`inf`/字符串/布尔 → 不通过;空策略/未知指标名 → 配置错误(`2`);
141
200
  相对比较要求协议/模型/并发/token/请求数/prompt 哈希/指纹完全一致,否则不可比。
142
- - 已知退化**会被拦住**:`scripts/red_check.py` 逐条回退 32 处修复,对应用例全部变红(32/32),
201
+ - 已知退化**会被拦住**:`scripts/red_check.py` 逐条回退 64 处修复,对应用例全部变红(64/64),
143
202
  证明这些判定不是摆设。
203
+ - **SLO 扫描与客户端污染可判定**:`scan` 违反即停且保留坏级别、`null` 不当通过;`client.lag` 能测到人为阻塞(`time.sleep(0.08)` → `max_ms ≥ 30`),且门禁拒绝「summary 声称 lag 但没有 `client` 块」。
144
204
  - 硬件块**自洽且可溯源**:`delta == peak − baseline`、负数/超设备总量 → 配置错误、
145
205
  `config.hardware` 必须等于用块重算的指纹(防改块绕过可比性门禁)。
146
206
  - 基线与阈值**来自同机 5 次实测**,不是拍的:`baselines/README.md` 给出 5 次全表 + 复现命令,
@@ -154,6 +214,9 @@ Ryzen 5800H / 无 GPU / ollama `qwen2.5-coder:0.5b`,3 请求、并发 1、`max
154
214
  - 显存是**设备级 + 轮询**:同卡其他进程的变化会混进 `delta`,间隔内的单次尖峰可能被漏掉(见 [`docs/hardware.md`](docs/hardware.md))。
155
215
  - 闭环固定并发,**不模拟泊松到达或真实流量分布**;要那个用 `aiperf`。
156
216
  - TPOT 是**客户端近似**:同一 SSE 块内的 token 时间无法拆分。
217
+ - 客户端 lag 只是**上界的一半**:同一台机器上别的进程也在抢 CPU;它不是「服务端慢了多少」的分解。
218
+ - `scan` 的结论仍是**闭环**结论(「K 个并发客户端下」),不是生产到达率下的容量;要开环到达率请用 `aiperf` / `guidellm`。
219
+ - 分位数置信区间是**分位数本身的不确定性**,不是「下一次测量的预测区间」,别拿它当 SLO 余量。
157
220
  - **不做分布式多机压测**,不测第三方付费 API 的绝对性能(网络抖动会污染结果)。
158
221
 
159
222
  ## 开发
@@ -164,9 +227,9 @@ python3 -m ruff check src tests scripts
164
227
  python3 scripts/red_check.py # RED 反证:把修复回退后,对应测试必须变红
165
228
  ```
166
229
 
167
- `red_check.py` 是变异检查的自动化版本:在临时副本上逐条回退修复(TTFT 取值时机、门禁边界、吞吐分母、token 口径、坏 `choices`、总时限、错误串回显、非字符串 `content`、残缺报告、warmup 退出码、`count=0` 带分位数、显存 `null`→`0`、硬件可比性、影子门禁退出码、label 恒 PASS、利用率方向、stop 截断、单样本 delta、零样本块、指纹 `none`、证据链不一致、影子读坏输入、指纹溯源、截断读数、物理不可能值、Collector 参数),跑对应用例并断言它**失败**。当前 32/32 全部变红——修复若只是摆设,这一步会变绿并报错。
230
+ `red_check.py` 是变异检查的自动化版本:在临时副本上逐条回退修复(TTFT 取值时机、门禁边界、吞吐分母、token 口径、坏 `choices`、总时限、错误串回显、非字符串 `content`、残缺报告、warmup 退出码、`count=0` 带分位数、显存 `null`→`0`、硬件可比性、影子门禁退出码、label 恒 PASS、利用率方向、stop 截断、单样本 delta、零样本块、指纹 `none`、证据链不一致、影子读坏输入、指纹溯源、截断读数、物理不可能值、Collector 参数、lag 空样本 `null`、lag 真能测到阻塞、扫描违反即停、缺证据不算通过、scan 不可过门禁、lag 无来源、bootstrap 种子、小样本不给区间、client 块形状、server_env 可比性键、server_env 缺键回落、build_report 读真字段),跑对应用例并断言它**失败**。当前 **64/64** 全部变红——修复若只是摆设,这一步会变绿并报错。
168
231
 
169
- 按 JD 练习的路径见 [`docs/labs.md`](docs/labs.md)(8 个实验,每个都有可复跑的通过判据)。
232
+ 按 JD 练习的路径见 [`docs/labs.md`](docs/labs.md)(10 个实验,每个都有可复跑的通过判据);这些能力的文献依据与「哪些只是文档、哪些真实现了」见 [`docs/papers.md`](docs/papers.md)。
170
233
 
171
234
  ## License
172
235
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "ttftkit"
7
- version = "0.2.1"
7
+ version = "0.4.0"
8
8
  description = "LLM serving benchmark harness and release gate: TTFT / TPOT / throughput / stability, CI-ready"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -1,3 +1,3 @@
1
1
  """ttftkit: OpenAI 兼容推理服务的性能测量与回归门禁。"""
2
2
 
3
- __version__ = "0.2.1"
3
+ __version__ = "0.4.0"
@@ -13,8 +13,9 @@ from pathlib import Path
13
13
  from . import __version__
14
14
  from .gate import evaluate
15
15
  from .hardware import command_sampler, detect_sampler
16
- from .report import markdown, write
16
+ from .report import markdown, write, write_scan
17
17
  from .runner import BenchmarkFailed, run_benchmark
18
+ from .scan import scan
18
19
 
19
20
  DEFAULT_PROMPT = "Explain in one paragraph why KV cache memory grows with context length."
20
21
 
@@ -40,6 +41,19 @@ def _load(path: str | Path) -> dict:
40
41
  return data
41
42
 
42
43
 
44
+ def _parse_kv(pairs) -> dict[str, str] | None:
45
+ """["K=V", ...] -> {"K": "V"};格式错误 fail-closed(配置声明错了比不声明更危险)。"""
46
+ if not pairs:
47
+ return None
48
+ out: dict[str, str] = {}
49
+ for item in pairs:
50
+ key, sep, value = item.partition("=")
51
+ if not sep or not key.strip():
52
+ raise SystemExit(f"--server-env 需要 KEY=VALUE 形式,收到 {item!r}")
53
+ out[key.strip()] = value.strip()
54
+ return out
55
+
56
+
43
57
  def cmd_run(args) -> int:
44
58
  if not math.isfinite(args.sample_interval) or args.sample_interval <= 0:
45
59
  raise ValueError(f"--sample-interval must be finite and positive, got {args.sample_interval!r}")
@@ -60,6 +74,10 @@ def cmd_run(args) -> int:
60
74
  slo_tpot_ms=args.slo_tpot,
61
75
  sampler=sampler,
62
76
  sample_interval_s=args.sample_interval,
77
+ temperature=args.temperature,
78
+ top_p=args.top_p,
79
+ seed=args.seed,
80
+ server_env=_parse_kv(args.server_env),
63
81
  )
64
82
  )
65
83
  json_path, md_path = write(result, args.output)
@@ -78,6 +96,69 @@ def cmd_run(args) -> int:
78
96
  return 0
79
97
 
80
98
 
99
+ def _parse_levels(text: str) -> list[int]:
100
+ levels: list[int] = []
101
+ for piece in text.split(","):
102
+ piece = piece.strip()
103
+ if not piece:
104
+ raise ValueError(f"--levels must be comma-separated integers, got {text!r}")
105
+ try:
106
+ levels.append(int(piece))
107
+ except ValueError:
108
+ raise ValueError(f"--levels must be comma-separated integers, got {text!r}") from None
109
+ return levels
110
+
111
+
112
+ def cmd_scan(args) -> int:
113
+ """多级并发扫描:报「满足 SLO 的最高负载」。见 docs/papers.md C1。"""
114
+ if not math.isfinite(args.sample_interval) or args.sample_interval <= 0:
115
+ raise ValueError(f"--sample-interval must be finite and positive, got {args.sample_interval!r}")
116
+ levels = _parse_levels(args.levels)
117
+ sampler = _sampler_for(args)
118
+ last_client: dict | None = None
119
+
120
+ def run_level(level: int) -> dict:
121
+ nonlocal last_client
122
+ report = asyncio.run(
123
+ run_benchmark(
124
+ endpoint=args.endpoint,
125
+ model=args.model,
126
+ prompt=args.prompt,
127
+ # 每个 worker 至少能拿到一个请求,否则高并发的「并发」是假的
128
+ requests=max(args.requests, level),
129
+ concurrency=level,
130
+ max_tokens=args.max_tokens,
131
+ warmup=args.warmup,
132
+ timeout_s=args.timeout,
133
+ profile=args.profile,
134
+ api_key=args.api_key,
135
+ slo_ttft_ms=args.slo_ttft,
136
+ slo_tpot_ms=args.slo_tpot,
137
+ sampler=sampler,
138
+ sample_interval_s=args.sample_interval,
139
+ )
140
+ )
141
+ last_client = report.get("client")
142
+ return report
143
+
144
+ result = scan(
145
+ run_level,
146
+ levels,
147
+ slo_ttft_ms=args.slo_ttft,
148
+ slo_tpot_ms=args.slo_tpot,
149
+ slo_error_rate=args.slo_error_rate,
150
+ )
151
+ result["client"] = last_client # 只保留最后一级的客户端读数(逐级数据在 levels[i])
152
+ json_path, md_path = write_scan(result, args.output)
153
+ print(f"扫描报告:{json_path} {md_path}")
154
+ best = result["slo_rps"]
155
+ if best is None:
156
+ print("ttftkit: 没有任何级别满足 SLO", file=sys.stderr)
157
+ return 1
158
+ print(f"满足 SLO 的最高负载:{round(best, 3)} req/s(首次违反:{result['stopped_at']})")
159
+ return 0
160
+
161
+
81
162
  def cmd_gate(args) -> int:
82
163
  candidate = _load(args.report)
83
164
  policy = _load(args.policy)
@@ -128,8 +209,39 @@ def build_parser() -> argparse.ArgumentParser:
128
209
  help="自定义采样命令(须输出 nvidia-smi CSV 格式),配合 --gpu command")
129
210
  run.add_argument("--sample-interval", type=float, default=0.25,
130
211
  help="采样间隔(秒),默认 0.25")
212
+ run.add_argument("--temperature", type=float, default=0.0,
213
+ help="采样温度,默认 0(贪心解码,历史行为)")
214
+ run.add_argument("--top-p", type=float, default=None,
215
+ help="nucleus 采样 top_p(0,1],缺省不发送")
216
+ run.add_argument("--server-env", action="append", default=None, metavar="KEY=VALUE",
217
+ help="服务端配置声明(可重复),如 --server-env VLLM_BATCH_INVARIANT=1。"
218
+ "写进报告 config.server_env,闸据此判断两份读数是否可比;"
219
+ "不声明就保持「未声明」,不会被当成默认值 0")
220
+ run.add_argument("--seed", type=int, default=None,
221
+ help="随机种子(非负整数),缺省不发送")
131
222
  run.set_defaults(func=cmd_run)
132
223
 
224
+ scan_cmd = sub.add_parser("scan", help="多级并发扫描:满足 SLO 的最高负载(SLO-qualified goodput)")
225
+ scan_cmd.add_argument("--endpoint", required=True)
226
+ scan_cmd.add_argument("--model", required=True)
227
+ scan_cmd.add_argument("--prompt", default=DEFAULT_PROMPT)
228
+ scan_cmd.add_argument("--levels", required=True, help="并发级别,升序逗号分隔,如 1,2,4,8")
229
+ scan_cmd.add_argument("--requests", type=int, default=16,
230
+ help="每级请求数(不足该级并发时按并发数抬高)")
231
+ scan_cmd.add_argument("--max-tokens", type=int, default=32)
232
+ scan_cmd.add_argument("--warmup", type=int, default=0)
233
+ scan_cmd.add_argument("--timeout", type=float, default=60.0)
234
+ scan_cmd.add_argument("--profile", default="unspecified")
235
+ scan_cmd.add_argument("--slo-ttft", type=float, default=None, help="TTFT p95 上限(ms)")
236
+ scan_cmd.add_argument("--slo-tpot", type=float, default=None, help="TPOT p95 上限(ms)")
237
+ scan_cmd.add_argument("--slo-error-rate", type=float, default=0.0, help="错误率上限,默认 0")
238
+ scan_cmd.add_argument("--output", default="results/scan.json")
239
+ scan_cmd.add_argument("--api-key", default=os.environ.get("TTFTKIT_API_KEY"))
240
+ scan_cmd.add_argument("--gpu", choices=("auto", "none", "command"), default="auto")
241
+ scan_cmd.add_argument("--gpu-command", default=None)
242
+ scan_cmd.add_argument("--sample-interval", type=float, default=0.25)
243
+ scan_cmd.set_defaults(func=cmd_scan)
244
+
133
245
  gate = sub.add_parser("gate", help="按策略判定一份报告能否放行")
134
246
  gate.add_argument("report")
135
247
  gate.add_argument("--policy", required=True)
@@ -21,9 +21,11 @@ DEFAULT_PATH = "/v1/chat/completions"
21
21
  SUCCESS_FINISH_REASONS = frozenset({"stop", "length"})
22
22
 
23
23
 
24
- def _fail(index: int, t0: float, error: str, latency_ms: float | None = None) -> RequestRecord:
24
+ def _fail(index: int, t0: float, error: str, latency_ms: float | None = None,
25
+ output_text: str | None = None) -> RequestRecord:
25
26
  latency = latency_ms if latency_ms is not None else (time.perf_counter() - t0) * 1000
26
- return RequestRecord(index=index, ok=False, latency_ms=latency, error=error, started_at=t0)
27
+ return RequestRecord(index=index, ok=False, latency_ms=latency, error=error,
28
+ started_at=t0, output_text=output_text)
27
29
 
28
30
 
29
31
  def _count(value, what: str) -> int:
@@ -43,6 +45,7 @@ async def measure_request(
43
45
  index: int = 0,
44
46
  timeout_s: float = 60.0,
45
47
  path: str = DEFAULT_PATH,
48
+ capture_text: bool = False,
46
49
  ) -> RequestRecord:
47
50
  """发一次流式请求并记录计时。
48
51
 
@@ -55,7 +58,8 @@ async def measure_request(
55
58
  t0 = time.perf_counter()
56
59
  try:
57
60
  return await asyncio.wait_for(
58
- _measure_once(client, payload, index=index, t0=t0, timeout_s=timeout_s, path=path),
61
+ _measure_once(client, payload, index=index, t0=t0, timeout_s=timeout_s,
62
+ path=path, capture_text=capture_text),
59
63
  timeout=timeout_s,
60
64
  )
61
65
  except asyncio.TimeoutError:
@@ -70,11 +74,15 @@ async def _measure_once(
70
74
  t0: float,
71
75
  timeout_s: float,
72
76
  path: str,
77
+ capture_text: bool = False,
73
78
  ) -> RequestRecord:
74
79
  first_t: float | None = None
75
80
  last_t: float | None = None
76
81
  content_chunks = 0
77
82
  intervals: list[float] = []
83
+ # 捕获缓冲:只有 capture_text=True 才收文本;性能测量默认不存文本
84
+ # (报告体积与敏感面都小一个量级),invariance 闸开捕获时才付这个成本。
85
+ text_parts: list[str] | None = [] if capture_text else None
78
86
  output_tokens: int | None = None
79
87
  prompt_tokens: int | None = None
80
88
  finish_reason: str | None = None
@@ -134,6 +142,8 @@ async def _measure_once(
134
142
  return _fail(index, t0, "invalid event: content is not a string")
135
143
  if content:
136
144
  content_chunks += 1
145
+ if text_parts is not None:
146
+ text_parts.append(content)
137
147
  if first_t is None:
138
148
  first_t = now
139
149
  else:
@@ -150,13 +160,14 @@ async def _measure_once(
150
160
  return _fail(index, t0, f"http error: {type(exc).__name__}")
151
161
 
152
162
  latency_ms = (time.perf_counter() - t0) * 1000
163
+ captured = "".join(text_parts) if text_parts is not None else None
153
164
  if content_chunks == 0:
154
- return _fail(index, t0, "empty content", latency_ms)
165
+ return _fail(index, t0, "empty content", latency_ms, output_text=captured)
155
166
  if finish_reason is not None and finish_reason not in SUCCESS_FINISH_REASONS:
156
167
  # 同理不内插服务端取值,只报「非正常结束」这一事实
157
- return _fail(index, t0, "unsuccessful finish_reason", latency_ms)
168
+ return _fail(index, t0, "unsuccessful finish_reason", latency_ms, output_text=captured)
158
169
  if finish_reason is None and not done_seen:
159
- return _fail(index, t0, "stream ended without finish_reason", latency_ms)
170
+ return _fail(index, t0, "stream ended without finish_reason", latency_ms, output_text=captured)
160
171
 
161
172
  assert first_t is not None and last_t is not None # content_chunks > 0 保证
162
173
  return RequestRecord(
@@ -170,4 +181,5 @@ async def _measure_once(
170
181
  prompt_tokens=prompt_tokens,
171
182
  chunk_intervals_ms=tuple(intervals),
172
183
  started_at=t0,
184
+ output_text=captured,
173
185
  )