model-infer-graph-mode

Adapt PyTorch models to torch.compile graph mode on Ascend NPU for inference acceleration.

Updated Sep 15, 2026
One-click install
npx skills add https://github.com/WangWindow/CANN-BatchMatMulMaxsum --skill model-infer-graph-mode-wangwindow
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: model-infer-graph-mode
Source: https://github.com/WangWindow/CANN-BatchMatMulMaxsum/tree/main/.agents/skills/model-infer-graph-mode
Command: npx skills add https://github.com/WangWindow/CANN-BatchMatMulMaxsum --skill model-infer-graph-mode-wangwindow

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, torch_npu, torchair, and includes references (resource) components.

What problem does it solve? Adapting PyTorch models to graph mode on Ascend NPU involves choosing between npugraph_ex and GE backends, fixing graph breaks, eliminating unexpected recompiles, and handling dynamic shapes like actual_seq_lengths in LLM decode. This Skill provides a structured workflow covering design, implementation, and verification for graph mode adaptation. ## Core Features & Use Cases - Backend Selection Guidance: Compares npugraph_ex (capture & replay, aclgraph) and GE graph mode (Ascend IR via torchair) with quick-start code for each. - LLM Prefill/Decode Separation: Enforces graph mode only on the Decode stage while keeping Prefill in eager mode, with KV cache pre-allocation and rotary embedding refactoring patterns. - Graph Break & Recompile Diagnosis: Provides a problem triage flow (aot_eager → force_eager → graph mode issue) plus FA operator configuration tables for actual_seq_lengths handling. - Use Case: An engineer's LLM decode step is slow due to kernel launch overhead. Use this Skill to compile the decode path with torch.compile backend npugraph_ex, pre-allocate KV cache, externalize dynamic inputs, and verify no recompiles occur during inference. ## Quick Start Ask the assistant to adapt your NPU model's decode stage to torch.compile graph mode and produce a design plan before making code changes.

Frequently Asked Questions about model-infer-graph-mode

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I use torch.compile graph mode on Ascend NPU?

Import torch_npu, then call torch.compile with backend="npugraph_ex" for capture-based graphs or torchair.get_npu_backend() for GE graph mode. For LLMs, compile only the decode method and keep prefill in eager mode.

What is the difference between npugraph_ex and GE graph mode?

npugraph_ex uses capture and replay (aclgraph), requires PyTorch 2.6.0+, and suits online inference. GE mode converts FX graphs to Ascend IR compiled by the GE engine, is more mature, and supports general scenarios via torchair CompilerConfig.

Why should graph mode only apply to the decode stage in LLM inference?

Prefill has dynamically varying input lengths and unstable shapes, making graph capture ineffective. Decode uses fixed single-token input shapes, so compiled graphs can be captured once and replayed each step.

How do I fix graph breaks and recompiles in torch.compile on NPU?

Enable recompile logging with torch._logging.set_logs(recompiles=True), remove .item() calls and data-dependent Python control flow, pre-allocate fixed-size KV cache with in-place updates, and pass dynamic values like actual_seq_lengths as inputs.

Does npugraph_ex support random operators and .item() calls?

No. npugraph_ex cannot capture random number operators (randn, dropout), dynamic control flow, stream synchronization, or .item() calls in forward. Replace them with tensor operations or pass values as external inputs.

When should I enable cache_compile for graph mode?

Enable cache_compile only after the graph captures stably with no graph breaks or unexpected recompiles. Regenerate the cache when model code, input specs, distributed rank/world_size, or CANN/torch_npu versions change.