Skip to content

LLM runner: validate and drive hf_static float-cache programs - #24572

Draft
psiddh wants to merge 8 commits into
pytorch:mainfrom
psiddh:stack2/pr07-hf-static-runtime
Draft

psiddh wants to merge 8 commits into
pytorch:mainfrom
psiddh:stack2/pr07-hf-static-runtime

Conversation

@psiddh

@psiddh psiddh commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

LLM runner: validate and drive hf_static float-cache programs

Resetting only logical position while leaving cache counters stale corrupts subsequent generation. The hf_static IOManager supplies authoritative start_pos counters, validates version-1 metadata and buffer geometry, and drives fixed methods through shared float-cache buffers.

The program keeps HF's static-cache tensor interface with a fixed prefill/decode padding protocol. Window masks exclude padding, and a tail that does not fit as a padded prefill runs through decode before execution. Logits remain at 3 * n_layers; the mutation prefix is opaque. Optional ordered state suffix outputs bind to existing buffers rather than allocating another cache.

Register the hf_static manager from this PR, replacing PR 3's inert builtin definition. Review validation/state handling, registration, build wiring and float32/float16/repeated-state fixtures. C++ has no transformers dependency; Python loading needs PR 6's guarded local-branch hook. Quantized caches, sha and full-length sliding mode are excluded.

Buffer ownership, fixed-shape execution and reset are implemented. Inspection, adopt/fork/evict hooks and arbitrary context extension remain follow-ups.

Files

extension/llm/runner/io_manager/hf_static_io_manager.cpp
extension/llm/runner/io_manager/hf_static_io_manager.h
extension/llm/runner/io_manager/targets.bzl
extension/llm/runner/llm_runner_helper.cpp
extension/llm/runner/targets.bzl
extension/llm/runner/test/BUCK
extension/llm/runner/test/CMakeLists.txt
extension/llm/runner/test/export_hf_static_program.py
extension/llm/runner/test/test_hf_static_io_manager.cpp
shim_et/xplat/executorch/build/build_variables.bzl

Test Plan

Commit cb09f3b3e2b9e529875812fa6377908c9f351e95 on 892e50425f5a3e90ff8d3c8802fdfb31f8599518. Validated locally with Python 3.12, pinned Torch/TorchAO, the local transformers exporter branch and QAIRT SDK 2.48.

223 runner tests passed, including all 77 hf_static cases; 2 existing skips; 0 failures.

cmake --build /data/users/sidart/qnnflow/gh_prs/build-split-native-pr07-final -j4 --target test_runner
ctest --test-dir /data/users/sidart/qnnflow/gh_prs/build-split-native-pr07-final -R "^test_runner$" --output-on-failure -V

The two existing runner skips are TextDecoderRunnerTest.LoadUsesMethodName and StepWithAllModels.

No device/physical rpcmem, two-target FCB, real-model export or full QNN device-suite result is claimed. Buck could not start because the local launcher requires a missing .buck2. The base already contains #23563 and #23183; neither is a separate prerequisite commit here.

Related PRs (review in order)

  1. Partitioner: run backend-contributed edge transform passes #24566 Partitioner: run backend-contributed edge transform passes
  2. Export: avoid reused lifted-constant names #24567 Export: avoid reused lifted-constant names
  3. LLM runner: select I/O contracts and accept custom buffer allocators #24568 LLM runner: select I/O contracts and accept custom buffer allocators
  4. QNN: construct partitioners from options and allocate LLM I/O in rpcmem #24569 QNN: construct partitioners from options and allocate LLM I/O in rpcmem
  5. QNN: bind delegate outputs in exported program order #24570 QNN: bind delegate outputs in exported program order
  6. QNN: never mix shared and client buffers in one graph execute #25345 QNN: never mix shared and client buffers in one graph execute
  7. Export hf_static float-cache programs and register their Python runner #24571 Export hf_static float-cache programs and register their Python runner
  8. LLM runner: validate and drive hf_static float-cache programs #24572 LLM runner: validate and drive hf_static float-cache programs
  9. Document the version-1 hf_static I/O contract #24573 Document the version-1 hf_static I/O contract
  10. portable: copy consecutive index_put_ rows in one block #25346 portable: copy consecutive index_put_ rows in one block
  11. LLM runner: never sample more logits than the model returns #25347 LLM runner: never sample more logits than the model returns
  12. hf_static v2: transposed key caches, full-length sliding caches, per-head attention #25348 hf_static v2: transposed key caches, full-length sliding caches, per-head attention
  13. LLM runner: drive hf_static v2 programs #25349 LLM runner: drive hf_static v2 programs
  14. QNN: export quantized hf_static programs in the NPU cache layout #25350 QNN: export quantized hf_static programs in the NPU cache layout
  15. Document the hf_static v2 NPU cache layout #25351 Document the hf_static v2 NPU cache layout

