#2660 tools: strata_profile.py, one command that says where the time goes on this PC (prompt phases, decode window split, hit rate per turn)

说明

## What it adds

`python tools/strata_profile.py`: one command that says **where the time goes** on this PC. It starts the server with the user's settings plus `STRATA_PREFILL_TIMING=1` and `STRATA_DECODE_TIMING=1` in the engine's environment (the switches docs/DETAILS.md describes under "Where a decode window's time goes"), sends a few typical requests through the HTTP API, reads the engine's own lines for each one, and writes `bench/results/<date>-profile-<gpu>-<model>/README.md` + `results.json`:

- **chat**: three short questions, 128 new tokens each (a decode window at a short context)
- **2K and 16K**: fresh prompts (the prompt path's phases)
- **long**: a fresh 32K prompt (`--long N`, 0 for none), then 128 tokens (decode at a long context, the KV streaming hit)
- **agent**: the bench's agent session (six requests), turn by turn (reused / read tokens, the hit rate per turn)

The report groups the prompt read's GPU time (experts streamed over PCIe, dequant, expert GEMM, attention, GDN, other), splits the decode window (the card, the experts computed on the CPU, the draft, the adaptive tier, other) with the hit rate and PCIe share, and ends with findings in words that name the setting on each path (the ones `setup --calibrate` measures where it does). The tokens per second in the report are measured with the switches on; the report says so and points to the bench for speeds. `--verify-profile` adds `STRATA_VERIFY_PROFILE=1`; `--url` with `--engine-log FILE` reads a server that is already running (without the log the report has the API's figures and no breakdown).

It reuses `tools/strata_bench.py` (the HTTP client, the calibrated prompt sizes, the agent session's text, the machine facts, the redaction). The server starts from a temporary copy of the config (0600, deleted at the end): the config is read, never written; `--expert-profile-save` is dropped for the run as the bench does (#2088); the engine log goes to a temporary file. The KV streaming line is cumulative over the process, so the report takes the difference between two lines for the long request's own share.

## Measured (RTX 5070 Ti 16 GB, Ryzen 7 5800X3D, 76 GB RAM, Linux, Strata 0.1.44.1, Swift 1.5 IQ3_S at 262K, INT8 KV, `--kv-resident 32768`)

The example report is in the PR: [`bench/results/2026-10-15-profile-rtx-5070-ti-swift-1-5-iq3-s`](https://github.com/qiuzan2001/Strata/blob/qiuzan2001/strata-profile/bench/results/2026-10-15-profile-rtx-5070-ti-swift-1-5-iq3-s/README.md). Three runs (two with an earlier revision of the tool) agree to a few percent.

| Read | Tokens | Prompt tok/s | experts over PCIe | dequant | expert GEMM | attention | GDN | other |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 2K fresh | 2,023 | 1,118 | 43% | 15% | 18% | 5% | 13% | 6% |
| 16K fresh | 16,058 | 2,982 | 5% | 8% | 30% | 18% | 25% | 14% |
| 32K fresh | 32,049 | 3,041 | 5% | 7% | 27% | 21% | 25% | 15% |

| Request | Context | Decode tok/s | Hit rate | ms/window | GPU | CPU experts | draft | adapt wait | CPU experts per layer-window |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| chat | 44 | 75.7 | 71% | 33.6 | 10.2 | 19.3 | 1.8 | 1.4 | 4.7 |
| long context | 32,049 | 82.0 | 82% | 27.4 | 10.0 | 13.1 | 2.3 | 1.3 | 3.6 |
| agent turns | 8,721 | 71.7 | 79% | 32.2 | 10.1 | 17.9 | 2.0 | 1.3 | 4.7 |

The long request's KV streaming: 96% of its 838,104 block reads from VRAM, 119 MiB from RAM. Agent session: the hit rate per turn runs from 51% (turn 0, right after the system prompt's read) to 86% (turn 4); follow-up turns read 1,469-3,380 tokens each. The run takes about 3 minutes after the model has loaded (36 s load, 2.5-3 min of requests).

## Checked

- `python3 tools/test_strata_profile.py`: 28/28 (the parsers on real engine lines, the grouping, the findings, the run against a fake server that writes an engine log; no GPU). `tools/test_strata_bench.py` 17/17 unchanged.
- Three real runs on the box above (one with `--verify-profile`, the last with the final code): every request's lines matched (prefill timing, host staging, decode timing, GPU stages, the prompt summary, the hit rate, KV streaming); the written report has no home folder, user or host name; the temporary config copy was gone at the end.
- The default path: a new tool and two docs paragraphs; no engine, server or setup file is touched, so the default is byte-identical.

## Not done

- HIP / Metal / SYCL servers are not run (the tool only reads lines; a backend that prints a different `prefill timing` line gets an empty breakdown and the API's figures, as the tests cover). `--batch` servers: the decode timing line is per request, the tool sends one request at a time, so it should work, but it was not run.
- A reviewer (a sub-agent) read the diff before this was opened; its findings (the cumulative KV line, experts vs entries, the log offset race, the wording of the findings, the temporary config's permissions) are in this revision.

The standalone companion, [Strata Profile Studio](https://github.com/qiuzan2001/strata-profile-studio) (Python standard library only), reads this tool's reports and compares runs against the noise floor of the PC, with a sign test over the agent turns.

🤖 Generated with [Claude Code](https://claude.com/claude-code)