otx.engine#

API for OTX Entry-Point User.

Classes

Engine(*[, data_root, task, work_dir, ...])

OTX Engine.

Bases: object

OTX Engine.

This class defines the Engine for OTX, which governs each step of the OTX workflow.

Example

The following examples show how to use the Engine class.

Auto-Configuration with data_root:

engine = Engine(
    data_root=<dataset/path>,
)

Create Engine with Custom OTXModel:

engine = Engine(
    data_root=<dataset/path>,
    model=OTXModel(...),
    checkpoint=<checkpoint/path>,
)

Create Engine with Custom OTXDataModule:

engine = Engine(
    model = OTXModel(...),
    datamodule = OTXDataModule(...),
)

Initializes the OTX Engine.

Parameters:

data_root (PathLike | None, optional) – Root directory for the data. Defaults to None.
task (OTXTaskType | None, optional) – The type of OTX task. Defaults to None.
work_dir (PathLike, optional) – Working directory for the engine. Defaults to “./otx-workspace”.
datamodule (OTXDataModule | None, optional) – The data module for the engine. Defaults to None.
model (OTXModel | str | None, optional) – The model for the engine. Defaults to None.
checkpoint (PathLike | None, optional) – Path to the checkpoint file. Defaults to None.
device (DeviceType, optional) – The device type to use. Defaults to DeviceType.auto.
**kwargs – Additional keyword arguments for pl.Trainer.

Run XAI using the specified model and data (test subset).

Parameters:

checkpoint (PathLike | None, optional) – The path to the checkpoint file to load the model from.
datamodule (EVAL_DATALOADERS | OTXDataModule | None, optional) – The data module to use for predictions.
explain_config (ExplainConfig | None, optional) – Config used to handle saliency maps.
dump (bool) – Whether to dump “saliency_map” or not.
**kwargs – Additional keyword arguments for pl.Trainer configuration.

Returns:

Saliency maps.

Return type:

list

Example

>>> engine.explain(
...     datamodule=OTXDataModule(),
...     checkpoint=<checkpoint/path>,
...     explain_config=ExplainConfig(),
...     dump=True,
... )

CLI Usage:

To run XAI using the specified model, run
```python otx explain

–config <CONFIG_PATH> –data_root <DATASET_PATH, str> –checkpoint <CKPT_PATH, str>

```

export(checkpoint: str | Path | PathLike | None = None, export_format: OTXExportFormatType = OTXExportFormatType.OPENVINO, export_precision: OTXPrecisionType = OTXPrecisionType.FP32, explain: bool = False) → Path[source]#

Export the trained model to OpenVINO Intermediate Representation (IR) or ONNX formats.

Parameters:

checkpoint (PathLike | None, optional) – Checkpoint to export. Defaults to None.
export_config (ExportConfig | None, optional) – Config that allows to set export
None. (format and precision. Defaults to) –
explain (bool) – Whether to get “saliency_map” and “feature_vector” or not.

Returns:

Path to the exported model.

Return type:

Path

Example

>>> engine.export(
...     checkpoint=<checkpoint/path>,
...     export_format=OTXExportFormatType.OPENVINO,
...     export_precision=OTXExportPrecisionType.FP32,
...     explain=True,
... )

CLI Usage:

To export a model with default setting (OPENVINO, FP32), run
```python otx export

–config <CONFIG_PATH> –data_root <DATASET_PATH, str> –checkpoint <CKPT_PATH, str>

```
To export a model with precision FP16 and format ONNX, run
```python otx export

–config <CONFIG_PATH> –data_root <DATASET_PATH, str> –checkpoint <CKPT_PATH, str> –export_precision FP16 –export_format ONNX

```

Builds the engine from a configuration file.

Parameters:

config_path (PathLike) – The configuration file path.
data_root (PathLike | None) – Root directory for the data. Defaults to None. If data_root is None, use the data_root from the configuration file.
work_dir (PathLike | None, optional) – Working directory for the engine. Defaults to None. If work_dir is None, use the work_dir from the configuration file.
kwargs – Arguments that can override the engine’s arguments.

Returns:

An instance of the Engine class.

Return type:

Engine

Example

>>> engine = Engine.from_config(
...     config="config.yaml",
... )

Builds the engine from a model name.

Parameters:

