hubai_sdk.services.convert

module documentation

Run hosted model conversion and download deployable artifacts.

The target-specific helpers RVC2, RVC3, RVC4, and Hailo are the recommended conversion API. Each helper prepares target options and delegates to convert, which coordinates the complete HubAI workflow:

Read model metadata from a model file, YAML config, or NN Archive.

Create or reuse model and variant resources.

Upload the source model as an instance.

Start an export job and wait for it to finish.

Download the exported instance.

Example

Convert an ONNX model for RVC4 with HubAI's general calibration data.

result = client.convert.RVC4(
    path="detector.onnx",
    name="detector",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
)
print(result.downloaded_path)

Input configuration:: path may point to a model file, an NN Archive, or a YAML configuration. Additional opts override values loaded from that configuration. A dictionary is usually easiest in Python; the flat list form exists for the command-line interface.
Resource reuse:: Pass model_id or variant_id to attach the conversion to existing resources. Without them, convert creates resources and reuses a model with the same slug if one already exists.
Quantization:: RVC4 and Hailo accept a built-in calibration domain, a dataset ID beginning with aid_, or a local ZIP file. Passing a ZIP path uploads it for the export job. RVC2 and RVC3 ignore quantization inputs because those helpers expose their platform-specific precision controls instead.

Function	`convert`	Starts the online conversion process.
Function	`Hailo`	Convert a model to Hailo format.
Function	`RVC2`	Convert a model to RVC2 format.
Function	`RVC3`	Convert a model to RVC3 format.
Function	`RVC4`	Convert a model to RVC4 format.
Function	`_combine_opts`	Merge generic options with target-prefixed conversion options.
Function	`_export`	Starts an export job for a model instance.
Function	`_get_instance_response`	Fetch a model instance response, returning `None` if missing.
Function	`_resolve_exported_instance`	Resolve the exported model instance from a completed export job.
Function	`_wait_for_exported_instance_ready`	Wait until an exported model instance is actually downloadable.

@telemetry_operation(OperationTelemetrySpec(operation_name=OperationName.CONVERT, operation_group=TelemetryGroup.CONVERSION, target_resource=TargetResource.CONVERSION))

Starts the online conversion process.

