docs: expand analyze/optimize content, rename hub→catalog#769
Merged
Conversation
Rewrite the analyze-and-optimize concept page with source-verified content: SupportLevel classification table, lint vs autoconf outputs, analysis modes, three finding classes, local op execution, HTP metadata, internal pipeline stages, optimizer pipe architecture (4 pipes, 43 capabilities across 13 categories, 5 rewrite groups / 12 rules), and the autoconf loop diagram (SVG). Update the analyze command reference with corrected EP aliases, exit-code table, and additional examples. Rename hub.md → catalog.md and update all cross-references. Also fix check-yaml pre-commit hook to support !!python/name tags in mkdocs.yml (--unsafe).
|
|
||
| When a model is exported with hierarchy-preserving tags (HTP), the export produces a sidecar `_htp_metadata.json` that maps each ONNX node back to its source module (e.g., `encoder.layer.0.attention.self.GELUActivation`). Passing this file via `--htp-metadata` lets the `PatternExtractor` use the module hierarchy to match subgraph patterns more accurately than operator-level heuristics alone. | ||
|
|
||
| HTP metadata is consumed at the pattern extraction stage — before any EP-specific runtime checking — so the enriched patterns benefit all target EPs equally (QNN, OpenVINO, VitisAI, etc.). Without HTP metadata, the analyzer falls back to attribute-based tag matching and then the general-purpose `PatternMatcher`; with it, the analyzer can correctly identify fused patterns (GELU, LayerNorm, Attention) that are difficult to detect from the raw operator graph. See the [analyze command reference](../commands/analyze.md) for usage examples. |
Contributor
There was a problem hiding this comment.
The explanation of relation between HTP metadata and PatternMatcher seems a bit fuzzy, and unclear on why both would be needed in our system. Maybe simply state the benefits of HTP metadata when it's available, and it can be obtained in winml export/build stage by passing a HTP flag, without mentioning PatternMatcher?
| This granularity matters when a specific fusion breaks a downstream step or when you need an exact optimization profile for a given EP. Some capabilities declare dependencies (e.g., `bias-gelu-fusion` requires `gelu-fusion`); the optimizer resolves these automatically when you enable a flag. | ||
|
|
||
| **Pattern rewrites** are a complementary mechanism: instead of folding nodes, rewrites replace one subgraph pattern with a structurally equivalent alternative. Rules are defined in JSON files (`default.json` for general rewrites, `qnn.json` for QNN-specific rewrites). The optimizer currently ships 5 rewrite groups containing 12 individual rules — for example, four GELU source variants can each be rewritten to a single `Gelu` op, and a MatMul+Add pattern can be rewritten to a GEMM or to a Conv2D for Qualcomm NPU targets. Run `--list-rewrites` to discover available families and their flag names. Flags follow the form `--enable-<source-slug>-<target-slug>`. | ||
|
|
Contributor
There was a problem hiding this comment.
nit: a md file with all the optimizer flags would also be convenient for user's reference
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/concepts/analyze-and-optimize.mdwith source-verified content: SupportLevel classification table, lint vs autoconf outputs, analysis modes, optimizer pipe architecture (4 pipes, 43 capabilities, 5 rewrite groups / 12 rules), and autoconf loop SVG diagramdocs/commands/analyze.mdwith corrected EP aliases, exit-code table, and additional CLI exampleshub.md→catalog.mdand updated all cross-references (inspect, overview, sys, mkdocs.yml)check-yamlpre-commit hook to support!!python/nametags in mkdocs.yml (--unsafe)🤖 Generated with Claude Code