HubAI

概述

HubAI 是适用于 Luxonis 设备的推荐在线转换工作流。它在云端运行 ModelConverter，无需本地转换器设置即可生成部署产物。本页重点介绍在线转换的使用方法以及从旧工具的迁移。如需了解托管模型注册工作流和特定平台的转换设置，请参阅 HubAI 转换指南。如需了解 SDK 安装、身份验证以及模型、变体和实例 API，请参阅 HubAI SDK 文档。

快速开始

安装 hubai-sdk 并按照 HubAI SDK 页面中的说明配置 HUBAI_API_KEY，然后运行转换：

Python

1import os
2
3from hubai_sdk import HubAIClient
4
5client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
6
7response = client.convert.RVC2(
8    path="path/to/model.onnx",
9    name="my-converted-model",
10)
11
12print(response.downloaded_path)

返回的响应会将转换后的产物下载到本地，并公开创建的 Hub AI 实例元数据。

Python API

在线转换 API 位于 HubAIClient.convert 命名空间下。当目标固定时，请使用特定目标的辅助函数，例如 convert.RVC2 和 convert.RVC4。如果你想以编程方式选择目标，还有一个通用的转换入口：

Python

1from hubai_sdk.utils.types import Target
2
3response = client.convert.convert(
4    Target.RVC2,
5    path="path/to/model.onnx",
6    name="my-converted-model",
7)

转换函数接受多个参数来指定模型和转换选项。这里列出主要参数以供入门，但有关确切的最新参数集，请参阅完整 API 文档。

通用参数

适用于所有转换函数的通用参数。

参数	类型	描述
`path`	`str`	模型文件的路径。
`tool_version`	`str \| None`	转换工具的版本。
`quantization_mode`	`Literal["INT8_STANDARD", "INT8_ACCURACY_FOCUSED", "INT8_INT16_MIXED", "INT8_INT16_MIXED_ACCURACY_FOCUSED", "FP16_STANDARD", "FP32_STANDARD"]`	支持量化的目标使用的量化或精度预设，例如 `INT8_STANDARD` 或 `FP16_STANDARD`。
`output_dir`	`str \| None`	保存转换模型的目录。如果未指定，模型将保存在当前工作目录。

YOLO 参数

这些参数仅在你转换 YOLO 模型时相关。

参数	类型	描述
`yolo_input_shape`	`list[int] \| None`	YOLO 模型的输入形状。
`yolo_version`	`str \| None`	可选的 YOLO 版本覆盖，例如 `"yolov8"`。如果省略，后端将尝试从 PyTorch 模型文件中自动检测版本。
`yolo_class_names`	`list[str] \| None`	模型的类别名称。

对于 YOLO 转换，你无需显式设置 yolo_version。如果省略，后端会尝试自动检测版本。PyTorch 模型文件仍然需要来自支持的 YOLO 版本之一。

RVC2 参数

特定于 RVC2 转换的参数。

参数	类型	描述
`mo_args`	`list[str] \| None`	传递给模型优化器的参数。
`compile_tool_args`	`list[str] \| None`	传递给 BLOB 编译器的参数。
`compress_to_fp16`	`bool`	是否将模型权重压缩为 FP16 精度。默认值为 `True`。
`number_of_shaves`	`int`	要使用的 SHAVE 数量。默认值为 `8`。
`superblob`	`bool`	是否创建超级 blob。默认值为 `True`。如果希望使用旧版 RVC2 blob 转换，请设为 `False`。

RVC4 参数

RVC4 转换专有的参数。

为 RVC4 进行转换时，请根据部署环境选择合适的 SNPE 版本。请参阅转换故障排除中的 SNPE 兼容性表。

参数	类型	描述
`snpe_onnx_to_dlc_args`	`list[str] \| None`	传递给 `snpe-onnx-to-dlc` 工具的参数。
`snpe_dlc_quant_args`	`list[str] \| None`	传递给 `snpe-dlc-quant` 工具的参数。
`snpe_dlc_graph_prepare_args`	`list[str] \| None`	传递给 `snpe-dlc-graph-prepare` 工具的参数。
`use_per_channel_quantization`	`bool`	是否使用逐通道量化。默认为 `True`。
`use_per_row_quantization`	`bool`	是否使用逐行量化。默认为 `False`。
`htp_socs`	`list[str] \| None`	要使用的 HTP SoC 列表。

转换调用还可以通过 name、model_id、variant_id、variant_version 和 input_shape 等参数创建或附加 Hub AI 资源。有关这些工作流及更广泛的 SDK 接口，请参阅HubAI SDK 页面。

命令行参考

也可以使用命令行界面进行转换。首先运行：

Command Line

1hubai login
2hubai convert RVC2 --path /path/to/model.onnx --name "my-model"

查看 hubai convert --help 获取完整选项列表。

从 BlobConverter 迁移

