AGENT SKILL

advanced-graph-control

Advanced graph-control workflows for ONNX Simplifier: custom rewriters, FunctionProto rules, metrics, graph diffs, metadata, and profiling.

License 许可
Apache-2.0
最近更新
2026-09-03
Stars
★ 351
Forks
27

01 前言 Front Matter

name
advanced-graph-control
license
Apache 2.0
metadata
{ "disco-role": "operating" }
description
Advanced graph-control workflows for ONNX Simplifier: custom rewriters, FunctionProto rules, metrics, graph diffs, metadata, and profiling.
disable-model-invocation
true

02 资源文件 5

03 SKILL.md 正文

advanced-graph-control

Use this sub-skill when the task is not just "simplify this ONNX model", but needs control over the simplification fixed point, graph rewrite rules, schema registration, graph inspection, model metrics, metadata annotations, or profiling traces.

Route first

  • Basic CLI/Python simplification, input shapes, correctness checks, providers, external data, target opset, constant folding, and ordinary optimizer skipping belong in sibling sub-skill path ../python-simplification/SKILL.md.
  • Python wheel/source builds, C API, Rust API, WASM/Node/npm, and binding build commands belong in sibling sub-skill path ../bindings-and-packaging/SKILL.md.
  • This sub-skill owns the semantics of FunctionProto rewrite rules; C/Rust users can use the same rule bytes, but binding-specific invocation belongs to the bindings sub-skill.

Primary references

Bundled smoke scripts

Run these from any environment where onnx and onnxsim are importable; they do not require the original repository checkout.

python scripts/function_rule_smoke.py --help
python scripts/function_rule_smoke.py
python scripts/model_metrics_smoke.py --help
python scripts/model_metrics_smoke.py
  • scripts/function_rule_smoke.py builds a tiny MatMul + Add model, applies a pure-data FunctionProto rule that rewrites it to Gemm, skips the built-in Gemm fusion so the rule is provably responsible, and asserts the rewritten graph contains Gemm.
  • scripts/model_metrics_smoke.py builds a tiny model, reports ModelInfo metrics, annotates metrics into metadata_props, and prints a compact graph-diff summary.

Workflow: custom Python rewriter

Use custom_rewriter= when the rewrite is Python-only or needs a richer matcher than onnxsim's built-in FunctionProto matcher.

  1. Build or load an onnx.ModelProto.
  2. Define a callable that accepts onnx.ModelProto and either:
    • returns a rewritten onnx.ModelProto,
    • mutates the input model in place and returns None, or
    • returns False when this fixed-point round changed nothing.
  3. Call onnxsim.simplify(model, custom_rewriter=callable, check_n=...).
  4. Validate both the ONNX checker and, when safe, check_n > 0.
  5. If a rewriter introduces custom-domain or newer-opset ops, register schemas or convert the model to the expected opset before simplification.

Prefer returning False on no-op rounds; it is the no-change sentinel that prevents unnecessary serialize/parse copies and helps the fixed point converge.

Workflow: binding-portable FunctionProto rule

Use function_rewrite_rules= when a rule can be expressed as pure ONNX graph data and should also be usable from C or Rust.

  1. Express a (pattern, replacement) pair as onnx.FunctionProto objects, usually with onnx.parser.parse_function.
  2. Treat pattern inputs as wildcards; pattern outputs are rewired to replacement outputs.
  3. Use @name / ref_attr_name for attribute wildcards that bind from the matched node and substitute into the replacement.
  4. Pass function_rewrite_rules=[(pattern, replacement)] to onnxsim.simplify.
  5. If a built-in optimizer would perform the same rewrite, pass skipped_optimizers=["that_optimizer"] while validating the rule itself.

custom_rewriter and function_rewrite_rules are mutually exclusive in one simplify() call.

Workflow: custom schemas

If the model contains custom ops that should remain schema-valid:

import onnx
import onnxsim

onnx.defs.register_schema(my_op_schema)
# simplify() imports registered schemas automatically by default.
model_simp, ok = onnxsim.simplify(model)

Call onnxsim.import_onnx_schemas() explicitly when you need an import count or want to prime the onnxsim registry. Disable the automatic import only when you know the model does not require Python-registered schemas: onnxsim.simplify(model, import_custom_schemas=False) or CLI --skip-schema-import.

Workflow: metrics, metadata, graph diff

Use onnxsim.model_info for static inspection without running inference:

from onnxsim.model_info import ModelInfo, annotate_metadata, diff_graphs

info = ModelInfo(model)
annotated = annotate_metadata(model)
diff = diff_graphs(original_model, simplified_model)

Metrics include operator counts, serialized model size, MACs, FLOPs, memory access, peak memory footprint, and compute density. Some values are symbolic when dynamic dimensions are named and sympy is installed; otherwise unresolved dimensions are best-effort lower bounds.

Workflow: profile simplification

Use profiling when a simplification is unexpectedly slow, memory-heavy, or when constant folding/optimizer cost attribution matters.

model_simp, ok = onnxsim.simplify(model, profile="profile.json")
model_simp, ok = onnxsim.simplify(model, ort_profile="ort_profile")
model_simp, ok = onnxsim.simplify(
    model, profile="profile.json", merge_ort_profile=True
)

CLI equivalents are --profile, --ort-profile, and --merge-ort-profile. Open Chrome trace JSON files in chrome://tracing or Perfetto. Use a scratch or user-selected output directory for traces; do not leave large trace files in a runtime skill directory.

Validation checklist

  • Run the bundled --help checks before relying on a script in a new environment.
  • For rewrite rules, assert the intended op counts and run onnx.checker.
  • For semantic rewrites, use check_n or explicit input_data; use check_n=0 only for structural or intentionally semantics-changing transformations.
  • For metrics, document whether dynamic shapes made values symbolic or lower bounds.
  • For profiling, confirm the expected trace files exist and that environment variables used for profiling are not unintentionally left set after the call.

04 同仓库更多 Skills

VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-triton-opt

Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-solve

END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-skill

PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-pattern-fusion

Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-orchestrate

Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.

★ 351
VectorSpaceLab
VectorSpaceLab/AREX-Skill

passnet-feedback

Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).

★ 351