Export a Model

SUMMARY

Export a trained Iris checkpoint as an inference-ready artifact. The checkpoint model family determines the output: RFDETR exports to ONNX, while SAM3-LoRA exports to an Iris .pt bundle.

Export Workflow

Use the same workflow for any supported Iris model family. Pass the completed checkpoint and the model name used for training; Iris reads the checkpoint metadata and produces the matching artifact type.

Create export.py

"""Export an Iris training checkpoint as an inference-ready artifact."""

import argparse
from pathlib import Path

from loguru import logger
from telekinesis.iris import export


def export_model_example(args: argparse.Namespace) -> None:
    """Export a checkpoint using its Iris model family."""
    # ===================== Configure Export ===============================
    artifact_path = export.export_model(
        checkpoint_path=args.checkpoint,
        output_dir=args.output_dir,
        model_name=args.model_name,
        artifact_name="model",
    )
    logger.info(f"Exported model artifact: {artifact_path.resolve()}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--checkpoint", type=Path, required=True, help="Path to the trained Iris checkpoint.")
    parser.add_argument("--output-dir", type=Path, required=True, help="Directory in which to save the exported artifact.")
    parser.add_argument("--model-name", required=True, help="Model name used for training, such as 'seg-medium' or 'sam3-lora'.")
    export_model_example(parser.parse_args())

Run the Export

Export an RFDETR checkpoint:

python export.py \
  --checkpoint results/rfdetr/best.pt \
  --output-dir results/rfdetr \
  --model-name seg-medium

This creates results/rfdetr/model.onnx.

Export a SAM3-LoRA checkpoint:

python export.py \
  --checkpoint results/sam3-lora/best.pt \
  --output-dir results/sam3-lora \
  --model-name sam3-lora

This creates results/sam3-lora/model.pt.

Match the Training Configuration

Use the model name and checkpoint from the same training run. For RFDETR, retain the training variant and resolution. For SAM3-LoRA, export a checkpoint created through Trainer(model=SAM3LoRA(...), ...) so the bundle includes its prompts and reconstruction metadata.

Run the Example

Runnable versions are available in the Telekinesis examples repository:

cd telekinesis-examples
python examples/iris/export_custom_rfdetr_model.py \
  --checkpoint results/rfdetr/best.pt \
  --output-dir artifacts/rfdetr

python examples/iris/export_custom_sam3_lora_model.py \
  --checkpoint results/sam3-lora/best.pt \
  --output-dir artifacts/sam3-lora

Export Artifacts

Model family	Artifact	Contents
RFDETR	.onnx	ONNX model for local prediction
SAM3-LoRA	.pt	LoRA weights, prompts, and model reconstruction metadata

Export Reference

Option	Required	Description
checkpoint_path	Yes	Trainer checkpoint for a supported Iris model family
output_dir	Yes	Directory in which to write the deployment artifact
model_name	Yes	Model name used for training; e.g. seg-medium or sam3-lora
artifact_name	No	Output filename; defaults to the checkpoint stem
resolution	No	RFDETR square input resolution override
dynamic_batch	No	Enables dynamic batching for RFDETR ONNX export
opset_version	No	ONNX operator-set version for RFDETR export; defaults to 17

Next Steps

Run Inference

Load an exported artifact locally and run inference.

Run inference →

Configuration

Review export and post-processing settings.

View configuration →