Parameters
target:`Target`	Target platform.
opts:`list[str] \| None`	Additional options for the conversion process.
path:`str`	Path to the model file, NN Archive, or configuration file.
name:`str \| None`	Model name. If not specified, the name is taken from the configuration file or the model file.
license_type:`License`	License type.
is_public:`bool \| None`	Whether the model is public (`True`), private (`False`), or team-scoped (`None`).
description_short:`str`	Short description of the model.
description:`str \| None`	Full description of the model.
architecture_id:`UUID \| str \| None`	Architecture ID.
tasks:`list[Task] \| None`	Tasks this model supports.
links:`list[str] \| None`	Links to related resources.
is_yolo:`bool`	Whether the model is a YOLO model.
model_id:`UUID \| str \| None`	ID of an existing model resource. If specified, that model is used instead of creating a new one.
variant_version:`str \| None`	Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`.
variant_description:`str \| None`	Full description of the model variant.
repository_url:`str \| None`	URL of the repository.
commit_hash:`str \| None`	Commit hash.
quantization_mode:`QuantizationMode \| None`	Quantization mode to use during conversion. Must be one of `INT8_STANDARD`, `INT8_ACCURACY_FOCUSED`, `INT8_INT16_MIXED`, `INT8_INT16_MIXED_ACCURACY_FOCUSED`, or `FP16_STANDARD`. `INT8_STANDARD` is standard INT8 quantization with calibration for optimal performance and model size. `INT8_ACCURACY_FOCUSED` is INT8 quantization with calibration that may improve accuracy without reducing performance or increasing model size, depending on the model. `INT8_INT16_MIXED` uses 8-bit weights and 16-bit activations across all layers for improved numeric stability and accuracy at the cost of performance and model size. `INT8_INT16_MIXED_ACCURACY_FOCUSED` is a mixed INT8 and INT16 calibration-based mode that prioritizes accuracy over throughput. `FP16_STANDARD` is FP16 quantization without calibration for models that require higher accuracy and numeric stability at the cost of performance and model size.
domain:`str \| None`	Domain of the model.
variant_tags:`list[str] \| None`	Tags for the model variant.
variant_id:`UUID \| str \| None`	ID of an existing model version resource. If specified, that version is used instead of creating a new one.
quantization_data:`QuantizationData \| PathType \| None`	Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file. Pass the `.zip` path itself instead of `CUSTOM`; the SDK normalizes local zip inputs automatically.
max_quantization_images:`int \| None`	Maximum number of quantization images.
instance_tags:`list[str] \| None`	Tags for the model instance.
input_shape:`list[int] \| None`	Input shape for the model instance.
is_deployable:`bool \| None`	Whether the model instance is deployable.
output_dir:`str \| None`	Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory.
tool_version:`str \| None`	Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version.
yolo_input_shape:`list[int] \| None`	Input shape for YOLO models.
yolo_version:`YoloVersion \| None`	YOLO version.
yolo_class_names:`list[str] \| None`	Class names for YOLO models.

Returns
`ConvertResponse`	Conversion result containing the downloaded output path, export job, and exported model instance.

def Hailo(path: PathType, optimization_level: Literal[-100, 0, 1, 2, 3, 4] = 2, compression_level: Literal[0, 1, 2, 3, 4, 5] = 2, batch_size: int = 8, alls: list[str] | None = None, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ¶

Convert a model to Hailo format.

Parameters
path:`PathType`	Path to the model file to convert.
optimization_level:`Literal[-100, 0, 1, 2, 3, 4]`	Optimization level for the conversion.
compression_level:`Literal[0, 1, 2, 3, 4, 5]`	Compression level for the conversion.
batch_size:`int`	Batch size for the conversion.
alls:`list[str] \| None`	Hailo ALLS commands applied during conversion.
opts:`Kwargs \| list[str] \| None`	Additional conversion options. These can override config values.
name	Model name. If not specified, the name is taken from the configuration file or the model file.
license_type	License type.
is_public	Whether the model is public (`True`), private (`False`), or team-scoped (`None`).
description_short	Short description of the model.
description	Full description of the model.
architecture_id	Architecture ID.
tasks	Tasks this model supports.
links	Links to related resources.
is_yolo	Whether the model is a YOLO model.
model_id	ID of an existing model resource. If specified, that model is used instead of creating a new one.
variant_version	Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`.
variant_description	Full description of the model variant.
repository_url	URL of the repository.
commit_hash	Commit hash.
quantization_mode	Quantization mode.
quantization_data	Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file.
max_quantization_images	Maximum number of quantization images.
domain	Domain of the model.
variant_tags	Tags for the model variant.
variant_id	ID of an existing model version resource. If specified, that version is used instead of creating a new one.
input_shape	Input shape for the model instance.
is_deployable	Whether the model instance is deployable.
output_dir	Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory.
tool_version	Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version.
yolo_input_shape	Input shape for YOLO models.
yolo_version	YOLO version.
yolo_class_names	Class names for YOLO models.
**hub_kwargs	Additional keyword arguments passed to `convert`.

Returns
`ConvertResponse`	Conversion result containing the downloaded output path, export job, and exported model instance.