model_name (str) – The model name.
task (OTXTaskType) – The type of OTX task.
data_root (PathLike | None) – Root directory for the data. Defaults to None. If data_root is None, use the data_root from the configuration file.
work_dir (PathLike | None, optional) – Working directory for the engine. Defaults to None. If work_dir is None, use the work_dir from the configuration file.
kwargs – Arguments that can override the engine’s arguments.

Returns:

An instance of the Engine class.

Return type:

Engine

Example

>>> engine = Engine.from_model_name(
...     model_name="atss_mobilenetv2",
...     task="DETECTION",
...     data_root=<dataset/path>,
... )

If you want to override configuration from default config:

>>> overriding = {
...     "data.config.train_subset.batch_size": 2,
...     "data.config.test_subset.subset_name": "TESTING",
... }
>>> engine = Engine(
...     model_name="atss_mobilenetv2",
...     task="DETECTION",
...     data_root=<dataset/path>,
...     **overriding,
... )

optimize(checkpoint: PathLike | None = None, datamodule: TRAIN_DATALOADERS | OTXDataModule | None = None, max_data_subset_size: int | None = None, export_demo_package: bool = False) → Path[source]#

Applies NNCF.PTQ to the underlying models (now works only for OV models).

PTQ performs int-8 quantization on the input model, so the resulting model comes in mixed precision (some operations, however, remain in FP32).

Parameters:

checkpoint (str | Path | None, optional) – Checkpoint to optimize. Defaults to None.
datamodule (TRAIN_DATALOADERS | OTXDataModule | None, optional) – The data module to use for optimization.
max_data_subset_size (int | None) – The maximum size of the train subset from datamodule that would be
set (used for model optimization. If not) –
it's (NNCF.PTQ will select subset size according to) –
settings. (default) –
export_demo_package (bool) – Whether to export demo package with optimized models.
package. (It outputs zip archive with stand-alone demo) –

Returns:

path to the optimized model.

Return type:

Path

Example

>>> engine.optimize(
...     checkpoint=<checkpoint/path>,
...     datamodule=OTXDataModule(),
...     checkpoint=<checkpoint/path>,
... )

CLI Usage:

To optimize a model, run

```python otx optimize

–checkpoint <CKPT_PATH, str> –model <CONFIG | CLASS_PATH_OR_NAME> –data_root <DATASET_PATH, str> –model.model_name=<PATH_TO_IR_XML, str>

```

Run predictions using the specified model and data.

Parameters:

datamodule (EVAL_DATALOADERS | OTXDataModule | None, optional) – The data module to use for predictions.
checkpoint (PathLike | None, optional) – The path to the checkpoint file to load the model from.
return_predictions (bool | None, optional) – Whether to return the predictions or not.
explain (bool) – Whether to dump “saliency_map” and “feature_vector” or not.
explain_config (ExplainConfig) – Explain configuration (used for saliency map post-processing).
**kwargs – Additional keyword arguments for pl.Trainer configuration.

Returns:

The predictions if return_predictions is True, otherwise None.

Return type:

list | None

Example

>>> engine.predict(
...     datamodule=OTXDataModule(),
...     checkpoint=<checkpoint/path>,
...     return_predictions=True,
...     explain=True,
... )

CLI Usage:

you can pick a model.
```python otx predict

–config <CONFIG_PATH> –data_root <DATASET_PATH, str> –checkpoint <CKPT_PATH, str>

```
If you have a ready configuration file, run it like this.
`python otx predict --config <CONFIG_PATH, str> --checkpoint <CKPT_PATH, str> `

test(checkpoint: PathLike | None = None, datamodule: EVAL_DATALOADERS | OTXDataModule | None = None, metric: MetricCallable | None = None, **kwargs) → dict[source]#

Run the testing phase of the engine.

Parameters:

datamodule (EVAL_DATALOADERS | OTXDataModule | None, optional) – The data module containing the test data.
checkpoint (PathLike | None, optional) – Path to the checkpoint file to load the model from. Defaults to None.
metric (MetricCallable | None) – If not None, it will override OTXModel.metric_callable with the given metric callable. It will temporarilly change the evaluation metric for the validation and test.
**kwargs – Additional keyword arguments for pl.Trainer configuration.

Returns:

Dictionary containing the callback metrics from the trainer.

Return type:

dict

Example

>>> engine.test(
...     datamodule=OTXDataModule(),
...     checkpoint=<checkpoint/path>,
... )

CLI Usage:

