# HubAI

## Overview

HubAI is the recommended online conversion workflow for Luxonis devices. It runs
[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) in the
cloud and produces deployment artifacts without local converter setup.

This page focuses on online conversion usage and migration from legacy tools. For the managed Model Registry workflow and
platform-specific conversion settings, see the [HubAI
Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) guide. For SDK installation,
authentication, and model, variant, and instance APIs, see the [HubAI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) documentation.

## Quick Start

Install hubai-sdk and configure HUBAI_API_KEY as described in the [HubAI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) page, then run a conversion:

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))

response = client.convert.RVC2(
    path="path/to/model.onnx",
    name="my-converted-model",
)

print(response.downloaded_path)
```

The returned response downloads the converted artifact locally and also exposes the created Hub AI instance metadata.

## Python API

The online conversion API lives under the HubAIClient.convert namespace. Use target-specific helpers such as convert.RVC2 and
convert.RVC4 when the target is fixed.

There is also a generic conversion entrypoint if you want to choose the target programmatically:

```python
from hubai_sdk.utils.types import Target

response = client.convert.convert(
    Target.RVC2,
    path="path/to/model.onnx",
    name="my-converted-model",
)
```

The conversion function takes a number of parameters to specify the model and the conversion options. Here we list the main ones
to get you started, but for the exact current parameter set, refer to the [full API
documentation](https://github.com/luxonis/hubai-sdk/blob/main/docs/available_parameters.md).

### General Parameters

General parameters applicable to all conversion functions.

| argument | type | description |
| --- | --- | --- |
| `path` | `str` | The path to the model file. |
| `tool_version` | `str \| None` | The version of the conversion tool. |
| `quantization_mode` | `Literal["INT8_STANDARD", "INT8_ACCURACY_FOCUSED", "INT8_INT16_MIXED",
"INT8_INT16_MIXED_ACCURACY_FOCUSED", "FP16_STANDARD", "FP32_STANDARD"]` | Quantization or precision preset used by targets that
support it, for example `INT8_STANDARD` or `FP16_STANDARD`. |
| `output_dir` | `str \| None` | The directory to save the converted model. If not specified, the model will be saved in the
current working directory. |

### YOLO Parameters

These parameters are only relevant if you're converting a YOLO model.

| argument | type | description |
| --- | --- | --- |
| `yolo_input_shape` | `list[int] \| None` | The input shape of the YOLO model. |
| `yolo_version` | `str \| None` | Optional YOLO version override, for example `"yolov8"`. If omitted, the backend attempts to
detect the version automatically from the PyTorch model file. |
| `yolo_class_names` | `list[str] \| None` | The class names of the model. |

You do not need to set yolo_version explicitly for YOLO conversions. If it is omitted, the backend attempts to detect the version
automatically. The PyTorch model file still needs to come from one of the supported YOLO versions.

### RVC2 Parameters

Parameters specific to the RVC2 conversion.

| argument | type | description |
| --- | --- | --- |
| `mo_args` | `list[str] \| None` | The arguments to pass to the model optimizer. |
| `compile_tool_args` | `list[str] \| None` | The arguments to pass to the BLOB compiler. |
| `compress_to_fp16` | `bool` | Whether to compress the model's weights to FP16 precision. Defaults to `True`. |
| `number_of_shaves` | `int` | The number of shaves to use. Defaults to `8`. |
| `superblob` | `bool` | Whether to create a superblob. Defaults to `True`. Use `False` if you want legacy RVC2 blob conversion. |

### RVC4 Parameters

Parameters specific to the RVC4 conversion.

> When converting for
> `RVC4`
> , choose an SNPE version that matches your deployment environment. See the
> [SNPE compatibility table in Conversion
Troubleshooting](https://docs.luxonis.com/software-v3/ai-inference/conversion/troubleshooting.md)
> .

| argument | type | description |
| --- | --- | --- |
| `snpe_onnx_to_dlc_args` | `list[str] \| None` | The arguments to pass to the `snpe-onnx-to-dlc` tool. |
| `snpe_dlc_quant_args` | `list[str] \| None` | The arguments to pass to the `snpe-dlc-quant` tool. |
| `snpe_dlc_graph_prepare_args` | `list[str] \| None` | The arguments to pass to the `snpe-dlc-graph-prepare` tool. |
| `use_per_channel_quantization` | `bool` | Whether to use per-channel quantization. Defaults to `True`. |
| `use_per_row_quantization` | `bool` | Whether to use per-row quantization. Defaults to `False`. |
| `htp_socs` | `list[str] \| None` | The list of HTP SoCs to use. |

Conversion calls can also create or attach Hub AI resources through arguments such as name, model_id, variant_id, variant_version,
and input_shape. For those workflows and the broader SDK surface, see the [HubAI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) page.

## CLI Reference

The conversion can also be done using the command line interface. Start with:

```bash
hubai login
hubai convert RVC2 --path /path/to/model.onnx --name "my-model"
```

See hubai convert --help for the full list of options.

## Migration from BlobConverter

[BlobConverter](https://pypi.org/project/blobconverter/) is our previous library for converting models to the BLOB format for
earlier OAK workflows. It is being replaced by
[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) and HubAI
SDK, which are the supported paths going forward.

blobconverter is still available and can be used for conversion, but we recommend HubAI SDK for new projects. The API is similar,
but there are differences in parameter names and in how conversion is executed.

blobconverter offers several functions for converting models from different frameworks, such as from_onnx, from_openvino, and
from_tf. These functions are replaced by convert.RVC2 in HubAI SDK, which takes a single path argument pointing to the model
input.

The following table shows the mapping between the parameters of blobconverter and HubAI SDK.

| `blobconverter` | `HubAI SDK` | Notes |
| --- | --- | --- |
| `model` | `path` | The model file path. |
| `xml` | `path` | The XML file path. Only for conversion from OpenVINO IR. |
| `bin` | `opts["input_bin"]` | The BIN file path. Only for conversion from OpenVINO IR. |
| `version` | `tool_version` | The version of the conversion tool. |
| `data_type` | `compress_to_fp16` | Use `True` for FP16-compressed weights and `False` otherwise. `RVC2` does not use
`quantization_mode`. |
| `shaves` | `number_of_shaves` | The number of shaves to use. |
| `optimizer_params` | `mo_args` | The arguments to pass to the model optimizer. |
| `compile_params` | `compile_tool_args` | The arguments to pass to the BLOB compiler. |

By default, HubAI SDK enables superblob, which is only supported on DepthAI v3. If you want to convert a model to the legacy RVC2
blob format, pass superblob=False to convert.RVC2.

### Simple Conversion

Simple ONNX conversion using blobconverter

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
)
```

