Add ExecuTorch WebGPU program for dfine-small

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+dfine_s_coco_webgpu.pte filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE

@@ -0,0 +1,6 @@
+This repository contains a modified version of ustc-community/dfine-small-coco.
+
+Modifications by Meta Platforms, Inc.: conversion to the ExecuTorch program format (.pte) for the
+ExecuTorch WebGPU backend.
+
+The original work and these modifications are distributed under the license in LICENSE.

README.md

@@ -0,0 +1,100 @@
+---
+license: apache-2.0
+base_model:
+- ustc-community/dfine-small-coco
+library_name: executorch
+pipeline_tag: object-detection
+inference: false
+tags:
+- executorch
+- webgpu
+- on-device
+- browser
+---
+# D-FINE small object detection for ExecuTorch WebGPU
+
+This repository contains an [ExecuTorch](https://github.com/pytorch/executorch) conversion of
+[ustc-community/dfine-small-coco](https://huggingface.co/ustc-community/dfine-small-coco) for the ExecuTorch **WebGPU** backend, so the model runs entirely in a web browser on
+the visitor's GPU. It powers the corresponding demo in the ExecuTorch WebGPU Playground (launching soon on [executorch.ai](https://executorch.ai)).
+
+- **Base model:** [ustc-community/dfine-small-coco](https://huggingface.co/ustc-community/dfine-small-coco)
+- **Format:** ExecuTorch `.pte` programs delegated to the WebGPU backend
+- **Quantization:** fp32 (as exported)
+- **Total size:** 40.3 MB
+
+> **Note:** The weights are the Hugging Face transformers port of the authors' checkpoint; every tensor was checked to be bit-identical to the official `dfine_s_coco.pth` published by the first author (see Provenance and `export/verify_official.py`).
+
+## About the original model
+
+The small COCO model of D-FINE, a real-time DETR-style object detector that refines boxes as probability distributions.
+
+- **Developed by:** Yansong Peng et al. (USTC)
+- **Paper:** [D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement](https://arxiv.org/abs/2410.13842)
+- 10.3M parameters
+- Detects the 80 COCO object classes
+- No non-maximum suppression needed
+
+For training data, evaluation results and full details, see the original model card: [ustc-community/dfine-small-coco](https://huggingface.co/ustc-community/dfine-small-coco).
+
+## Intended use and limitations
+
+Detecting everyday objects in photos, video and camera frames.
+
+Only knows the 80 COCO classes. Small, unusual or heavily occluded objects are often missed, and confidence scores are not calibrated probabilities.
+
+## What changed in this conversion
+
+- Graph rewritten with output-preserving substitutions so it runs as a single WebGPU delegate (checked against upstream on a real image: boxes within 0.001 px)
+- Fixed 640x640 input; the 300 query outputs are filtered by score outside the program
+
+## Inputs and outputs
+
+- Input `[1, 3, 640, 640]` float32 RGB in [0, 1] (`x / 255`, no mean/std); letterboxed or plain-resized
+- Output `[1, 84, 300]` float32: rows 0-3 are box center x, center y, width, height in input pixels; rows 4-83 are sigmoid scores for the 80 COCO classes
+
+## Files
+
+| File | Size | SHA-256 |
+|---|---|---|
+| `dfine_s_coco_webgpu.pte` | 40.3 MB | `96cc65f615dc2c79…` |
+
+Full checksums are in `manifest.json`. The playground verifies them after download.
+
+## Running it
+
+These programs were exported with the ExecuTorch WebGPU backend
+([backends/webgpu](https://github.com/pytorch/executorch/tree/main/backends/webgpu)) and validated with the
+WebAssembly runtime build used by the ExecuTorch WebGPU Playground (launching soon on [executorch.ai](https://executorch.ai)). That runtime build is not published yet; until it is,
+the playground is the supported way to run them. It downloads these files once, caches them in the browser,
+and runs everything locally.
+
+Requirements: a browser with WebGPU enabled.
+
+## Provenance
+
+- **Weights:** `ustc-community/dfine-small-coco` @ `f79e65b5fbb33ceb9d3ebba042955d7410c608f8`, file `model.safetensors`, sha256 `a144baff3a27bfd538fe37b11fa8d4fca5744b8c054b5301e7c699a1379cd18f` (from a community mirror of the official release)
+- **Checked against the official checkpoint:** `Peterande/D-FINE` @ `19214e91f5ce4c1e609022c38b1fc953c47404e7`, file `dfine_s_coco.pth` (sha256 `48a6c8cc43eb57186843f752e2e8461ddd3326e0d3c575e71e6e960844683e89`): all 764 tensors bit-identical (verify_official.py)
+- **Exported with:** executorch 1.5.1+cpu, torch 2.14.1+cpu, torchao 0.18.0+cpu, transformers 5.19.0 (executorch git `3b6068392324`)
+- **Reproduce:** `python recipes/detector-dfine-small.py --out out/detector-dfine-small --image photo.jpg` (recipe in `export/`)
+- Re-running the recipe produces byte-identical files.
+
+## Citation
+
+If you use this model, please cite the original work:
+
+```bibtex
+@misc{peng2024dfine,
+  title={D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement},
+  author={Yansong Peng and Hebei Li and Peixi Wu and Yueyi Zhang and Xiaoyan Sun and Feng Wu},
+  year={2024},
+  eprint={2410.13842},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV}
+}
+```
+
+## License
+
+This is a derivative of the upstream model and is distributed under the same terms
+(`apache-2.0`); see `LICENSE`.
+Modifications (conversion to the ExecuTorch format) by Meta Platforms, Inc.

dfine_s_coco_webgpu.pte

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:96cc65f615dc2c79d1da80ef075b831fac8e39e8dcb58af9aff5bab154a4c4d6
+size 42260612

export/_common.py

@@ -0,0 +1,330 @@
+"""Shared helpers for the ExecuTorch WebGPU export recipes in this directory.
+
+Each recipe builds an eager model from a pinned upstream revision and calls
+`export_vision` (or its own LLM path), which writes:
+
+  <out>/<name>_webgpu.pte    program lowered with WebGPUPartitioner (delegate id "VulkanBackend")
+  <out>/<name>_portable.pte  same exported graph without a delegate, for CPU validation only
+  <out>/recipe.json          upstream id + revision, versions, shapes, dtype, command line
+  <out>/validation.json      eager vs exported-program vs portable .pte (and goldens, if given)
+"""
+
+import hashlib
+import io
+import json
+import platform
+import shlex
+import sys
+import urllib.request
+import zipfile
+from pathlib import Path
+
+import numpy as np
+import torch
+
+PROXY_HINT = (
+    "set https_proxy if the machine needs a proxy for huggingface.co / pypi.org"
+)
+
+
+def versions():
+    import executorch
+    import torchao
+    from executorch.version import git_version
+
+    out = {
+        "python": platform.python_version(),
+        "torch": torch.__version__,
+        "torchao": torchao.__version__,
+        "executorch": getattr(executorch, "__version__", None)
+        or __import__("executorch.version").version.__version__,
+        "executorch_git": git_version,
+    }
+    try:
+        import transformers
+
+        out["transformers"] = transformers.__version__
+    except ImportError:
+        pass
+    try:
+        import huggingface_hub
+
+        out["huggingface_hub"] = huggingface_hub.__version__
+    except ImportError:
+        pass
+    return out
+
+
+def sha256_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def hf_file(repo_id, filename, revision, expected_sha256=None, cache_dir=None):
+    from huggingface_hub import hf_hub_download
+
+    path = hf_hub_download(
+        repo_id=repo_id, filename=filename, revision=revision, cache_dir=cache_dir
+    )
+    digest = sha256_file(path)
+    if expected_sha256 and digest != expected_sha256:
+        sys.exit(
+            f"{repo_id}@{revision}:{filename} sha256 {digest} != {expected_sha256}"
+        )
+    return Path(path), digest
+
+
+def pypi_wheel_member(url, expected_sha256, member):
+    """Read one file out of a PyPI wheel, verifying the wheel's sha256."""
+    with urllib.request.urlopen(url, timeout=120) as resp:
+        blob = resp.read()
+    digest = hashlib.sha256(blob).hexdigest()
+    if digest != expected_sha256:
+        sys.exit(f"{url}: sha256 {digest} != {expected_sha256} ({PROXY_HINT})")
+    with zipfile.ZipFile(io.BytesIO(blob)) as zf:
+        return zf.read(member).decode()
+
+
+def scrub(text, out_dir):
+    """Replace machine-specific paths so recipe.json can ship with the model."""
+    text = text.replace(str(Path(out_dir).resolve()), "<out>")
+    text = text.replace(str(Path(__file__).resolve().parent), "recipes")
+    return text.replace(str(Path.home()), "~")
+
+
+def command_line(out_dir):
+    argv = [f"recipes/{Path(sys.argv[0]).name}", *sys.argv[1:]]
+    args = []
+    for a in argv:
+        if a.startswith("/") or a.startswith("."):
+            a = scrub(str(Path(a).resolve()), out_dir)
+        args.append(a)
+    return scrub(" ".join(["python", *(shlex.quote(a) for a in args)]), out_dir)
+
+
+def lower_webgpu(ep):
+    from executorch.backends.webgpu.partitioner import WebGPUPartitioner
+    from executorch.exir import to_edge_transform_and_lower
+
+    return to_edge_transform_and_lower(
+        ep, partitioner=[WebGPUPartitioner()]
+    ).to_executorch()
+
+
+def lower_portable(ep):
+    from executorch.exir import to_edge_transform_and_lower
+
+    return to_edge_transform_and_lower(ep).to_executorch()
+
+
+def delegate_summary(pte_bytes):
+    """Non-delegated kernels and per-delegate op histograms of a serialized program."""
+    import collections
+
+    from executorch.backends.vulkan.serialization.vulkan_graph_serialize import (
+        extract_vk_flatbuffer,
+        flatbuffer_to_vk_graph,
+    )
+    from executorch.exir._serialize._program import deserialize_pte_binary
+
+    pte = deserialize_pte_binary(pte_bytes)
+    prog = pte.program if hasattr(pte, "program") else pte
+    seg_base = int.from_bytes(pte_bytes[24:32], "little")
+    plan = prog.execution_plan[0]
+    ops = [f"{o.name}.{o.overload}" for o in plan.operators]
+    kernels = collections.Counter()
+    for chain in plan.chains:
+        for ins in chain.instructions:
+            if type(ins.instr_args).__name__ == "KernelCall":
+                kernels[ops[ins.instr_args.op_index]] += 1
+    delegates = []
+    for d in plan.delegates:
+        proc = d.processed
+        if proc.location.name == "INLINE":
+            blob = prog.backend_delegate_data[proc.index].data
+        else:
+            seg = prog.segments[proc.index]
+            blob = pte_bytes[seg_base + seg.offset : seg_base + seg.offset + seg.size]
+        g = flatbuffer_to_vk_graph(extract_vk_flatbuffer(blob))
+        delegates.append(
+            {
+                "id": d.id,
+                "ops": dict(collections.Counter(c.name for c in g.chain)),
+                "inputs": len(g.input_ids),
+                "outputs": len(g.output_ids),
+            }
+        )
+    return {"non_delegated_kernels": dict(kernels), "delegates": delegates}
+
+
+def compare(a, b):
+    a = np.asarray(a, dtype=np.float64).ravel()
+    b = np.asarray(b, dtype=np.float64).ravel()
+    n = min(a.size, b.size)
+    a, b = a[:n], b[:n]
+    cos = float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-30))
+    return {
+        "max_abs": float(np.max(np.abs(a - b))),
+        "mean_abs": float(np.mean(np.abs(a - b))),
+        "cosine": cos,
+    }
+
+
+def run_pte(pte_bytes, inputs):
+    from executorch.extension.pybindings.portable_lib import (
+        _load_for_executorch_from_buffer,
+    )
+
+    m = _load_for_executorch_from_buffer(pte_bytes)
+    return [
+        o.detach().numpy() if isinstance(o, torch.Tensor) else o
+        for o in m.forward(inputs)
+    ]
+
+
+def try_run_webgpu_pte_on_cpu(pte_bytes, inputs):
+    try:
+        return run_pte(pte_bytes, inputs), None
+    except Exception as e:  # noqa: BLE001 - the error text is the result
+        return None, f"{type(e).__name__}: {str(e).splitlines()[0][:300]}"
+
+
+def export_vision(
+    *,
+    name,
+    model,
+    example_input,
+    out_dir,
+    upstream,
+    extra_recipe,
+    golden=None,
+    output_index=None,
+):
+    """Export, lower, write both .pte files, recipe.json, and validation.json.
+
+    `golden` is an optional (input ndarray, output ndarray) pair; when its input
+    shape matches `example_input`, all paths are also compared against it.
+    `output_index` picks one tensor when the eager model returns a tuple.
+    """
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    torch.manual_seed(0)
+    model = model.eval()
+
+    class Wrapped(torch.nn.Module):
+        def __init__(self, m):
+            super().__init__()
+            self.m = m
+
+        def forward(self, x):
+            y = self.m(x)
+            return y[output_index] if output_index is not None else y
+
+    wrapped = Wrapped(model).eval()
+    with torch.no_grad():
+        ep = torch.export.export(wrapped, (example_input,), strict=False)
+        webgpu = lower_webgpu(ep)
+        portable = lower_portable(ep)
+
+    webgpu_path = out_dir / f"{name}_webgpu.pte"
+    portable_path = out_dir / f"{name}_portable.pte"
+    webgpu_path.write_bytes(webgpu.buffer)
+    portable_path.write_bytes(portable.buffer)
+
+    summary = delegate_summary(webgpu.buffer)
+    out_shape = list(ep.module()(example_input).shape)
+    recipe = {
+        "model": name,
+        "upstream": upstream,
+        "versions": versions(),
+        "export": {
+            "api": "torch.export.export(strict=False) -> to_edge_transform_and_lower(partitioner=[WebGPUPartitioner()]) -> to_executorch()",
+            "partitioner": "executorch.backends.webgpu.partitioner.WebGPUPartitioner() (default compile options; wraps VulkanPartitioner)",
+            "inputs": [
+                {
+                    "shape": list(example_input.shape),
+                    "dtype": "float32",
+                    "layout": "NCHW",
+                }
+            ],
+            "outputs": [{"shape": out_shape, "dtype": "float32"}],
+            "dtype": "float32",
+            "quantization": "none (fp32)",
+            **extra_recipe,
+        },
+        "files": {
+            webgpu_path.name: {
+                "bytes": webgpu_path.stat().st_size,
+                "sha256": sha256_file(webgpu_path),
+            },
+            portable_path.name: {
+                "bytes": portable_path.stat().st_size,
+                "sha256": sha256_file(portable_path),
+                "note": "CPU-only validation artifact (portable kernels, no delegate); not for release",
+            },
+        },
+        "graph": summary,
+        "command": command_line(out_dir),
+    }
+    (out_dir / "recipe.json").write_text(json.dumps(recipe, indent=2) + "\n")
+
+    # Validation on CPU.
+    gen = torch.Generator().manual_seed(1234)
+    rand_input = torch.rand(example_input.shape, generator=gen)
+    cases = {"random": rand_input}
+    if golden is not None and tuple(golden[0].shape) == tuple(example_input.shape):
+        cases["golden"] = torch.from_numpy(golden[0].copy())
+    report = {
+        "cpu_runtime": "executorch pybindings (portable_lib) from the pip wheel",
+        "cases": {},
+    }
+    webgpu_cpu_error = None
+    for label, x in cases.items():
+        with torch.no_grad():
+            eager = wrapped(x).numpy()
+            exported = ep.module()(x).numpy()
+        port = run_pte(portable.buffer, (x,))[0]
+        res = {
+            "exported_vs_eager": compare(exported, eager),
+            "portable_pte_vs_eager": compare(port, eager),
+        }
+        wg, err = try_run_webgpu_pte_on_cpu(webgpu.buffer, (x,))
+        if wg is not None:
+            res["webgpu_pte_vs_eager"] = compare(wg[0], eager)
+        else:
+            webgpu_cpu_error = err
+        if label == "golden":
+            ref = golden[1]
+            res["internal_golden_vs_eager"] = compare(eager, ref)
+            res["internal_golden_vs_portable_pte"] = compare(port, ref)
+            res["golden_note"] = (
+                "reference output from the internal goldens.manifest.json"
+            )
+        report["cases"][label] = res
+    report["webgpu_pte_on_cpu"] = (
+        "ran"
+        if webgpu_cpu_error is None
+        else f"not runnable on CPU pybindings: {webgpu_cpu_error}"
+    )
+    (out_dir / "validation.json").write_text(json.dumps(report, indent=2) + "\n")
+    print(
+        json.dumps(
+            {"recipe": recipe["files"], "graph": summary, "validation": report},
+            indent=2,
+        )
+    )
+    return ep, webgpu, portable
+
+
+def load_golden(manifest_path, key):
+    man = json.loads(Path(manifest_path).read_text())[key]["tensors"]
+    base = Path(manifest_path).parent
+
+    def ld(t):
+        return np.fromfile(base / t["file"], dtype=np.float32).reshape(t["shape"])
+
+    inp = man.get("input")
+    return ld(inp), ld(man["output"])

export/_detector.py

@@ -0,0 +1,299 @@
+"""Graph building blocks for exporting DETR-style detectors to the playground's WebGPU runtime.
+
+The playground's current `webgpu_forward.wasm` registers 63 operators and links no CPU kernels,
+so a program must be one delegate made only of those operators, with every elementwise tensor
+at rank <= 4. These helpers rewrite the pieces of RT-DETR / D-FINE that fall outside that set
+using only: add/sub/mul/div, relu, sigmoid, where.self, gt/ge/le/lt.Scalar, sum.dim,
+gather (fp32 self + int32 index), _to_copy (fp32 <-> int32), view/permute/expand/slice/cat.
+
+Each helper is exact (selection by comparison, integer arithmetic below 2^24) or an
+algebraic identity of the original op; see the docstrings.
+"""
+
+import torch
+
+
+def clamp(x, lo=None, hi=None):
+    """Exact clamp written with where + compare-against-0.
+
+    The current runtime's aten.clamp returns zeros for integer-valued bounds (the serializer
+    stores them as Int), so clamp is never emitted. Bounds are lifted [1] constants.
+    """
+    if lo is not None:
+        x = torch.where((x - lo) < 0, torch.tensor([float(lo)]), x)
+    if hi is not None:
+        x = torch.where((x - hi) > 0, torch.tensor([float(hi)]), x)
+    return x
+
+
+def where_max(a, b):
+    """Elementwise max(a, b), exact: picks b where b - a > 0 (a - b is never 0 for a != b)."""
+    return torch.where((b - a) > 0, b, a)
+
+
+def where_min(a, b):
+    return torch.where((b - a) < 0, b, a)
+
+
+def tree_reduce(x, pick):
+    """Reduce the last dim with a pairwise `pick` (where_max / where_min); keeps the dim (size 1)."""
+    while x.shape[-1] > 1:
+        n = x.shape[-1]
+        h = n // 2
+        m = pick(x[..., :h], x[..., h : 2 * h])
+        x = torch.cat([m, x[..., 2 * h :]], dim=-1) if n % 2 else m
+    return x
+
+
+class TopKSet(torch.nn.Module):
+    """Indices of the k largest entries of a [N] score vector, in ascending index order.
+
+    torch.topk is not available on the runtime. The detectors' decoders are permutation
+    equivariant over queries (self-attention with box-derived position embeddings, per-query
+    deformable cross-attention), so only the selected *set* matters, not its order.
+
+    1. Bisection for the k-th largest value t: `iters` steps of count(s >= mid) >= k.
+       After enough steps lo is the k-th largest value (unless another score lies within
+       (hi - lo) / 2^iters of it), so {s >= lo} is exactly the top-k set (ties aside).
+    2. Stream compaction: inclusive prefix count of the selection mask (two-level block cumsum
+       done with a triangular mask and sum, exact for integers), one-hot match of the
+       positions 0..k-1 with relu(1 - d^2), and index = sum(onehot * arange) (exact, < 2^24).
+    Returns a float tensor [k] of integer-valued indices.
+    """
+
+    def __init__(self, n, k, iters=48, block=None):
+        super().__init__()
+        self.n, self.k, self.iters = n, k, iters
+        if block is None:
+            block = next(b for b in range(int(n**0.5), 0, -1) if n % b == 0)
+        self.block = block
+        nb = n // block
+        self.nb = nb
+        self.register_buffer(
+            "tri_in", torch.tril(torch.ones(block, block)), persistent=False
+        )
+        self.register_buffer(
+            "tri_blk", torch.tril(torch.ones(nb, nb), diagonal=-1), persistent=False
+        )
+        self.register_buffer("one", torch.ones(1), persistent=False)
+        self.register_buffer("zero", torch.zeros(1), persistent=False)
+        self.register_buffer(
+            "slots", torch.arange(k, dtype=torch.float32).view(k, 1), persistent=False
+        )
+        self.register_buffer(
+            "arange", torch.arange(n, dtype=torch.float32).view(1, n), persistent=False
+        )
+
+    def forward(self, s):  # s: [1, N]
+        lo = tree_reduce(s, where_min) - 1.0  # [1, 1]
+        hi = tree_reduce(s, where_max) + 1.0
+        for _ in range(self.iters):
+            mid = (lo + hi) * 0.5
+            cnt = torch.where((s - mid) >= 0, self.one, self.zero).sum(
+                dim=-1, keepdim=True
+            )
+            ok = (cnt - self.k) >= 0
+            lo = torch.where(ok, mid, lo)
+            hi = torch.where(ok, hi, mid)
+        sel = torch.where((s - lo) >= 0, self.one, self.zero)  # [1, N]
+        blocks = sel.view(self.nb, 1, self.block)
+        within = (blocks * self.tri_in).sum(
+            dim=-1
+        )  # [nb, block] inclusive count in block
+        totals = blocks.sum(dim=-1).view(1, self.nb)  # [1, nb]
+        offsets = (
+            (totals * self.tri_blk).sum(dim=-1).view(self.nb, 1)
+        )  # exclusive block prefix
+        pos = (
+            sel * (within + offsets).view(1, self.n)
+        ) - 1.0  # selected -> 0.., others -> -1
+        d = pos - self.slots  # [k, N]
+        onehot = torch.relu(1.0 - d * d)
+        return (onehot * self.arange).sum(dim=-1)  # [k]
+
+
+def sigmoid_add_logit(delta, r, eps=1e-5):
+    """sigmoid(delta + inverse_sigmoid(r)) without log/exp.
+
+    With x = clamp(r, 0, 1), x1 = clamp(x, eps), x2 = clamp(1 - x, eps) (as in
+    inverse_sigmoid), sigmoid(delta + log(x1 / x2)) = x1 s / (x1 s + x2 (1 - s)) with
+    s = sigmoid(delta) and 1 - s = sigmoid(-delta).
+    """
+    x = clamp(r, 0.0, 1.0)
+    x1 = clamp(x, eps)
+    x2 = clamp(1.0 - x, eps)
+    a = x1 * torch.sigmoid(delta)
+    return a / (a + x2 * torch.sigmoid(-delta))
+
+
+class DeformSampler(torch.nn.Module):
+    """Multi-scale deformable attention core with bilinear grid_sample written as gathers.
+
+    Matches F.grid_sample(mode="bilinear", padding_mode="zeros", align_corners=False) on grid
+    g = 2 * loc - 1, pixel x = ((g + 1) * W - 1) / 2. floor() comes from an fp32 -> int32 cast of a
+    clamped, non-negative value; out-of-range corners get weight 0 through an integer mask
+    clamp(x0 + 1, 0, 1) * clamp(W - x0, 0, 1). Index clamping to [0, n-1] with a per-point n uses
+    min(i - (n - 1), 0) + (n - 1), exact on small integers (clamp.Tensor is not available).
+    All levels are concatenated along the spatial axis so one gather serves every
+    (level, point, corner).
+
+    points_per_level: number of sampling points per level, e.g. [6, 6] or [4, 4, 4].
+    shapes: [(H, W), ...] per level.
+    """
+
+    def __init__(self, shapes, points_per_level, heads, head_dim):
+        super().__init__()
+        self.heads, self.head_dim = heads, head_dim
+        self.P = sum(points_per_level)
+        self.L = sum(h * w for h, w in shapes)
+        Ws, Hs, starts = [], [], []
+        start = 0
+        for (h, w), p in zip(shapes, points_per_level):
+            Ws += [float(w)] * p
+            Hs += [float(h)] * p
+            starts += [float(start)] * p
+            start += h * w
+        self.wmax, self.hmax = max(Ws), max(Hs)
+        # Shaped [P, 1]: coordinates keep a trailing size-1 dim (slice, not select; the current
+        # runtime rejects a select index that the serializer stored as a Double).
+        self.register_buffer("W", torch.tensor(Ws).view(-1, 1), persistent=False)
+        self.register_buffer("H", torch.tensor(Hs).view(-1, 1), persistent=False)
+        self.register_buffer("start", torch.tensor(starts).view(-1, 1), persistent=False)
+
+    def forward(self, value, loc, attn):
+        """value [L, heads, head_dim]; loc [Q, heads, P, 2] in [0, 1]; attn [Q, heads, P].
+
+        Returns [Q, heads * head_dim].
+        """
+        Q = loc.shape[0]
+        nh, hd, P = self.heads, self.head_dim, self.P
+        loc = loc.permute(1, 0, 2, 3)  # [heads, Q, P, 2]
+        W, H = self.W, self.H
+        # Same arithmetic as grid_sampler's unnormalize on grid = 2 * loc - 1.
+        x = ((loc[..., 0:1] * 2.0 - 1.0 + 1.0) * W - 1.0) / 2.0  # [heads, Q, P, 1]
+        y = ((loc[..., 1:2] * 2.0 - 1.0 + 1.0) * H - 1.0) / 2.0
+        # trunc == floor once x + 1 >= 0. A point left of -1 or right of the level's W has
+        # both corners outside, so clamping to [-1, max W] cannot change the result.
+        x = clamp(x, -1.0, self.wmax)
+        y = clamp(y, -1.0, self.hmax)
+        x0 = (x + 1.0).to(torch.int32).to(torch.float32) - 1.0  # floor: x + 1 >= 0
+        y0 = (y + 1.0).to(torch.int32).to(torch.float32) - 1.0
+        fx = x - x0
+        fy = y - y0
+        x1 = x0 + 1.0
+        y1 = y0 + 1.0
+
+        def inside(i, n):
+            return clamp(i + 1.0, 0.0, 1.0) * clamp(n - i, 0.0, 1.0)
+
+        def clampi(i, n):
+            return clamp(clamp(i, 0.0) - (n - 1.0), None, 0.0) + (n - 1.0)
+
+        mx0, mx1, my0, my1 = inside(x0, W), inside(x1, W), inside(y0, H), inside(y1, H)
+        cx0, cx1 = clampi(x0, W), clampi(x1, W)
+        ry0 = clampi(y0, H) * W + self.start
+        ry1 = clampi(y1, H) * W + self.start
+        a = attn.permute(1, 0, 2).reshape(nh, Q, P, 1)
+        w00 = (1.0 - fx) * (1.0 - fy) * mx0 * my0 * a
+        w01 = fx * (1.0 - fy) * mx1 * my0 * a
+        w10 = (1.0 - fx) * fy * mx0 * my1 * a
+        w11 = fx * fy * mx1 * my1 * a
+        idx = torch.cat([ry0 + cx0, ry0 + cx1, ry1 + cx0, ry1 + cx1], dim=-1)  # [heads, Q, P, 4]
+        wts = torch.cat([w00, w01, w10, w11], dim=-1)
+        K = Q * P * 4
+        idx = idx.reshape(nh, 1, K).expand(nh, hd, K).to(torch.int64)
+        v = value.permute(1, 2, 0)  # [heads, head_dim, L]
+        g = torch.gather(v, 2, idx)  # [heads, head_dim, K]
+        out = (
+            (g * wts.reshape(nh, 1, K)).reshape(nh, hd, Q, P * 4).sum(dim=-1)
+        )  # [heads, hd, Q]
+        return out.permute(2, 0, 1).reshape(Q, nh * hd)
+
+
+def attention(q_proj, k_proj, v_proj, o_proj, hidden, pos, heads):
+    """Self-attention with position embeddings on queries/keys (DETR style). hidden [1, N, C]."""
+    n, c = hidden.shape[1], hidden.shape[2]
+    hd = c // heads
+    qk_in = hidden + pos
+    q = q_proj(qk_in).view(n, heads, hd).permute(1, 0, 2)
+    k = k_proj(qk_in).view(n, heads, hd).permute(1, 2, 0)
+    v = v_proj(hidden).view(n, heads, hd).permute(1, 0, 2)
+    w = torch.softmax(torch.bmm(q, k) * (hd**-0.5), dim=-1)
+    o = torch.bmm(w, v).permute(1, 0, 2).reshape(1, n, c)
+    return o_proj(o)
+
+
+class SiLU(torch.nn.Module):
+    def forward(self, x):
+        return x * torch.sigmoid(x)
+
+
+class FoldedBatchNorm(torch.nn.Module):
+    """x * scale + shift with the frozen-BN scale/shift precomputed exactly as the module does."""
+
+    def __init__(self, weight, bias, mean, var, eps):
+        super().__init__()
+        scale = weight * (var + eps).rsqrt()
+        self.register_buffer("scale", scale.reshape(1, -1, 1, 1))
+        self.register_buffer("shift", (bias - mean * scale).reshape(1, -1, 1, 1))
+
+    def forward(self, x):
+        return x * self.scale + self.shift
+
+
+def fold_frozen_bn_into_conv(root, bn_class):
+    """For every module with `.convolution` + frozen-BN `.normalization`, fold the BN into the conv.
+
+    Used where a conv output is too large for the runtime's 1D elementwise dispatch limit
+    (~4.2M elements): folded, the following ReLU fuses into et_vk.conv_with_clamp.
+    """
+    n = 0
+    for m in root.modules():
+        conv, bn = getattr(m, "convolution", None), getattr(m, "normalization", None)
+        if isinstance(conv, torch.nn.Conv2d) and isinstance(bn, bn_class):
+            scale = bn.weight * (bn.running_var + 1e-5).rsqrt()
+            shift = bn.bias - bn.running_mean * scale
+            with torch.no_grad():
+                conv.weight.mul_(scale.view(-1, 1, 1, 1))
+                bias = shift if conv.bias is None else conv.bias * scale + shift
+                conv.bias = torch.nn.Parameter(bias.clone())
+            m.normalization = torch.nn.Identity()
+            n += 1
+    return n
+
+
+def relabel_golden(out_dir, note):
+    """_common.export_vision labels its reference case as the internal goldens; here it is upstream eager."""
+    import json
+    from pathlib import Path
+
+    p = Path(out_dir) / "validation.json"
+    v = json.loads(p.read_text())
+    if "golden" in v["cases"]:
+        v["cases"]["golden"]["golden_note"] = note
+    p.write_text(json.dumps(v, indent=2) + "\n")
+
+
+def replace_modules(root, predicate, factory):
+    n = 0
+    for parent in list(root.modules()):
+        for name, child in list(parent.named_children()):
+            if predicate(child):
+                setattr(parent, name, factory(child))
+                n += 1
+    return n
+
+
+def yolo_layout_buf(boxes_cxcywh, scores, pix_scale):
+    """Like yolo_layout, with the [w, h, w, h] scale passed in as a registered buffer."""
+    return torch.cat([boxes_cxcywh * pix_scale, scores], dim=-1).permute(0, 2, 1)
+
+
+def yolo_layout(boxes_cxcywh, scores, size):
+    """[1, Q, 4] normalized boxes + [1, Q, C] probabilities -> [1, 4 + C, Q] in input pixels.
+
+    The layout the playground's YOLO decoder (src/vision/detect.js) already reads.
+    """
+    w, h = size
+    scale = torch.tensor([w, h, w, h], dtype=torch.float32)
+    return torch.cat([boxes_cxcywh * scale, scores], dim=-1).permute(0, 2, 1)

export/detector-dfine-small.py

@@ -0,0 +1,424 @@
+#!/usr/bin/env python3
+"""D-FINE small (COCO, Apache-2.0) -> ExecuTorch WebGPU, for the playground's current forward runtime.
+
+Upstream: HF transformers port `ustc-community/dfine-small-coco` (Peterande/D-FINE, D-FINE-S). Every tensor in
+it is bit-identical to the authors' `dfine_s_coco.pth` on `Peterande/D-FINE` (see verify_official.py).
+
+Input:  [1, 3, 640, 640] float32 RGB in [0, 1] (image / 255; the HF processor does no mean/std).
+        Upstream resizes to 640x640 without keeping aspect; a letterboxed input also works.
+Output: [1, 84, 300] float32, the YOLO layout src/vision/detect.js reads: rows 0-3 are
+        cx, cy, w, h in input pixels, rows 4-83 are sigmoid class probabilities (80 COCO classes,
+        contiguous ids, same order as the YOLO head). 300 queries; no NMS needed (DETR).
+
+The eager graph is rebuilt from the HF modules with output-preserving rewrites so that the
+whole program is one delegate made of operators the current runtime registers
+(see _detector.py): topk -> TopKSet (same query set; queries come out in anchor order, and the
+decoder is permutation equivariant), grid_sample -> gathers, inverse_sigmoid/log -> identity,
+LQE top-4 -> rank-based selection, max over classes -> exact where-tree, SiLU -> x * sigmoid(x),
+frozen BN -> precomputed scale/shift, position embedding and anchors -> constants.
+"""
+
+import argparse
+import copy
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import _common  # noqa: E402
+import _detector as D  # noqa: E402
+
+UPSTREAM = {
+    "repo": "ustc-community/dfine-small-coco",
+    "revision": "f79e65b5fbb33ceb9d3ebba042955d7410c608f8",
+    "files": {
+        "model.safetensors": "a144baff3a27bfd538fe37b11fa8d4fca5744b8c054b5301e7c699a1379cd18f",
+    },
+    "license": "Apache-2.0",
+}
+OFFICIAL = {
+    "repo": "Peterande/D-FINE",
+    "revision": "19214e91f5ce4c1e609022c38b1fc953c47404e7",
+    "file": "dfine_s_coco.pth",
+    "sha256": "48a6c8cc43eb57186843f752e2e8461ddd3326e0d3c575e71e6e960844683e89",
+    "result": "all 764 tensors bit-identical (verify_official.py)",
+}
+SIZE = 640
+
+
+def load_hf():
+    from transformers import DFineForObjectDetection
+
+    path, digest = _common.hf_file(
+        UPSTREAM["repo"],
+        "model.safetensors",
+        UPSTREAM["revision"],
+        UPSTREAM["files"]["model.safetensors"],
+    )
+    m = DFineForObjectDetection.from_pretrained(
+        UPSTREAM["repo"], revision=UPSTREAM["revision"], attn_implementation="eager"
+    ).eval()
+    return m, digest
+
+
+class DFineStatic(torch.nn.Module):
+    def __init__(self, hf, size=SIZE):
+        super().__init__()
+        cfg = hf.config
+        self.cfg = cfg
+        mdl = hf.model
+        self.backbone = mdl.backbone.model
+        from transformers.models.d_fine.modeling_d_fine import DFineFrozenBatchNorm2d
+
+        D.replace_modules(
+            self.backbone,
+            lambda c: isinstance(c, DFineFrozenBatchNorm2d),
+            lambda c: D.FoldedBatchNorm(
+                c.weight, c.bias, c.running_mean, c.running_var, 1e-5
+            ),
+        )
+        self.encoder_input_proj = mdl.encoder_input_proj
+        self.encoder = mdl.encoder
+        D.replace_modules(
+            self,
+            lambda c: type(c).__name__ in ("SiLUActivation", "SiLU"),
+            lambda c: D.SiLU(),
+        )
+        self.decoder_input_proj = mdl.decoder_input_proj
+        self.enc_output = mdl.enc_output
+        self.enc_score_head = mdl.enc_score_head
+        self.enc_bbox_head = mdl.enc_bbox_head
+        self.decoder = mdl.decoder
+        self.class_embed = hf.class_embed
+        self.bbox_embed = hf.bbox_embed
+
+        strides = cfg.feat_strides
+        self.shapes = [(size // s, size // s) for s in strides]
+        for _ in range(cfg.num_feature_levels - len(strides)):
+            h, w = self.shapes[-1]
+            self.shapes.append(((h + 1) // 2, (w + 1) // 2))
+        n = sum(h * w for h, w in self.shapes)
+        anchors, valid = mdl.generate_anchors(
+            tuple(self.shapes), device="cpu", dtype=torch.float32
+        )
+        self.register_buffer("anchors", anchors.clone(), persistent=False)
+        self.register_buffer("valid", valid.to(torch.float32).clone(), persistent=False)
+        aifi_hw = self.shapes[cfg.encode_proj_layers[0]]
+        from transformers.models.d_fine.modeling_d_fine import (
+            build_2d_sinusoidal_position_embedding,
+        )
+
+        pos = build_2d_sinusoidal_position_embedding(
+            aifi_hw[0],
+            aifi_hw[1],
+            cfg.encoder_hidden_dim,
+            cfg.positional_encoding_temperature,
+        )
+        self.register_buffer(
+            "aifi_pos", pos.unsqueeze(0).to(torch.float32), persistent=False
+        )
+        from transformers.models.d_fine.modeling_d_fine import weighting_function
+
+        with torch.no_grad():
+            project = weighting_function(
+                cfg.max_num_bins, self.decoder.up, self.decoder.reg_scale
+            )
+        self.register_buffer(
+            "project", project.reshape(1, -1).clone(), persistent=False
+        )
+        self.reg_scale = float(self.decoder.reg_scale.item())
+        self.topk = D.TopKSet(n, cfg.num_queries)
+        self.sampler = D.DeformSampler(
+            self.shapes,
+            list(self.decoder.layers[0].encoder_attn.num_points_list),
+            cfg.decoder_attention_heads,
+            cfg.d_model // cfg.decoder_attention_heads,
+        )
+        self.register_buffer(
+            "pix_scale",
+            torch.tensor([size, size, size, size], dtype=torch.float32),
+            persistent=False,
+        )
+        self.register_buffer("one", torch.ones(1), persistent=False)
+        self.register_buffer("two", torch.full((1,), 2.0), persistent=False)
+        self.register_buffer("zero", torch.zeros(1), persistent=False)
+
+    # ---- encoder -------------------------------------------------------------------------
+    def aifi(self, x):
+        cfg = self.cfg
+        b, c, h, w = x.shape
+        hs = x.flatten(2).permute(0, 2, 1)
+        for layer in self.encoder.aifi[0].layers:
+            a = layer.self_attn
+            att = D.attention(
+                a.q_proj,
+                a.k_proj,
+                a.v_proj,
+                a.o_proj,
+                hs,
+                self.aifi_pos,
+                cfg.encoder_attention_heads,
+            )
+            hs = layer.self_attn_layer_norm(hs + att)
+            hs = layer.final_layer_norm(hs + layer.mlp(hs))
+        return hs.permute(0, 2, 1).reshape(b, c, h, w)
+
+    def run_encoder(self, feats):
+        enc = self.encoder
+        feats = list(feats)
+        idx = self.cfg.encode_proj_layers[0]
+        feats[idx] = self.aifi(feats[idx])
+        fpn = [feats[-1]]
+        for i, (lat, blk) in enumerate(zip(enc.lateral_convs, enc.fpn_blocks)):
+            back = feats[enc.num_fpn_stages - i - 1]
+            top = lat(fpn[-1])
+            fpn[-1] = top
+            top = F.interpolate(top, scale_factor=2.0, mode="nearest")
+            fpn.append(blk(torch.cat([top, back], dim=1)))
+        fpn.reverse()
+        pan = [fpn[0]]
+        for i, (down, blk) in enumerate(zip(enc.downsample_convs, enc.pan_blocks)):
+            pan.append(blk(torch.cat([down(pan[-1]), fpn[i + 1]], dim=1)))
+        return pan
+
+    # ---- decoder -------------------------------------------------------------------------
+    def deform(self, attn_mod, hidden, ref, value):
+        """hidden [1, Q, C]; ref [1, Q, 4]; value [L, heads, hd]."""
+        cfg = self.cfg
+        q = hidden.shape[1]
+        nh = cfg.decoder_attention_heads
+        P = sum(attn_mod.num_points_list)
+        off = attn_mod.sampling_offsets(hidden).view(q, nh, P, 2)
+        aw = torch.softmax(attn_mod.attention_weights(hidden).view(q, nh, P), dim=-1)
+        scale = attn_mod.num_points_scale.view(1, 1, P, 1)
+        r = ref.view(q, 1, 1, 4)
+        loc = r[..., :2] + off * scale * r[..., 2:] * attn_mod.offset_scale
+        out = self.sampler(value, loc, aw).view(1, q, cfg.d_model)
+        return out
+
+    def decoder_layer(self, layer, hs, pos, ref, value):
+        cfg = self.cfg
+        a = layer.self_attn
+        att = D.attention(
+            a.q_proj, a.k_proj, a.v_proj, a.o_proj, hs, pos, cfg.decoder_attention_heads
+        )
+        hs = layer.self_attn_layer_norm(hs + att)
+        cross = self.deform(layer.encoder_attn, hs + pos, ref, value)
+        hs = layer.gateway(hs, cross)
+        hs = hs + layer.mlp(hs)
+        return layer.final_layer_norm(D.clamp(hs, -65504.0, 65504.0))
+
+    def integral(self, corners):
+        q = corners.shape[1]
+        p = torch.softmax(corners.reshape(q * 4, self.cfg.max_num_bins + 1), dim=-1)
+        return F.linear(p, self.project).reshape(1, q, 4)
+
+    def distance2bbox(self, pts, dist):
+        rs = self.reg_scale
+        cx, cy, w, h = pts[..., 0:1], pts[..., 1:2], pts[..., 2:3], pts[..., 3:4]
+        x0 = cx - (0.5 * rs + dist[..., 0:1]) * (w / rs)
+        y0 = cy - (0.5 * rs + dist[..., 1:2]) * (h / rs)
+        x1 = cx + (0.5 * rs + dist[..., 2:3]) * (w / rs)
+        y1 = cy + (0.5 * rs + dist[..., 3:4]) * (h / rs)
+        return torch.cat([(x0 + x1) / 2, (y0 + y1) / 2, x1 - x0, y1 - y0], dim=-1)
+
+    def lqe(self, lqe_mod, scores, corners):
+        q = corners.shape[1]
+        nb = self.cfg.max_num_bins + 1
+        k = self.cfg.top_prob_values
+        prob = torch.softmax(corners.reshape(q * 4, nb), dim=-1)  # [R, nb]
+        diff = prob.view(q * 4, 1, nb) - prob.view(
+            q * 4, nb, 1
+        )  # [R, j, l] = p_l - p_j
+        greater = torch.where(diff > 0, self.one, self.zero).sum(dim=-1)  # [R, nb]
+        tops = []
+        for i in range(k):
+            masked = torch.where(greater <= i, prob, self.two)
+            tops.append(D.tree_reduce(masked, D.where_min))  # i-th largest value
+        top = torch.cat(tops, dim=-1)
+        stat = torch.cat([top, top.mean(dim=-1, keepdim=True)], dim=-1).reshape(
+            1, q, 4 * (k + 1)
+        )
+        return scores + lqe_mod.reg_conf(stat)
+
+    def forward(self, pixel_values):
+        cfg = self.cfg
+        feats = self.backbone(pixel_values).feature_maps
+        proj = [self.encoder_input_proj[i](f) for i, f in enumerate(feats)]
+        enc = self.run_encoder(proj)
+        sources = [self.decoder_input_proj[i](s) for i, s in enumerate(enc)]
+        for i in range(len(sources), cfg.num_feature_levels):
+            sources.append(self.decoder_input_proj[i](enc[-1]))
+        flat = torch.cat(
+            [s.flatten(2).permute(0, 2, 1) for s in sources], dim=1
+        )  # [1, L, C]
+        L = flat.shape[1]
+
+        memory = self.valid * flat
+        out_mem = self.enc_output(memory)
+        cls = self.enc_score_head(out_mem)  # [1, L, 80]
+        coord = self.enc_bbox_head(out_mem) + self.anchors  # [1, L, 4]
+        best = D.tree_reduce(cls, D.where_max).view(1, L)
+        idx = self.topk(best)  # [Q] float, ascending anchor order
+        Q = cfg.num_queries
+        idx_c = idx.view(1, Q, 1).expand(1, Q, cfg.d_model).to(torch.int64)
+        target = torch.gather(out_mem, 1, idx_c)
+        idx_4 = idx.view(1, Q, 1).expand(1, Q, 4).to(torch.int64)
+        ref_unact = torch.gather(coord, 1, idx_4)
+
+        nh = cfg.decoder_attention_heads
+        value = flat.view(L, nh, cfg.d_model // nh)
+        dec = self.decoder
+        hs = target
+        ref = torch.sigmoid(ref_unact)
+        out_detach = None
+        corners_prev = None
+        ref_initial = None
+        for i, layer in enumerate(dec.layers):
+            pos = D.clamp(dec.query_pos_head(ref), -10.0, 10.0)
+            hs = self.decoder_layer(layer, hs, pos, ref, value)
+            if i == 0:
+                ref_initial = D.sigmoid_add_logit(dec.pre_bbox_head(hs), ref)
+            if out_detach is None:
+                corners = self.bbox_embed[i](hs)
+            else:
+                corners = self.bbox_embed[i](hs + out_detach) + corners_prev
+            box = self.distance2bbox(ref_initial, self.integral(corners))
+            corners_prev = corners
+            ref = box
+            out_detach = hs
+        last = len(dec.layers) - 1
+        scores = self.class_embed[last](hs)
+        scores = self.lqe(dec.lqe_layers[last], scores, corners)
+        return D.yolo_layout_buf(box, torch.sigmoid(scores), self.pix_scale)
+
+
+# ---------------------------------------------------------------------------------------------
+def hf_reference(hf, x):
+    """HF eager outputs in the same layout, with queries permuted to ascending anchor order."""
+    with torch.no_grad():
+        o = hf(pixel_values=x)
+    order = torch.topk(
+        o.enc_outputs_class.max(-1).values, hf.config.num_queries, dim=1
+    ).indices[0]
+    perm = torch.argsort(order)
+    boxes = o.pred_boxes[:, perm]
+    probs = torch.sigmoid(o.logits[:, perm])
+    return torch.cat([boxes * SIZE, probs], dim=-1).permute(0, 2, 1).numpy(), order
+
+
+def load_image(path, size=SIZE):
+    from PIL import Image
+
+    img = Image.open(path).convert("RGB").resize((size, size), Image.BILINEAR)
+    a = np.asarray(img, dtype=np.float32) / 255.0
+    return torch.from_numpy(a.transpose(2, 0, 1).copy()).unsqueeze(0)
+
+
+def top_detections(out, thr=0.4):
+    out = np.asarray(out)[0]
+    probs = out[4:]
+    cls = probs.argmax(0)
+    sc = probs.max(0)
+    keep = np.argsort(-sc)
+    res = []
+    for q in keep:
+        if sc[q] < thr:
+            break
+        cx, cy, w, h = out[:4, q]
+        res.append(
+            (
+                int(cls[q]),
+                round(float(sc[q]), 3),
+                [
+                    round(float(v), 1)
+                    for v in (cx - w / 2, cy - h / 2, cx + w / 2, cy + h / 2)
+                ],
+            )
+        )
+    return res
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--out", required=True)
+    ap.add_argument(
+        "--image",
+        required=True,
+        help="any RGB photo; the rewritten graph is checked against upstream eager on it",
+    )
+    args = ap.parse_args()
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+
+    hf, digest = load_hf()
+    model = DFineStatic(copy.deepcopy(hf)).eval()
+    img = load_image(args.image)
+
+    # Output-preservation check of the rewritten eager graph against HF eager, real image.
+    ref, order = hf_reference(hf, img)
+    with torch.no_grad():
+        mine = model(img).numpy()
+    parity = {
+        "image": Path(args.image).name,
+        "rewritten_eager_vs_hf_eager": _common.compare(mine, ref),
+    }
+    parity["rewritten_eager_vs_hf_eager"]["max_abs_boxes_px"] = float(
+        np.abs(mine[:, :4] - ref[:, :4]).max()
+    )
+    parity["rewritten_eager_vs_hf_eager"]["max_abs_probs"] = float(
+        np.abs(mine[:, 4:] - ref[:, 4:]).max()
+    )
+    parity["detections_hf"] = top_detections(ref)
+    parity["detections_rewritten"] = top_detections(mine)
+    print(json.dumps(parity, indent=1))
+
+    ep, webgpu, portable = _common.export_vision(
+        name="dfine_s_coco",
+        model=model,
+        example_input=img,
+        out_dir=out,
+        upstream={
+            "model": "D-FINE-S (COCO), HF transformers port",
+            "weights": {
+                "repo": UPSTREAM["repo"],
+                "revision": UPSTREAM["revision"],
+                "file": "model.safetensors",
+                "sha256": digest,
+                "verified_against": OFFICIAL,
+            },
+            "license": UPSTREAM["license"],
+        },
+        extra_recipe={
+            "preprocessing_outside_graph": "RGB resize to 640x640 (letterbox also works), / 255; no mean/std",
+            "postprocessing_outside_graph": "output [1, 84, 300]: cx, cy, w, h (input px) + 80 sigmoid probs; threshold; NMS optional",
+            "rewrites": "see recipes/detector-dfine-small.py docstring and recipes/_detector.py",
+        },
+        golden=(img.numpy(), ref),
+    )
+    # Real-image check of the exported paths as well.
+    D.relabel_golden(
+        out,
+        "internal_golden_* here = upstream HF transformers eager output on the real image (same layout; DETR queries permuted to anchor order)",
+    )
+    port = _common.run_pte(portable.buffer, (img,))[0]
+    parity["portable_pte_vs_hf_eager"] = _common.compare(port, ref)
+    parity["portable_pte_vs_rewritten_eager"] = _common.compare(port, mine)
+    parity["detections_portable_pte"] = top_detections(port)
+    (out / "hf_parity.json").write_text(json.dumps(parity, indent=1) + "\n")
+    np.save(out / "cpu_eager_out.npy", mine)
+    img.numpy().astype(np.float32).tofile(out / "input_640.f32")
+    print(
+        json.dumps(
+            {k: v for k, v in parity.items() if not k.startswith("detections")},
+            indent=1,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

export/recipe.json

@@ -0,0 +1,119 @@
+{
+  "model": "dfine_s_coco",
+  "upstream": {
+    "model": "D-FINE-S (COCO), HF transformers port",
+    "weights": {
+      "repo": "ustc-community/dfine-small-coco",
+      "revision": "f79e65b5fbb33ceb9d3ebba042955d7410c608f8",
+      "file": "model.safetensors",
+      "sha256": "a144baff3a27bfd538fe37b11fa8d4fca5744b8c054b5301e7c699a1379cd18f",
+      "verified_against": {
+        "repo": "Peterande/D-FINE",
+        "revision": "19214e91f5ce4c1e609022c38b1fc953c47404e7",
+        "file": "dfine_s_coco.pth",
+        "sha256": "48a6c8cc43eb57186843f752e2e8461ddd3326e0d3c575e71e6e960844683e89",
+        "result": "all 764 tensors bit-identical (verify_official.py)"
+      }
+    },
+    "license": "Apache-2.0"
+  },
+  "versions": {
+    "python": "3.12.15+meta",
+    "torch": "2.14.1+cpu",
+    "torchao": "0.18.0+cpu",
+    "executorch": "1.5.1+cpu",
+    "executorch_git": "3b60683923245cf472b7323426920e15623ba361",
+    "transformers": "5.19.0",
+    "huggingface_hub": "2.2.0"
+  },
+  "export": {
+    "api": "torch.export.export(strict=False) -> to_edge_transform_and_lower(partitioner=[WebGPUPartitioner()]) -> to_executorch()",
+    "partitioner": "executorch.backends.webgpu.partitioner.WebGPUPartitioner() (default compile options; wraps VulkanPartitioner)",
+    "inputs": [
+      {
+        "shape": [
+          1,
+          3,
+          640,
+          640
+        ],
+        "dtype": "float32",
+        "layout": "NCHW"
+      }
+    ],
+    "outputs": [
+      {
+        "shape": [
+          1,
+          84,
+          300
+        ],
+        "dtype": "float32"
+      }
+    ],
+    "dtype": "float32",
+    "quantization": "none (fp32)",
+    "preprocessing_outside_graph": "RGB resize to 640x640 (letterbox also works), / 255; no mean/std",
+    "postprocessing_outside_graph": "output [1, 84, 300]: cx, cy, w, h (input px) + 80 sigmoid probs; threshold; NMS optional",
+    "rewrites": "see recipes/detector-dfine-small.py docstring and recipes/_detector.py"
+  },
+  "files": {
+    "dfine_s_coco_webgpu.pte": {
+      "bytes": 42260612,
+      "sha256": "96cc65f615dc2c79d1da80ef075b831fac8e39e8dcb58af9aff5bab154a4c4d6"
+    },
+    "dfine_s_coco_portable.pte": {
+      "bytes": 42299640,
+      "sha256": "f36da046a83ee72fe4083e61253e6ae5dc52d843ba38faaf73fb10ecd29da8ac",
+      "note": "CPU-only validation artifact (portable kernels, no delegate); not for release"
+    }
+  },
+  "graph": {
+    "non_delegated_kernels": {},
+    "delegates": [
+      {
+        "id": "VulkanBackend",
+        "ops": {
+          "et_vk.prepack.default": 603,
+          "aten.convolution.default": 99,
+          "aten.mul.Tensor": 281,
+          "aten.add.Tensor": 254,
+          "aten.relu.default": 48,
+          "aten.constant_pad_nd.default": 2,
+          "aten.max_pool2d_with_indices.default": 1,
+          "aten.cat.default": 66,
+          "aten.clone.default": 5,
+          "aten.view_copy.default": 110,
+          "aten.permute_copy.default": 37,
+          "aten.expand_copy.default": 8,
+          "aten.bmm.default": 11,
+          "aten._softmax.default": 11,
+          "aten.linear.default": 59,
+          "aten.native_layer_norm.default": 12,
+          "aten.squeeze_copy.dims": 33,
+          "aten.gelu.default": 1,
+          "aten.upsample_nearest2d.vec": 2,
+          "aten.sigmoid.default": 47,
+          "aten.split_with_sizes_copy.default": 7,
+          "aten.slice_copy.Tensor": 190,
+          "aten.sub.Tensor": 358,
+          "aten.gt.Scalar": 71,
+          "aten.where.self": 308,
+          "aten.lt.Scalar": 89,
+          "aten.ge.Scalar": 97,
+          "aten.sum.dim_IntList": 56,
+          "dim_order_ops._to_dim_order_copy.default": 71,
+          "aten.unsqueeze_copy.default": 6,
+          "aten.gather.default": 5,
+          "aten.div.Tensor": 25,
+          "aten.neg.default": 1,
+          "aten.le.Scalar": 4,
+          "aten.mean.dim": 1
+        },
+        "inputs": 1,
+        "outputs": 1
+      }
+    ]
+  },
+  "command": "python recipes/detector-dfine-small.py --out out/detector-dfine-small --image photo.jpg"
+}

export/requirements.txt

@@ -0,0 +1,15 @@
+# Environment the re-exports in REEXPORT.md were produced with (Python 3.12, Linux x86_64, CPU only).
+#   python -m venv venv
+#   venv/bin/pip install -r recipes/requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu
+# executorch 1.5.1 = pytorch/executorch git 3b60683923245cf472b7323426920e15623ba361; its wheel ships
+# backends/webgpu (WebGPUPartitioner) and examples/models/llama (export_llm).
+executorch==1.5.1
+torch==2.14.1+cpu
+torchvision==0.29.1+cpu
+torchao==0.18.0+cpu
+transformers==5.19.0
+huggingface_hub==2.2.0
+safetensors==0.8.0
+tokenizers==0.23.3
+numpy==2.5.4
+pillow==12.3.0

export/verify_official.py

@@ -0,0 +1,56 @@
+"""Check that every tensor in a converted Hugging Face D-FINE checkpoint is bit-identical to a
+tensor (or a q/k/v third of an in_proj tensor) of the official checkpoint.
+
+  python verify_official.py Peterande/D-FINE 19214e91f5ce4c1e609022c38b1fc953c47404e7 dfine_s_coco.pth \
+      ustc-community/dfine-small-coco f79e65b5fbb33ceb9d3ebba042955d7410c608f8
+"""
+import hashlib
+import json
+import sys
+
+import torch
+from huggingface_hub import hf_hub_download
+from safetensors.torch import load_file
+
+off_repo, off_rev, off_file, port_repo, port_rev = sys.argv[1:6]
+
+
+def digest(t):
+    t = t.detach().contiguous().cpu()
+    return hashlib.sha256(str(t.dtype).encode() + str(tuple(t.shape)).encode() + t.numpy().tobytes()).hexdigest()
+
+
+off_path = hf_hub_download(off_repo, off_file, revision=off_rev)
+ckpt = torch.load(off_path, map_location="cpu", weights_only=False)
+official = ckpt["model"]
+pool = {}
+for k, t in official.items():
+    if not torch.is_tensor(t):
+        continue
+    pool.setdefault(digest(t), k)
+    if "in_proj" in k and t.shape[0] % 3 == 0:
+        for i, part in enumerate(t.chunk(3, dim=0)):
+            pool.setdefault(digest(part), f"{k}[{'qkv'[i]}]")
+
+port_path = hf_hub_download(port_repo, "model.safetensors", revision=port_rev)
+port = load_file(port_path)
+matched, unmatched = 0, []
+for k, t in port.items():
+    if digest(t) in pool:
+        matched += 1
+    else:
+        unmatched.append((k, tuple(t.shape)))
+nparams = sum(t.numel() for t in port.values())
+unparams = sum(port[k].numel() for k, _ in unmatched)
+print(json.dumps({
+    "official": f"{off_repo}@{off_rev}/{off_file}",
+    "official_sha256": hashlib.sha256(open(off_path, "rb").read()).hexdigest(),
+    "official_keys": list(ckpt.keys()),
+    "port": f"{port_repo}@{port_rev}/model.safetensors",
+    "port_tensors": len(port),
+    "matched": matched,
+    "unmatched": len(unmatched),
+    "unmatched_params": unparams,
+    "total_params": nparams,
+    "unmatched_sample": unmatched[:25],
+}, indent=1))

manifest.json

@@ -0,0 +1,11 @@
+{
+  "model": "dfine-small",
+  "repo": "executorch-community/D-FINE-Small-COCO-ExecuTorch-WebGPU",
+  "files": [
+    {
+      "path": "dfine_s_coco_webgpu.pte",
+      "bytes": 42260612,
+      "sha256": "96cc65f615dc2c79d1da80ef075b831fac8e39e8dcb58af9aff5bab154a4c4d6"
+    }
+  ]
+}