Reference for ultralytics/utils/export/executorch.py
Improvements
This page is sourced from https://github.com/ultralytics/ultralytics/blob/main/ultralytics/utils/export/executorch.py. Have an improvement or example to add? Open a Pull Request — thank you! 🙏
Summary
Function ultralytics.utils.export.executorch.executorch_wrapper#
def executorch_wrapper(model: torch.nn.Module) -> torch.nn.ModuleApply ExecuTorch-specific model patches required for export/runtime compatibility.
Args
| Name | Type | Description | Default |
|---|---|---|---|
model | torch.nn.Module | required |
ultralytics/utils/export/executorch.py
def executorch_wrapper(model: torch.nn.Module) -> torch.nn.Module:
"""Apply ExecuTorch-specific model patches required for export/runtime compatibility."""
import types
for m in model.modules():
if not isinstance(m, Pose):
continue
m.kpts_decode = types.MethodType(partial(_executorch_kpts_decode, is_pose26=type(m) is Pose26), m)
return modelFunction ultralytics.utils.export.executorch._executorch_kpts_decode#
def _executorch_kpts_decode(self, kpts: torch.Tensor, is_pose26: bool = False) -> torch.TensorDecode pose keypoints for ExecuTorch export with XNNPACK-safe broadcasting.
Args
| Name | Type | Description | Default |
|---|---|---|---|
self | required | ||
kpts | torch.Tensor | required | |
is_pose26 | bool | False |
ultralytics/utils/export/executorch.py
def _executorch_kpts_decode(self, kpts: torch.Tensor, is_pose26: bool = False) -> torch.Tensor:
"""Decode pose keypoints for ExecuTorch export with XNNPACK-safe broadcasting."""
ndim = self.kpt_shape[1]
bs = kpts.shape[0]
y = kpts.view(bs, *self.kpt_shape, -1)
# XNNPACK requires explicit dim matching for broadcasting, expand 2D tensors to 4D.
anchors = self.anchors[None, None]
strides = self.strides[None, None]
a = ((y[:, :, :2] + anchors) if is_pose26 else (y[:, :, :2] * 2.0 + (anchors - 0.5))) * strides
if ndim == 3:
a = torch.cat((a, y[:, :, 2:3].sigmoid()), 2)
return a.view(bs, self.nk, -1)Function ultralytics.utils.export.executorch.torch2executorch#
def torch2executorch(
model: torch.nn.Module,
im: torch.Tensor,
output_dir: Path | str,
metadata: dict | None = None,
prefix: str = "",
calibration_dataset: torch.utils.data.DataLoader | None = None,
) -> strExport a PyTorch model to ExecuTorch format, with static INT8 quantization when calibration data is given.
Args
| Name | Type | Description | Default |
|---|---|---|---|
model | torch.nn.Module | The PyTorch model to export, on CPU. | required |
im | torch.Tensor | Example input tensor for tracing/export, on CPU. | required |
output_dir | Path | str | Directory to save the exported ExecuTorch model. | required |
metadata | dict | None, optional | Optional metadata to save as YAML. | None |
prefix | str, optional | Prefix for log messages. | "" |
calibration_dataset | DataLoader | None, optional | Calibration dataloader for static INT8 (int8 weights + int8 activations, FP32 head on Detect models), as returned by get_int8_calibration_dataloader. Requires executorch>=1.6.0. | None |
Returns
| Type | Description |
|---|---|
str | Path to the exported ExecuTorch model directory. |
ultralytics/utils/export/executorch.py
def torch2executorch(
model: torch.nn.Module,
im: torch.Tensor,
output_dir: Path | str,
metadata: dict | None = None,
prefix: str = "",
calibration_dataset: torch.utils.data.DataLoader | None = None,
) -> str:
"""Export a PyTorch model to ExecuTorch format, with static INT8 quantization when calibration data is given.
Args:
model (torch.nn.Module): The PyTorch model to export, on CPU.
im (torch.Tensor): Example input tensor for tracing/export, on CPU.
output_dir (Path | str): Directory to save the exported ExecuTorch model.
metadata (dict | None, optional): Optional metadata to save as YAML.
prefix (str, optional): Prefix for log messages.
calibration_dataset (DataLoader | None, optional): Calibration dataloader for static INT8 (int8 weights + int8
activations, FP32 head on Detect models), as returned by ``get_int8_calibration_dataloader``.
Requires executorch>=1.6.0.
Returns:
(str): Path to the exported ExecuTorch model directory.
"""
check_executorch_requirements()
from executorch import version as executorch_version
from executorch.backends.xnnpack.partition.xnnpack_partitioner import XnnpackPartitioner
from executorch.exir import to_edge_transform_and_lower
LOGGER.info(f"\n{prefix} starting export with ExecuTorch {executorch_version.__version__}...")
if calibration_dataset is not None:
# Earlier releases quantize the head concat despite the exclusion below, which zeroes the scores
assert check_version(executorch_version.__version__, "1.6.0"), "INT8 export requires executorch>=1.6.0"
from executorch.backends.xnnpack.quantizer.xnnpack_quantizer import (
XNNPACKQuantizer,
get_symmetric_quantization_config,
)
from torchao.quantization.pt2e.quantize_pt2e import convert_pt2e, prepare_pt2e
quantizer = XNNPACKQuantizer().set_global(get_symmetric_quantization_config(is_per_channel=True))
for m in model.modules():
if isinstance(m, Detect): # keep the head float: one int8 scale over boxes and scores zeroes the scores
quantizer.set_module_type(type(m), None)
model = prepare_pt2e(torch.export.export(model, (im,)).module(), quantizer)
for batch in calibration_dataset:
model(batch["img"].float() / 255)
model = convert_pt2e(model)
et_program = to_edge_transform_and_lower(
torch.export.export(model, (im,)),
partitioner=[XnnpackPartitioner()],
).to_executorch()
output_dir = Path(output_dir).resolve() # rmtree refuses a symlinked directory
shutil.rmtree(output_dir, ignore_errors=True) # a re-export would keep an older export's <stem>.pte
output_dir.mkdir(parents=True)
(output_dir / "model.pte").write_bytes(et_program.buffer)
if metadata is not None:
YAML.save(output_dir / "metadata.yaml", metadata)
return str(output_dir)