Equivalent code using HubAI SDK

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
)

blob = response.downloaded_path
```

### Conversion from OpenVINO IR

blobconverter example

```python
import blobconverter

blob = blobconverter.from_openvino(
    xml="resnet18.xml",
    bin="resnet18.bin",
)
```

HubAI SDK example

```python
# When the XML and BIN files are at the same location,
# only the XML needs to be specified.
response = client.convert.RVC2(path="resnet18.xml")
blob = response.downloaded_path

# Otherwise, the BIN file can be specified using
# the `opts` parameter.
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "resnet18.bin",
    },
)
blob = response.downloaded_path
```

### Conversion from TFLite

> HubAI online conversion does not support conversion from frozen PB files. Only TFLite files are supported.

blobconverter example

```python
import blobconverter

blob = blobconverter.from_tf(
    frozen_pb="resnet18.tflite",
)
```

Equivalent code using HubAI SDK

```python
response = client.convert.RVC2(
    path="resnet18.tflite",
)

blob = response.downloaded_path
```

### Advanced Parameters

blobconverter.from_onnx with advanced parameters

```python
import blobconverter

blob = blobconverter.from_onnx(
    model="resnet18.onnx",
    data_type="FP16",
    version="2021.4",
    shaves=6,
    optimizer_params=[
        "--mean_values=[127.5,127.5,127.5]",
        "--scale_values=[255,255,255]",
    ],
    compile_params=["-ip U8"],
)
```

Equivalent code using HubAI SDK

```python
response = client.convert.RVC2(
    path="resnet18.onnx",
    tool_version="2021.4.0",
    number_of_shaves=6,
    mo_args=[
        "mean_values=[127.5,127.5,127.5]",
        "scale_values=[255,255,255]",
    ],
    compile_tool_args=["-ip", "U8"],
)

blob = response.downloaded_path
```

### Caffe Conversion

Conversion from the Caffe framework is not supported.

## Migration from tools.luxonis.com

The web app hosted on [tools.luxonis.com](https://tools.luxonis.com/) is our legacy application for converting YOLO object
detection models. It is being replaced by HubAI online conversion.

Compared to the web application, HubAI online conversion also supports instance segmentation, pose, oriented detection, and
classification YOLO models. For the current conversion capabilities, refer to the [HubAI
Conversion](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) documentation.

Here is an example of converting an existing .pt file to an RVC2-compatible .superblob:

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))

converted_model = client.convert.RVC2(
    path="yolov6n.pt",
    yolo_version="yolov6r4",
)
```

This uses our Hub cloud service to perform the conversion and downloads a .tar.xz bundle when the job finishes. For additional
YOLO-specific flags, see the [YOLO
parameters](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) section.