Skip to content

Export a Model ​

SUMMARY

export_model() reads the model family, variant, task, config, categories, and run name from the Trainer checkpoint. RF-DETR and YOLOX export to ONNX; SAM3-LoRA exports to an Iris .pt deployment bundle.

Export Workflow ​

Choose an Export Script ​

python
"""Export an RF-DETR checkpoint to an ONNX artifact."""

import argparse
from pathlib import Path

from loguru import logger

from telekinesis.iris.export import RFDETRONNXExportOptions, export_model


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--checkpoint", type=Path, required=True)
    parser.add_argument("--output-dir", type=Path, required=True)
    parser.add_argument("--artifact-name", default="model")
    parser.add_argument("--resolution", type=int)
    parser.add_argument("--dynamic-batch", action=argparse.BooleanOptionalAction, default=False)
    parser.add_argument("--opset-version", type=int, default=17)
    parser.add_argument("--verbose", action=argparse.BooleanOptionalAction, default=False)
    return parser.parse_args()


def export_rfdetr(args: argparse.Namespace) -> None:
    """Export the checkpoint."""
    artifact = export_model(
        checkpoint_path=args.checkpoint,
        output_dir=args.output_dir,
        format="onnx",
        artifact_name=args.artifact_name,
        options=RFDETRONNXExportOptions(
            resolution=args.resolution,
            dynamic_batch=args.dynamic_batch,
            opset_version=args.opset_version,
            verbose=args.verbose,
        ),
    )
    logger.success(f"Exported RF-DETR artifact to {artifact.resolve()}")


if __name__ == "__main__":
    export_rfdetr(parse_args())
python
"""Export a YOLOX checkpoint to an ONNX artifact."""

import argparse
from pathlib import Path

from loguru import logger

from telekinesis.iris.export import YOLOXONNXExportOptions, export_model


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--checkpoint", type=Path, required=True)
    parser.add_argument("--output-dir", type=Path, required=True)
    parser.add_argument("--artifact-name", default="model")
    parser.add_argument("--resolution", type=int)
    parser.add_argument("--dynamic-batch", action=argparse.BooleanOptionalAction, default=False)
    parser.add_argument("--opset-version", type=int, default=17)
    parser.add_argument("--verbose", action=argparse.BooleanOptionalAction, default=False)
    return parser.parse_args()


def export_yolox(args: argparse.Namespace) -> None:
    """Export the checkpoint."""
    artifact = export_model(
        checkpoint_path=args.checkpoint,
        output_dir=args.output_dir,
        format="onnx",
        artifact_name=args.artifact_name,
        options=YOLOXONNXExportOptions(
            resolution=args.resolution,
            dynamic_batch=args.dynamic_batch,
            opset_version=args.opset_version,
            verbose=args.verbose,
        ),
    )
    logger.success(f"Exported YOLOX artifact to {artifact.resolve()}")


if __name__ == "__main__":
    export_yolox(parse_args())
python
"""Export a SAM3 LoRA checkpoint to an Iris PyTorch bundle."""

import argparse
from pathlib import Path

from loguru import logger

from telekinesis.iris.export import export_model


def parse_args() -> argparse.Namespace:
    """Parse command-line arguments."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--checkpoint", type=Path, required=True)
    parser.add_argument("--output-dir", type=Path, required=True)
    parser.add_argument("--artifact-name", default="model")
    return parser.parse_args()


def export_sam3_lora(args: argparse.Namespace) -> None:
    """Export the checkpoint."""
    artifact = export_model(
        checkpoint_path=args.checkpoint,
        output_dir=args.output_dir,
        format="bundle",
        artifact_name=args.artifact_name,
    )
    logger.success(f"Exported SAM3 LoRA bundle to {artifact.resolve()}")


if __name__ == "__main__":
    export_sam3_lora(parse_args())

Export the Checkpoint ​

Choose the command for your model family:

bash
python export_rfdetr.py \
  --checkpoint results/rfdetr/best.pt \
  --output-dir artifacts/rfdetr
bash
python export_yolox.py \
  --checkpoint results/yolox/best.pt \
  --output-dir artifacts/yolox
bash
python export_sam3_lora.py \
  --checkpoint results/sam3_lora/best.pt \
  --output-dir artifacts/sam3_lora

To override ONNX settings, pass the options class that matches the checkpoint family:

python
artifact = export.export_model(  # RF-DETR
    "results/rfdetr/best.pt",
    "artifacts/rfdetr",
    options=export.RFDETRONNXExportOptions(dynamic_batch=True),
)

artifact = export.export_model(  # YOLOX
    "results/yolox/best.pt",
    "artifacts/yolox",
    options=export.YOLOXONNXExportOptions(resolution=640),
)

Artifact Names

When artifact_name is omitted, Iris uses the checkpoint's stored run_name, then falls back to the checkpoint stem. Pass a filename only, with or without the family extension.

Export Artifacts ​

Model familyDefault formatArtifact contents
RF-DETR.onnxONNX network plus embedded Iris metadata
YOLOX.onnxONNX network plus category IDs and embedded Iris metadata
SAM3-LoRA.ptLoRA weights, prompts, base-model reconstruction data, and metadata

API Reference ​

export_model() ​

ParameterDefaultDescription
checkpoint_pathrequiredCheckpoint created by the shared Iris Trainer
output_dirrequiredDestination directory
formatfamily defaultOptional selector: "onnx" for RF-DETR/YOLOX or "bundle" for SAM3-LoRA
artifact_namestored run nameOutput filename, not a path
optionsNoneMatching RFDETRONNXExportOptions or YOLOXONNXExportOptions; SAM3-LoRA accepts no options

ONNX Options ​

Both ONNX option classes expose:

OptionDefaultDescription
resolutionNoneSquare resolution override; otherwise uses checkpoint configuration
dynamic_batchFalseMakes the batch dimension dynamic
opset_version17Positive ONNX operator-set version
verboseFalsePrints the exported graph

Checkpoint Metadata

The exporter no longer accepts model_name. Use a checkpoint produced by the updated Trainer; export fails when model_metadata is absent or its family does not match the supplied options.

Next Steps ​