def RVC2(path: PathType, mo_args: list[str] | None = None, compile_tool_args: list[str] | None = None, compress_to_fp16: bool = True, number_of_shaves: int = 8, superblob: bool = True, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ¶

Convert a model to RVC2 format.

Parameters
path:`PathType`	Path to the model file to convert.
mo_args:`list[str] \| None`	Additional arguments for the Model Optimizer.
compile_tool_args:`list[str] \| None`	Additional arguments for the compile tool.
compress_to_fp16:`bool`	Whether to compress the model weights to FP16.
number_of_shaves:`int`	Number of shaves to use for the conversion.
superblob:`bool`	Whether to create a superblob for the model.
opts:`Kwargs \| list[str] \| None`	Additional conversion options. These can override config values.
name	Model name. If not specified, the name is taken from the configuration file or the model file.
license_type	License type.
is_public	Whether the model is public (`True`), private (`False`), or team-scoped (`None`).
description_short	Short description of the model.
description	Full description of the model.
architecture_id	Architecture ID.
tasks	Tasks this model supports.
links	Links to related resources.
is_yolo	Whether the model is a YOLO model.
model_id	ID of an existing model resource. If specified, that model is used instead of creating a new one.
variant_version	Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`.
variant_description	Full description of the model variant.
repository_url	URL of the repository.
commit_hash	Commit hash.
domain	Domain of the model.
variant_tags	Tags for the model variant.
variant_id	ID of an existing model version resource. If specified, that version is used instead of creating a new one.
input_shape	Input shape for the model instance.
is_deployable	Whether the model instance is deployable.
output_dir	Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory.
tool_version	Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version.
yolo_input_shape	Input shape for YOLO models.
yolo_version	YOLO version.
yolo_class_names	Class names for YOLO models.
**hub_kwargs	Additional keyword arguments passed to `convert`.

Returns
`ConvertResponse`	Conversion result containing the downloaded output path, export job, and exported model instance.

def RVC3(path: PathType, mo_args: list[str] | None = None, compile_tool_args: list[str] | None = None, compress_to_fp16: bool = True, pot_target_device: PotDevice | Literal['VPU', 'ANY'] = PotDevice.VPU, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ¶

Convert a model to RVC3 format.

Parameters
path:`PathType`	Path to the model file to convert.
mo_args:`list[str] \| None`	Additional arguments for the Model Optimizer.
compile_tool_args:`list[str] \| None`	Additional arguments for the compile tool.
compress_to_fp16:`bool`	Whether to compress the model weights to FP16.
pot_target_device:`PotDevice \| Literal['VPU', 'ANY']`	Target device for POT quantization.
opts:`Kwargs \| list[str] \| None`	Additional conversion options. These can override config values.
name	Model name. If not specified, the name is taken from the configuration file or the model file.
license_type	License type.
is_public	Whether the model is public (`True`), private (`False`), or team-scoped (`None`).
description_short	Short description of the model.
description	Full description of the model.
architecture_id	Architecture ID.
tasks	Tasks this model supports.
links	Links to related resources.
is_yolo	Whether the model is a YOLO model.
model_id	ID of an existing model resource. If specified, that model is used instead of creating a new one.
variant_version	Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`.
variant_description	Full description of the model variant.
repository_url	URL of the repository.
commit_hash	Commit hash.
domain	Domain of the model.
variant_tags	Tags for the model variant.
variant_id	ID of an existing model version resource. If specified, that version is used instead of creating a new one.
input_shape	Input shape for the model instance.
is_deployable	Whether the model instance is deployable.
output_dir	Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory.
tool_version	Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version.
yolo_input_shape	Input shape for YOLO models.
yolo_version	YOLO version.
yolo_class_names	Class names for YOLO models.
**hub_kwargs	Additional keyword arguments passed to `convert`.

Returns
`ConvertResponse`	Conversion result containing the downloaded output path, export job, and exported model instance.

def RVC4(path: PathType, snpe_onnx_to_dlc_args: list[str] | None = None, snpe_dlc_quant_args: list[str] | None = None, snpe_dlc_graph_prepare_args: list[str] | None = None, use_per_channel_quantization: bool = True, use_per_row_quantization: bool = False, htp_socs: list[Literal['sm8350', 'sm8450', 'sm8550', 'sm8650', 'qcs6490', 'qcs8550']] | None = None, opts: Kwargs | list[str] | None = None, **hub_kwargs) -> ConvertResponse: ¶

Convert a model to RVC4 format.

Parameters
path:`PathType`	Path to the model file to convert.
snpe_onnx_to_dlc_args:`list[str] \| None`	Additional arguments for the SNPE ONNX to DLC conversion.
snpe_dlc_quant_args:`list[str] \| None`	Additional arguments for SNPE DLC quantization.
snpe_dlc_graph_prepare_args:`list[str] \| None`	Additional arguments for SNPE DLC graph preparation.
use_per_channel_quantization:`bool`	Whether to use per-channel quantization.
use_per_row_quantization:`bool`	Whether to use per-row quantization.
htp_socs:`list[Literal['sm8350', 'sm8450', 'sm8550', 'sm8650', 'qcs6490', 'qcs8550']] \| None`	HTP SoCs for the final DLC graph.
opts:`Kwargs \| list[str] \| None`	Additional conversion options. These can override config values.
name	Model name. If not specified, the name is taken from the configuration file or the model file.
license_type	License type.
is_public	Whether the model is public (`True`), private (`False`), or team-scoped (`None`).
description_short	Short description of the model.
description	Full description of the model.
architecture_id	Architecture ID.
tasks	Tasks this model supports.
links	Links to related resources.
is_yolo	Whether the model is a YOLO model.
model_id	ID of an existing model resource. If specified, that model is used instead of creating a new one.
variant_version	Model version. If not specified, the version is auto-incremented from the latest version of the model. If no versions exist, the version is `"0.1.0"`.
variant_description	Full description of the model variant.
repository_url	URL of the repository.
commit_hash	Commit hash.
quantization_mode	Quantization mode to use during conversion. Must be one of `INT8_STANDARD`, `INT8_ACCURACY_FOCUSED`, `INT8_INT16_MIXED`, `INT8_INT16_MIXED_ACCURACY_FOCUSED`, or `FP16_STANDARD`. `INT8_STANDARD` is standard INT8 quantization with calibration for optimal performance and model size. `INT8_ACCURACY_FOCUSED` is INT8 quantization with calibration that may improve accuracy without reducing performance or increasing model size, depending on the model. `INT8_INT16_MIXED` uses 8-bit weights and 16-bit activations across all layers for improved numeric stability and accuracy at the cost of performance and model size. `INT8_INT16_MIXED_ACCURACY_FOCUSED` is a mixed INT8 and INT16 calibration-based mode that prioritizes accuracy over throughput. `FP16_STANDARD` is FP16 quantization without calibration for models that require higher accuracy and numeric stability at the cost of performance and model size.
domain	Domain of the model.
variant_tags	Tags for the model variant.
variant_id	ID of an existing model version resource. If specified, that version is used instead of creating a new one.
quantization_data	Data used to quantize this model. This can be a predefined domain (`DRIVING`, `FOOD`, `GENERAL`, `INDOORS`, `RANDOM`, `WAREHOUSE`, `CLIP`, `UNKNOWN`), a dataset ID, or a path to a local quantization `.zip` file. Pass the `.zip` path itself instead of `CUSTOM`; the SDK normalizes local zip inputs automatically.
max_quantization_images	Maximum number of quantization images.
input_shape	Input shape for the model instance.
is_deployable	Whether the model instance is deployable.
output_dir	Directory path for the downloaded files. If not specified, the downloader creates a directory named after the exported instance slug under the current working directory.
tool_version	Version of the tool used for conversion. For RVC2 and RVC3 this is the IR version, while for RVC4 this is the SNPE version.
yolo_input_shape	Input shape for YOLO models.
yolo_version	YOLO version.
yolo_class_names	Class names for YOLO models.
**hub_kwargs	Additional keyword arguments passed to `convert`.

Returns
`ConvertResponse`	Conversion result containing the downloaded output path, export job, and exported model instance.

def _combine_opts(target: Target, target_kwargs: Kwargs, opts: list[str] | Kwargs | None) -> list[str]: ¶

Merge generic options with target-prefixed conversion options.

Returns
`list[str]`	A flat option list ready for config parsing.

def _export(name: str, identifier: UUID | str, target: Target, quantization_mode: QuantizationMode | None, quantization_data: str | None, max_quantization_images: int | None = None, yolo_version: str | None = None, yolo_class_names: list[str] | None = None, **kwargs) -> JobMessageResponse: ¶

Starts an export job for a model instance.

Returns
`JobMessageResponse`	The created export job response.

def _get_instance_response(instance_id: str) -> ModelInstanceResponse | None: ¶

Fetch a model instance response, returning None if missing.

Returns
`ModelInstanceResponse \| None`	The model instance response, or `None` if the instance does not exist yet.

def _resolve_exported_instance(job: JobMessageResponse) -> ModelInstanceResponse: ¶

Resolve the exported model instance from a completed export job.

Returns
`ModelInstanceResponse`	The exported model instance once it is ready to download.

def _wait_for_exported_instance_ready(instance_id: str, *, timeout_seconds: int = 180, poll_interval_seconds: int = 2) -> ModelInstanceResponse: ¶

Wait until an exported model instance is actually downloadable.

Returns
`ModelInstanceResponse`	The exported model instance once it becomes downloadable.