BlobConverter 是此前用于将模型转换为 BLOB 格式的库，适用于早期 OAK 工作流。它正被ModelConverter 和 HubAI SDK 取代，后者是未来支持的路径。blobconverter 仍可使用，但我们建议新项目使用 HubAI SDK。API 类似，但参数名称和执行方式存在差异。blobconverter 提供了多个函数用于从不同框架转换模型，例如 from_onnx、from_openvino 和 from_tf。这些函数在 HubAI SDK 中被 convert.RVC2 取代，后者接受一个指向模型输入的 path 参数。下表显示了 blobconverter 和 HubAI SDK 参数之间的映射关系。

`blobconverter`	`HubAI SDK`	备注
`model`	`path`	模型文件路径。
`xml`	`path`	XML 文件路径。仅适用于从 OpenVINO IR 转换。
`bin`	`opts["input_bin"]`	BIN 文件路径。仅适用于从 OpenVINO IR 转换。
`version`	`tool_version`	转换工具的版本。
`data_type`	`compress_to_fp16`	使用 `True` 表示 FP16 压缩权重，`False` 表示其他。`RVC2` 不使用 `quantization_mode`。
`shaves`	`number_of_shaves`	要使用的 SHAVE 数量。
`optimizer_params`	`mo_args`	传递给模型优化器的参数。
`compile_params`	`compile_tool_args`	传递给 BLOB 编译器的参数。

默认情况下，HubAI SDK 启用 superblob，该功能仅受 DepthAI v3 支持。如果要将模型转换为传统的 RVC2 BLOB 格式，请向 convert.RVC2 传递 superblob=False。

简单转换

使用 blobconverter 进行简单的 ONNX 转换

Python

1import blobconverter
2
3blob = blobconverter.from_onnx(
4    model="resnet18.onnx",
5)

使用 HubAI SDK 的等效代码

Python

1response = client.convert.RVC2(
2    path="resnet18.onnx",
3)
4
5blob = response.downloaded_path

从 OpenVINO IR 转换

blobconverter 示例

Python

1import blobconverter
2
3blob = blobconverter.from_openvino(
4    xml="resnet18.xml",
5    bin="resnet18.bin",
6)

HubAI SDK 示例

Python

1# 当 XML 和 BIN 文件位于同一位置时，只需指定 XML。
2response = client.convert.RVC2(path="resnet18.xml")
3blob = response.downloaded_path
4
5# 否则，可以使用 `opts` 参数指定 BIN 文件。
6response = client.convert.RVC2(
7    path="resnet18.xml",
8    opts={
9        "input_bin": "resnet18.bin",
10    },
11)
12blob = response.downloaded_path

从 TFLite 转换

HubAI 在线转换不支持从 frozen PB 文件进行转换。仅支持 TFLite 文件。

blobconverter 示例

Python

1import blobconverter
2
3blob = blobconverter.from_tf(
4    frozen_pb="resnet18.tflite",
5)

使用 HubAI SDK 的等效代码

Python

1response = client.convert.RVC2(
2    path="resnet18.tflite",
3)
4
5blob = response.downloaded_path

高级参数

带高级参数的 blobconverter.from_onnx

Python

1import blobconverter
2
3blob = blobconverter.from_onnx(
4    model="resnet18.onnx",
5    data_type="FP16",
6    version="2021.4",
7    shaves=6,
8    optimizer_params=[
9        "--mean_values=[127.5,127.5,127.5]",
10        "--scale_values=[255,255,255]",
11    ],
12    compile_params=["-ip U8"],
13)

使用 HubAI SDK 的等效代码

Python

1response = client.convert.RVC2(
2    path="resnet18.onnx",
3    tool_version="2021.4.0",
4    number_of_shaves=6,
5    mo_args=[
6        "mean_values=[127.5,127.5,127.5]",
7        "scale_values=[255,255,255]",
8    ],
9    compile_tool_args=["-ip", "U8"],
10)
11
12blob = response.downloaded_path

`Caffe` 转换

不支持从 Caffe 框架进行转换。

从 tools.luxonis.com 迁移

托管在 tools.luxonis.com 上的 Web 应用是我们转换 YOLO 目标检测模型的旧版应用程序。它正被 HubAI 在线转换所取代。与 Web 应用相比，HubAI 在线转换还支持实例分割、姿态估计、方向检测和分类 YOLO 模型。有关当前的转换能力，请参阅 HubAI 转换文档。以下是将现有 .pt 文件转换为兼容 RVC2 的 .superblob 的示例：

Python

1import os
2
3from hubai_sdk import HubAIClient
4
5client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
6
7converted_model = client.convert.RVC2(
8    path="yolov6n.pt",
9    yolo_version="yolov6r4",
10)

这利用我们的 Hub 云服务执行转换，并在任务完成时下载一个 .tar.xz 包。有关其他 YOLO 特定标志，请参阅 YOLO 参数部分。

本页目录

HubAI

概述

快速开始

Python API

通用参数

YOLO 参数

RVC2 参数

RVC4 参数

命令行参考

从 BlobConverter 迁移

简单转换

从 OpenVINO IR 转换

从 TFLite 转换

高级参数

Caffe 转换

从 tools.luxonis.com 迁移

`Caffe` 转换