you can pick a model.
```python otx test

–model <CONFIG | CLASS_PATH_OR_NAME> –data_root <DATASET_PATH, str> –checkpoint <CKPT_PATH, str>

```
If you have a ready configuration file, run it like this.
`python otx test --config <CONFIG_PATH, str> --checkpoint <CKPT_PATH, str> `

train(max_epochs: int = 10, seed: int | None = None, deterministic: bool | Literal['warn'] = False, precision: _PRECISION_INPUT | None = '32', val_check_interval: int | float | None = None, callbacks: list[Callback] | Callback | None = None, logger: Logger | Iterable[Logger] | bool | None = None, resume: bool = False, metric: MetricCallable | None = None, run_hpo: bool = False, hpo_config: HpoConfig = HpoConfig(search_space=None, save_path=None, mode='max', num_trials=None, num_workers=1, expected_time_ratio=4, maximum_resource=None, prior_hyper_parameters=None, acceptable_additional_time_ratio=1.0, minimum_resource=None, reduction_factor=3, asynchronous_bracket=True, asynchronous_sha=False, metric_name=None), checkpoint: PathLike | None = None, adaptive_bs: Literal['None', 'Safe', 'Full'] = 'None', **kwargs) → dict[str, Any][source]#

Trains the model using the provided LightningModule and OTXDataModule.

Parameters:

max_epochs (int | None, optional) – The maximum number of epochs. Defaults to None.
seed (int | None, optional) – The random seed. Defaults to None.
deterministic (bool | Literal["warn"]) – Whether to enable deterministic behavior.
Also –
failures (can be set to warn to avoid) –
don't (because some operations) –
False. (support deterministic mode. Defaults to) –
precision (_PRECISION_INPUT | None, optional) – The precision of the model. Defaults to 32.
val_check_interval (int | float | None, optional) – The validation check interval. Defaults to None.
callbacks (list[Callback] | Callback | None, optional) – The callbacks to be used during training.
logger (Logger | Iterable[Logger] | bool | None, optional) – The logger(s) to be used. Defaults to None.
resume (bool, optional) – If True, tries to resume training from existing checkpoint.
metric (MetricCallable | None) – If not None, it will override OTXModel.metric_callable with the given metric callable. It will temporarilly change the evaluation metric for the validation and test.
run_hpo (bool, optional) – If True, optimizer hyper parameters before training a model.
hpo_config (HpoConfig | None, optional) – Configuration for HPO.
checkpoint (PathLike | None, optional) – Path to the checkpoint file. Defaults to None.
adaptive_bs (Literal["None", "Safe", "Full"]) – Change the actual batch size depending on the current GPU status. Safe => Prevent GPU out of memory. Full => Find a batch size using most of GPU memory.
**kwargs – Additional keyword arguments for pl.Trainer configuration.

Returns:

A dictionary containing the callback metrics from the trainer.

Return type:

dict[str, Any]

Example

>>> engine.train(
...     max_epochs=3,
...     seed=1234,
...     deterministic=False,
...     precision="32",
... )

CLI Usage:

you can train with data_root only. then OTX will provide default model.
`python otx train --data_root <DATASET_PATH> `
you can pick a model or datamodule as Config file or Class.
`python otx train --data_root <DATASET_PATH> --model <CONFIG | CLASS_PATH_OR_NAME> --data <CONFIG | CLASS_PATH_OR_NAME> `
Of course, you can override the various values with commands.
```python otx train

–data_root <DATASET_PATH> –max_epochs <EPOCHS, int> –checkpoint <CKPT_PATH, str>

```
If you have a complete configuration file, run it like this.
`python otx train --data_root <DATASET_PATH> --config <CONFIG_PATH, str> `

property datamodule: OTXDataModule#

Returns the datamodule object associated with the engine.

Returns:: The OTXDataModule object.
Return type:: OTXDataModule

property device: DeviceConfig#: Device engine uses.

property model: OTXModel#

Returns the model object associated with the engine.

Returns:: The OTXModel object.
Return type:: OTXModel

property trainer: Trainer#

Returns the trainer object associated with the engine.

To get this property, you should execute Engine.train() function first.

Returns:: The trainer object.
Return type:: Trainer

property trainer_params: dict#

Returns the parameters used for training the model.

Returns:: A dictionary containing the training parameters.
Return type:: dict

property work_dir: str | Path | PathLike#: Work directory.