quark-onnx-shapeshifter-run

Files (2)

• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

# quark-onnx-shapeshifter-run

## Purpose

Apply one or more **existing** ShapeShifter ONNX passes to an `.onnx` model by authoring a
ShapeShifter YAML config and running the `quark-cli shapeshifter` CLI. ShapeShifter is Quark's
pass-based graph-transformation framework; this skill covers *invoking* its built-in `onnx_*`
passes (fold BatchNorm, simplify, convert opset, fuse LayerNorm/GELU, align scales, XINT8/NPU
adaptation, etc.) as a standalone file→file transform — separate from authoring a new pass
(`quark-create-shapeshifter-pass`) and from a full quantization run (`quark-onnx-ptq`). It exists so
graph preprocessing/postprocessing can be run and inspected on its own, and so the driving YAML is
a reusable, reviewable artifact.

## Inputs

- **Required**: path to an `.onnx` model (optionally with an adjacent `.onnx_data` external-weights
  file).
- **Required**: the pass(es) to apply and their config keys. If the user names an effect ("fold
  batch norm") rather than a pass name, map it to the pass via the catalog in
  `docs/source/quark_shapeshifter_onnx_passes.rst`.
- **Required**: an output `.onnx` path.
- **Optional**: whether these are preprocessing (float model) or postprocessing (quantized Q/DQ
  model) passes — affects which passes are valid and the recommended order.

## Outputs: shapeshifter_config.yaml

The primary artifact is the ShapeShifter YAML config that drives the run — reusable and reviewable.
Side effect: the transformed model written to the user's output `.onnx` path.

```yaml
input_model_path: /path/to/model.onnx
passes:
  onnx_convert_opset_version:
    target_opset_version: 21
  onnx_simplify:
    simplify: true
  onnx_fold_batch_norm:
    fold_batch_norm: true
output_model_path: /path/to/model_out.onnx
```

No JSON schema — this is a ShapeShifter CLI config (see `quark/shapeshifter/utils.py`), not a
cross-skill contract artifact.

## Interaction Flow

1. **Intake** — confirm the input `.onnx` path exists, capture the requested transformation(s) and
   the output path. Map effect words to concrete pass names.
2. **Route** — verify every requested pass is an ONNX pass (`onnx_*`) and exists in
   `quark/shapeshifter/passes/`. If the user asked to *create* a pass, hand off to
   `quark-create-shapeshifter-pass`; if they asked to *quantize*, hand off to `quark-onnx-ptq`.
3. **Plan** — present the YAML config (pass order + config keys) before writing. Confirm the config
   key for each pass (many passes are a silent no-op without their enable flag — see Recovery).
4. **Confirm** — get approval before running the CLI (it writes the output file).
5. **Execute or Summarize** — write `shapeshifter_config.yaml`, run the CLI, then verify the output
   model loads and the transformation took effect. Summarize what changed.

## Invoking the CLI

Write the YAML (see Outputs), then:

```bash
quark-cli shapeshifter shapeshifter_config.yaml
```

The CLI loads the model, runs each pass **in the order listed** (each on the previous pass's
output), and writes `output_model_path`. JSON configs also work. An explicit model config is
equivalent to the flat form and clearer when in doubt:

```yaml
input_model_config:
  model_type: onnx        # discriminator
  input_model_path: /path/to/model.onnx
passes: { ... }
output_model_path: /path/to/model_out.onnx
```

## Pass Selection

Full catalog + config keys: `docs/source/quark_shapeshifter_onnx_passes.rst`. Common choices:

| Intent | Pass | Config key |
|--------|------|-----------|
| Constant-fold / clean graph | `onnx_simplify` | `simplify: true` |
| Upgrade opset | `onnx_convert_opset_version` | `target_opset_version: 21` |
| Fold BatchNorm into Conv/Gemm | `onnx_fold_batch_norm` | `fold_batch_norm: true` |
| Fuse LayerNorm / GELU | `onnx_fuse_layer_norm` / `onnx_fuse_gelu` | `fuse_layer_norm: true` / `fuse_gelu: true` |
| Layout NCHW→NHWC | `onnx_convert_nchw_to_nhwc` | `convert_nchw_to_nhwc: true` |
| Cross-layer equalization | `onnx_cross_layer_equalization` | `cross_layer_equalization: true` |
| Align Q/DQ scales (quantized) | `onnx_align_scale` | `align_scale: [Concat, MaxPool]` |
| XINT8/NPU adapt (quantized) | `onnx_xint8_adjust` / `onnx_xint8_simulate` | `xint8_adjust: true` / `xint8_simulate: true` |

**Preprocessing** passes run on the **float** model (before quantization); **postprocessing**
passes (`onnx_align_scale`, `onnx_adjust_bias_scale`, `onnx_xint8_*`, bfloat16 passes) expect a
**quantized Q/DQ** model. Do not run postprocessing passes on a float model.

**Ordering tip:** put opset conversion and `onnx_simplify` first (some fusions require a newer
opset and a cleaner graph), then folding/fusion, then per-node initializer passes.

## Relationship to quantization

If the goal is to run these passes **as part of** quantization rather than standalone, they can be
driven from the quantizer instead via `extra_options={"ShapeShifterYaml": "config.yaml"}` with
`preprocess_passes:` / `postprocess_passes:` groups — that path belongs to `quark-onnx-ptq`. Use
this skill only for the standalone file→file transform.

## Recovery

- **Pass ran but nothing changed (silent no-op)** — most passes require their enable flag; e.g.
  `onnx_convert_clip_to_relu` needs `convert_clip_to_relu: true`. A missing/`false` flag logs a
  warning and returns the model unchanged. Re-check the config key against the docs.
- **`Pass '<name>' is not registered`** — misspelled pass name or a `pytorch_*` name. List valid
  names with `ls quark/shapeshifter/passes/`; this skill is ONNX-only.
- **`ValueError: ... is not an ONNX pass`** — a `pytorch_*` pass slipped into the config. All passes
  in one run must be ONNX.
- **Postprocessing pass errors on a float model** — `onnx_align_scale` / `onnx_xint8_*` need a
  quantized Q/DQ model. Quantize first (`quark-onnx-ptq`), then apply.
- **CLI errors / onnxruntime traceback** — hand off to `quark-onnx-debug` with the exact message.
- **Output opset too low for a fusion** — `onnx_fuse_gelu` (opset ≥ 20) and `onnx_fuse_layer_norm`

From amd/Quark, MIT.

More from amd/Quark