Skip to content

refactor(qwen3): move the report harness out of the library API - #983

Open
onenewcode wants to merge 1 commit into
pegainfer-project:mainfrom
onenewcode:refactor/944-qwen3-report-harness-out-of-lib
Open

refactor(qwen3): move the report harness out of the library API#983
onenewcode wants to merge 1 commit into
pegainfer-project:mainfrom
onenewcode:refactor/944-qwen3-report-harness-out-of-lib

Conversation

@onenewcode

@onenewcode onenewcode commented Aug 28, 2026

Copy link
Copy Markdown

Description

Fixes #944.

pegainfer-qwen3 exposed pub mod kernel_bench (1112 lines) as public API. Every normal library and server build compiled report-only benchmark code and shipped its types in the crate's public surface.

The harness moves to pegainfer-qwen3/src/bin/report_support/, split across five modules, and is #[path]-included by the two kernel-report binaries. It is now compiled per binary and never as part of the library.

  • qwen3_kernel_report takes the whole tree. qwen3_model_report needs only common::L2CacheClear and includes that module alone, with the #[allow(dead_code)] on its own mod declaration rather than inside the shared module — so the other four modules stay dead-code-checked by the kernel report's build. Removing the allow and building qwen3_kernel_report alone yields 0 dead-code warnings, confirming the allow covers only the model report's narrower use.
  • The model report imports production primitives from their owning crates: build_split_kv_csr from pegainfer_core::ops, split_qkv_into from pegainfer_kernels::ops, instead of reaching through a harness re-export.
  • SplitKvConfig::{new, label} widen to pub. parse was already public and calls new, so a private constructor only pushed external callers onto the unchecked struct-literal path; label is parse's inverse, and restating its format in the harness would silently break the round-trip contract that label_parse_round_trips guards.
  • SPLIT_KV_CHUNK_TOKENS / SPLIT_KV_TUNED_MAX_CHUNKS are re-exported through runtime so the harness keeps deriving the Tuned split width from the runtime constants exactly as it did before the move, rather than restating 64x64 where a later retune would silently desync the report's split_tmp_* sizing.

Report schemas, CLI flags, benchmark cases, numeric policy, and kernel selection are unchanged; both binaries' --help output is identical.

Incidental fix. qwen3_model_report did not compile under --features kernel-report at main: it called ops::split_qkv_into, which pegainfer-core does not re-export. This was invisible because no CI job enables kernel-report — the two binaries carry required-features = ["kernel-report"], and qwen3-cuda-clippy does not pass it (the feature pulls pegainfer-cupti, excluded at ci.yml:300 for missing CUPTI headers in the CI toolkit). Worth a follow-up: this PR does not create that gap, but it does move ~1500 more lines behind it.

Docs. docs/models/qwen3/roadmap.md cleanup ledger strikes the kernel_bench.rs file-size entry. docs/subsystems/kernels/kernel-op-reports.md TL;DR records the new home and notes that paths in its Execution Log are historical — those are dated past-tense step records (Step 1 still uses the pre-flattening crates/ layout), so rewriting them to today's paths would falsify the record rather than fix it.

Type of Change

  • Bug fix (non-breaking change which fixes an issue) — the qwen3_model_report compile break described above
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected) — the crate's public API loses pub mod kernel_bench. No runtime behavior changes and no in-workspace consumer breaks; flagged because Move the Qwen3 benchmark harness out of the library public API #944 mandates the removal with no compatibility shim, so any out-of-tree user of that path is affected.
  • Documentation update

Checklist

  • My code follows the style guidelines of this project (see docs/conventions/coding-style.md).
  • I have performed a self-review of my own code.
  • I have formatted my commits according to Commitizen conventions.
  • I have run the local test suite and all tests pass (see CLAUDE.md).

Run locally on RTX 5090 (sm_120), driver 610.57.04:

Gate Result
cargo check --release -p pegainfer-qwen3 --lib pass, 0 warnings
cargo check --release -p pegainfer-qwen3 --all-targets --features kernel-report pass
cargo clippy --release -p pegainfer-qwen3 --all-targets --features kernel-report -- -D warnings pass
cargo test --release -p pegainfer-qwen3 --lib 88 passed, 0 failed
cargo build --release -p pegainfer-qwen3 --features kernel-report --bin qwen3_kernel_report --bin qwen3_model_report both link
cargo fmt --check pass

`pegainfer-qwen3` exposed `pub mod kernel_bench` (1112 lines) as public
API, so every normal library and server build compiled report-only
benchmark code and shipped its types in the crate's public surface.

Move the harness to `src/bin/report_support/`, split across five modules,
and `#[path]`-include it from the two `kernel-report` binaries. It is now
compiled per binary and never as part of the library.

- `qwen3_kernel_report` takes the whole tree; `qwen3_model_report` needs
  only `common::L2CacheClear` and includes that module alone, with the
  `#[allow(dead_code)]` on its own `mod` declaration so the other four
  modules stay dead-code-checked by the kernel report's build.
- The model report now imports production primitives from their owning
  crates: `build_split_kv_csr` from `pegainfer_core::ops` and
  `split_qkv_into` from `pegainfer_kernels::ops`, instead of reaching
  through a harness re-export. This also fixes a pre-existing build
  break: `qwen3_model_report` did not compile under `--features
  kernel-report` at HEAD, because `split_qkv_into` is not re-exported by
  `pegainfer-core`.
- `SplitKvConfig::{new, label}` widen to `pub`. `parse` was already
  public and calls `new`, so a private constructor only pushed external
  callers to the unchecked struct-literal path; `label` is `parse`'s
  inverse and restating its format in the harness would silently break
  the round-trip contract.
- `SPLIT_KV_CHUNK_TOKENS` / `SPLIT_KV_TUNED_MAX_CHUNKS` are re-exported
  through `runtime` so the harness keeps deriving the Tuned split width
  from the runtime constants, as it did before the move, rather than
  restating 64x64 where a retune would silently desync `split_tmp_*`.

Report schemas, CLI flags, benchmark cases, numeric policy, and kernel
selection are unchanged; both binaries' `--help` output is identical.

Verified on RTX 5090 (sm_120):
  cargo check  -p pegainfer-qwen3 --lib                                       0 warnings
  cargo check  -p pegainfer-qwen3 --all-targets --features kernel-report      pass
  cargo clippy -p pegainfer-qwen3 --all-targets --features kernel-report -D warnings  pass
  cargo test   -p pegainfer-qwen3 --lib                                       88 passed
  cargo build  --features kernel-report --bin qwen3_kernel_report --bin qwen3_model_report  both link
  cargo fmt --check                                                           pass

Closes pegainfer-project#944
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Move the Qwen3 benchmark harness out of the library public API

1 participant