# HubAI

## 概述

HubAI 是适用于 Luxonis 设备的推荐在线转换工作流。它在云端运行
[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md)，无需本地转换器设置即可生成部署产物。

本页重点介绍在线转换的使用方法以及从旧工具的迁移。如需了解托管模型注册工作流和特定平台的转换设置，请参阅 [HubAI
转换](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) 指南。如需了解 SDK 安装、身份验证以及模型、变体和实例 API，请参阅 [HubAI
SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) 文档。

## 快速开始

安装 hubai-sdk 并按照 [HubAI SDK](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) 页面中的说明配置 HUBAI_API_KEY，然后运行转换：

```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)
```

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

## Python API

在线转换 API 位于 HubAIClient.convert 命名空间下。当目标固定时，请使用特定目标的辅助函数，例如 convert.RVC2 和 convert.RVC4。

如果你想以编程方式选择目标，还有一个通用的转换入口：

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

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

转换函数接受多个参数来指定模型和转换选项。这里列出主要参数以供入门，但有关确切的最新参数集，请参阅[完整 API
文档](https://github.com/luxonis/hubai-sdk/blob/main/docs/available_parameters.md)。

### 通用参数

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

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `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 兼容性表](https://docs.luxonis.com/software-v3/ai-inference/conversion/troubleshooting.md)
> 。

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| `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](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) 页面。

## 命令行参考

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

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

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

## 从 BlobConverter 迁移

[BlobConverter](https://pypi.org/project/blobconverter/) 是此前用于将模型转换为 BLOB 格式的库，适用于早期 OAK
工作流。它正被[ModelConverter](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter.md) 和
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
import blobconverter

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

使用 HubAI SDK 的等效代码

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

blob = response.downloaded_path
```

### 从 OpenVINO IR 转换

blobconverter 示例

```python
import blobconverter

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

HubAI SDK 示例

```python
# 当 XML 和 BIN 文件位于同一位置时，只需指定 XML。
response = client.convert.RVC2(path="resnet18.xml")
blob = response.downloaded_path

# 否则，可以使用 `opts` 参数指定 BIN 文件。
response = client.convert.RVC2(
    path="resnet18.xml",
    opts={
        "input_bin": "resnet18.bin",
    },
)
blob = response.downloaded_path
```

### 从 TFLite 转换

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

blobconverter 示例

```python
import blobconverter

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

使用 HubAI SDK 的等效代码

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

blob = response.downloaded_path
```

### 高级参数

带高级参数的 blobconverter.from_onnx

```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"],
)
```

使用 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 转换

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

## 从 tools.luxonis.com 迁移

托管在 [tools.luxonis.com](https://tools.luxonis.com/) 上的 Web 应用是我们转换 YOLO 目标检测模型的旧版应用程序。它正被 HubAI 在线转换所取代。

与 Web 应用相比，HubAI 在线转换还支持实例分割、姿态估计、方向检测和分类 YOLO 模型。有关当前的转换能力，请参阅 [HubAI
转换](https://docs.luxonis.com/cloud/hubai/model-registry/hubai-sdk.md) 文档。

以下是将现有 .pt 文件转换为兼容 RVC2 的 .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",
)
```

这利用我们的 Hub 云服务执行转换，并在任务完成时下载一个 .tar.xz 包。有关其他 YOLO 特定标志，请参阅 [YOLO
参数](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) 部分。