此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 概述
  • 快速入门
  • Python API
  • 通用参数
  • YOLO 参数
  • RVC2 参数
  • RVC4 参数
  • CLI 参考
  • 从 BlobConverter 迁移
  • 简单转换
  • 从 OpenVINO IR 转换
  • 从 TFLite 转换
  • 高级参数
  • 转换
  • 从 tools.luxonis.com 迁移
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新

概述

HubAI 是 Luxonis 设备推荐的在线转换工作流程。它在云端运行 ModelConverter,并生成部署工件,无需本地转换器设置。本页面重点介绍在线转换的使用和从旧版工具的迁移。有关托管模型注册表工作流程和特定于平台的转换设置,请参阅 HubAI 转换 指南。有关 SDK 安装、身份验证以及模型、变体和实例 API,请参阅 HubAI SDK 文档。

快速入门

安装 hubai-sdk 并配置 HUBAI_API_KEY,如 HubAI SDK 页面所述,然后运行转换:
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 文档。

通用参数

适用于所有转换函数的通用参数。
参数类型描述
pathstr模型文件的路径。
tool_versionstr | None转换工具的版本。
quantization_modeLiteral["INT8_STANDARD", "INT8_ACCURACY_FOCUSED", "INT8_INT16_MIXED", "INT8_INT16_MIXED_ACCURACY_FOCUSED", "FP16_STANDARD", "FP32_STANDARD"]支持量化或精度预设的目标使用,例如 INT8_STANDARD 或 FP16_STANDARD。
output_dirstr | None保存转换后模型的目录。如果未指定,模型将保存在当前工作目录中。

YOLO 参数

这些参数仅在您转换 YOLO 模型时相关。
参数类型描述
yolo_input_shapelist[int] | NoneYOLO 模型的输入形状。
yolo_versionstr | None可选的 YOLO 版本覆盖,例如 "yolov8"。如果省略,后端会尝试从 PyTorch 模型文件中自动检测版本。
yolo_class_nameslist[str] | None模型的类名。
您无需为 YOLO 转换显式设置 yolo_version。如果省略,后端会尝试自动检测版本。PyTorch 模型文件仍需来自受支持的 YOLO 版本之一。

RVC2 参数

RVC2 转换特有的参数。
参数类型描述
mo_argslist[str] | None传递给模型优化器的参数。
compile_tool_argslist[str] | None传递给 BLOB 编译器的参数。
compress_to_fp16bool是否将模型的权重压缩为 FP16 精度。默认为 True。
number_of_shavesint要使用的 shaves 数量。默认为 8。
superblobbool是否创建 superblob。默认为 True。如果您想要旧版 RVC2 blob 转换,请使用 False。

RVC4 参数

RVC4 转换特有的参数。
参数类型描述
snpe_onnx_to_dlc_argslist[str] | None传递给 snpe-onnx-to-dlc 工具的参数。
snpe_dlc_quant_argslist[str] | None传递给 snpe-dlc-quant 工具的参数。
snpe_dlc_graph_prepare_argslist[str] | None传递给 snpe-dlc-graph-prepare 工具的参数。
use_per_channel_quantizationbool是否使用逐通道量化。默认为 True。
use_per_row_quantizationbool是否使用逐行量化。默认为 False。
htp_socslist[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 参数之间的映射。
blobconverterHubAI SDK注意事项
modelpath模型文件路径。
xmlpathXML 文件路径。仅用于从 OpenVINO IR 转换。
binopts["input_bin"]BIN 文件路径。仅用于从 OpenVINO IR 转换。
versiontool_version转换工具的版本。
data_typecompress_to_fp16对于 FP16 压缩权重使用 True,否则使用 False。RVC2 不使用 quantization_mode。
shavesnumber_of_shaves要使用的 shaves 数量。
optimizer_paramsmo_args传递给模型优化器的参数。
compile_paramscompile_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# 否则,可以使用 `opts` 参数指定 BIN 文件。
7response = client.convert.RVC2(
8    path="resnet18.xml",
9    opts={
10        "input_bin": "resnet18.bin",
11    },
12)
13blob = response.downloaded_path

从 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 参数 部分。