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`	是否创建 superblob。默认为 `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 页面。

CLI 参考

也可以使用命令行界面进行转换。从以下命令开始：

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 格式，请将 superblob=False 传递给 convert.RVC2。

简单转换

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

从 TFLite 转换

HubAI 在线转换不支持从冻结的 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 参数

CLI 参考

从 BlobConverter 迁移

简单转换

从 OpenVINO IR 转换

从 TFLite 转换

高级参数

Caffe 转换

从 tools.luxonis.com 迁移

`Caffe` 转换