Each PR includes the commits of the ones above it; review only its own top commit.

@pytorch-bot

pytorch-bot Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/24572

Note: Links to docs will display an error until the docs builds have been completed.

❌ 3 New Failures, 1 Unrelated Failure, 5 Unclassified Failures

As of commit c87270e with merge base 765e973 (image):

NEW FAILURES - The following jobs have failed:

UNCLASSIFIED FAILURES - DrCI could not classify the following jobs because the workflow did not run on the merge base. The failures may be pre-existing on trunk or introduced by this PR:

BROKEN TRUNK - The following job failed but were present on the merge base:

👉 Rebase onto the `viable/strict` branch to avoid these failures

This comment was automatically generated by Dr. CI and updates every 15 minutes.

@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown

This PR needs a release notes: label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Nov 3, 2026
Run each partitioner’s edge transforms after caller-supplied passes so backends can use the standard lowering entry point. QNN contributes its existing transforms through the new hook.
Reserve names for constant tensors already present in the exported program before lifting new constants, so methods with folded tables retain distinct constants.
Choose the registered IOManager and its logits, method names and step sizes, rejecting unknown contracts and invalid metadata. Load and reset the selected methods; route prompt tails to decode with a side-effect-free capacity check. Preserve module and I/O-buffer lifetimes and expose a backend-neutral allocator hook.
Route backend options through QnnPartitioner.from_options and register an allocator that supplies QNN shared-memory buffers through the generic IOManager hook. The LLM runner remains backend-neutral.
Encode graph output positions and restore their order at both runtime tensor-allocation entry points. Preserve context-binary order and legacy mutable outputs, and ignore malformed or overflowing position labels without throwing. This runtime change needs Qualcomm review.
On QNN SDK 2.48 an HTP execute that binds some tensors as registered rpcmem and others as plain client buffers fails (prefill DMA error 1100, decode transport error 1003) or produces wrong results; 2.50 and 2.51 runtimes run the same binding correctly. LLM runners place their caches, masks, positions and logits in rpcmem through the I/O buffer allocator, but delegate inputs and outputs that ExecuTorch plans internally (CPU-computed masks and RoPE tables, new K/V rows) stay in planned memory. When any tensor of an execute is shared, the backend now copies the remaining ones through persistent rpcmem staging buffers, one block per graph owned by the QnnManager and registered once, so each execute is all shared or all client memory. Executes without shared tensors are unchanged.

Authored with AI assistance (Metamate / agentcloud).
Move backend-neutral static-cache rewriting into the LLM extension and keep QNN partitioning and tuning in the backend. Detect sliding layers from model configuration, write every cache and counter in place on the caller buffer (export fails otherwise, since a missed write becomes full-cache CPU copies), and register a versioned runner that handles fixed chunks, padding, counters and reset. Quantized caches, sha attention and full-length sliding mode are excluded.

Authored with AI assistance (Metamate / agentcloud).
Use authoritative positions, float-cache version and dtype checks, exact buffer geometry and selected methods. Bind optional HF state outputs to existing buffers, preserve input aliases and register each concrete IOManager from its own implementation. Float-only fixtures cover reset, padding, malformed metadata and near-context tails.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant