Export and Deploy Models

SUMMARY

Export trained Iris models into inference-ready artifacts and run predictions using the shared Model interface. RF-DETR exports to ONNX, while SAM3-LoRA produces an Iris .pt bundle. Both return a common Prediction structure that can be used directly or visualized in Rerun.

Export and Deployment Workflow

Iris provides a consistent workflow for exporting, loading, and running inference across supported model architectures. Configure the deployment, export a trained checkpoint, load the resulting artifact, and run predictions on new images.

Configure Deployment

Define the model artifact location and select the model architecture before initializing the deployment interface.

Model Configuration

from pathlib import Path

model_path = Path("artifacts/model.pt")
model_name = "sam3-lora"

Model	Model name	Artifact
RF-DETR	rfdetr	.onnx
SAM3-LoRA	sam3-lora	.pt

Post-processing Configuration

Post-processing controls confidence filtering, maximum detections, and model-specific prediction behavior.

RF-DETR

from telekinesis.iris.deploy import RFDETRPostprocessConfig

postprocess = RFDETRPostprocessConfig(
    confidence_threshold=0.4,
    max_detections=100,
)

SAM3-LoRA

from telekinesis.iris.deploy import SAM3PostprocessConfig

postprocess = SAM3PostprocessConfig(
    confidence_threshold=0.5,
    max_detections=100,
    per_prompt_nms_threshold=0.5,
    prompt_conflict_policy="best_prompt",
    cross_prompt_iou_threshold=0.8,
)

SAM3-LoRA supports two prompt-conflict policies:

• multi_label: Retains overlapping detections assigned to different prompts.
• best_prompt: Resolves overlapping predictions to the strongest result when overlap exceeds cross_prompt_iou_threshold.

Deployment Configuration

See Configuration for all available deployment and post-processing settings.

Export Model

Export the trained model using the shared Trainer or directly from an existing checkpoint.

Export from Trainer

After completing training, export the selected checkpoint:

artifact_path = trainer.export(
    artifact_name="model",
    from_best=True,
)

By default, the artifact is saved in the training output directory. Specify output_dir to use a different destination.

Export an Existing Checkpoint

Alternatively, export a previously saved checkpoint without restarting training:

from telekinesis.iris.export import export_model

artifact_path = export_model(
    checkpoint_path="results/training/best.pt",
    output_dir="artifacts",
    artifact_name="model",
)

Iris identifies the model architecture from the checkpoint metadata. For legacy checkpoints without this information, explicitly provide model_name.

Model	Export format	Output
RF-DETR	ONNX	model.onnx
SAM3-LoRA	Iris bundle	model.pt

RF-DETR additionally supports resolution, dynamic_batch, and opset_version export settings.

Load Model

Load the exported artifact through the shared Model deployment interface.

from telekinesis.iris.deploy import Model

model = Model(
    model_path=artifact_path,
    model_name=model_name,
    postprocess=postprocess,
)

The deployment interface initializes the corresponding runtime and applies the selected post-processing configuration.

Runtime Selection

Model	Runtime	Configuration
RF-DETR	ONNX Runtime	providers
SAM3-LoRA	PyTorch	device

Optional loading arguments include class_names, providers, device, and input_size. Pass only the options supported by the runtime selected for the exported artifact.

Runtime Configuration

Iris can infer the model architecture from the artifact extension. Explicitly provide model_name when required. Dynamically exported ONNX models also require input_size=(height, width).

Run Inference

Both model families expose the same predict() method.

prediction = model.predict("images/test.jpg")

Image Inputs

predict() accepts an image path or an HWC NumPy array. Arrays are interpreted as RGB by default. For images loaded through OpenCV, specify the BGR color format:

import cv2

image = cv2.imread("images/test.jpg")

prediction = model.predict(
    image,
    array_color_format="bgr",
)

Text Prompts (SAM3-LoRA)

SAM3-LoRA uses the category prompts embedded in the exported model bundle by default. You can override them for an individual prediction:

prediction = model.predict(
    "images/test.jpg",
    prompts=[
        "green circle",
        "red triangle",
        "blue square",
    ],
)

Each text prompt is evaluated against the input image. The configured post-processing policy determines how overlapping predictions are handled.

Access and Visualize Predictions

Iris returns a unified Prediction structure.

Access Prediction Results

print(prediction.boxes)
print(prediction.scores)
print(prediction.class_ids)
print(prediction.class_names)
print(prediction.masks)

Attribute	Description
boxes	Bounding boxes in absolute XYXY pixel coordinates
scores	Confidence scores for each prediction
class_ids	Predicted class identifiers
class_names	Optional class labels
masks	Instance segmentation masks, when available

Detection-only models return None for masks.

Visualize in Rerun

Predictions can be visualized alongside their corresponding input image using Rerun.

import cv2
import numpy as np
import rerun as rr

image = cv2.imread("images/test.jpg")
image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

rr.init("iris_inference", spawn=True)
rr.log("inference/image", rr.Image(image))

if len(prediction):
    labels = [
        f"{name} {score:.2f}"
        for name, score in zip(
            prediction.class_names
            or map(str, prediction.class_ids),
            prediction.scores,
            strict=True,
        )
    ]

    rr.log(
        "inference/image/detections",
        rr.Boxes2D(
            mins=prediction.boxes[:, :2],
            sizes=prediction.boxes[:, 2:] - prediction.boxes[:, :2],
            labels=labels,
        ),
    )

if prediction.masks is not None and len(prediction):
    segmentation = np.zeros(
        image.shape[:2],
        dtype=np.uint16,
    )

    # Higher-confidence instances take precedence.
    for mask, class_id in zip(
        prediction.masks[::-1],
        prediction.class_ids[::-1],
        strict=True,
    ):
        segmentation[mask] = int(class_id)

    rr.log(
        "inference/image/segmentation",
        rr.SegmentationImage(segmentation),
    )

Export Reference

export_model() Options

Option	Default	Description
checkpoint_path	required	Trainer checkpoint to export
output_dir	required	Artifact destination directory
model_name	checkpoint metadata	Public model name for legacy checkpoints
resolution	None	RF-DETR input resolution override
artifact_name	checkpoint stem	Output filename with or without its extension
dynamic_batch	False	Enables dynamic RF-DETR ONNX batch size
opset_version	17	RF-DETR ONNX operator-set version
verbose	False	Prints the exported ONNX graph

Methods

Method	Returns	Description
export_model(...)	Path	Exports RF-DETR to ONNX or SAM3-LoRA to an Iris .pt bundle
trainer.export(output_dir=None, artifact_name="model", from_best=True)	Path	Exports the best or latest checkpoint from a training run

Deployment Reference

Model Options

Option	Default	Description
model_path	required	RF-DETR ONNX artifact or SAM3-LoRA Iris bundle
model_name	None	Explicit public model name; otherwise inferred from the extension
class_names	None	Category-name mapping or SAM3 prompt sequence
postprocess	None	RFDETRPostprocessConfig, SAM3PostprocessConfig, or shared configuration
num_select	None	Deprecated maximum-detection shorthand
background_class_id	0	RF-DETR class slot excluded from predictions
providers	None	Ordered ONNX Runtime providers
input_size	None	Spatial size required by dynamic RF-DETR ONNX models
array_color_format	"rgb"	Color order for NumPy inputs: "rgb" or "bgr"
device	None	PyTorch device used for SAM3-LoRA inference

Methods

Method	Returns	Description
predict(image, confidence_threshold=None, prompts=None)	Prediction	Runs inference with an optional confidence override and SAM3 prompts
model(image)	Prediction	Calls predict() with configured defaults
len(prediction)	int	Returns the number of predicted instances

Next Steps

Train and Resume a Model

Prepare datasets, configure a trainable model, and execute training using the shared Trainer.

Explore training →

Configuration

Explore model export, runtime, and post-processing parameters.

View configuration →