# 在 HubAI 上使用自定义模型

本教程适合当您希望以最短路径将已准备并上传至 HubAI 的模型，在 OAK 设备上看到实际模型输出时使用。

> **注意：此工作流不要从 Viewer 开始**
> OAK Viewer 和默认可视化工具适用于尝试内置模型、检查流以及调整可视化或深度设置。它们不是验证自定义 HubAI 模型工作流的可编辑路径。为此，请从
> `oak-examples`
> 开始，这样您可以控制模型引用、认证和输出处理。

> **本教程的适用场景**
> 此流程最适合那些可通过
> `generic-example`
> 应用运行的模型：即具有兼容解析器路径的单图像输入模型。如果您的模型需要自定义后处理或多个输出头，请先使用本教程验证转换，然后转到自定义示例或应用。

## 1. 准备并上传模型

首先确保模型已准备好用于 HubAI 并已上传到模型注册表。

从 [模型准备](https://docs.luxonis.com/cloud/hubai/model-registry/preparation.md) 开始，以支持的格式准备模型文件和模型卡片。

然后按照 [上传/下载](https://docs.luxonis.com/cloud/hubai/model-registry/upload-download.md) 将模型添加到 HubAI。上传期间：

> **选择正确的上传格式**
> 对于自定义 YOLO 模型，请使用
> **YOLO**
> 上传路径配合
> **PyTorch**
> (
> `.pt`
> ) 权重。对于大多数其他自定义模型，请导出为
> **ONNX**
> 并使用
> **自定义**
> 上传路径。ONNX 是非 YOLO 模型的通用交换格式，通常保留原始架构，而 YOLO 特定路径则标准化输出以便原生解析和更多设备端后处理。更多详情请参见
> [转换为 ONNX](https://docs.luxonis.com/software-v3/ai-inference/conversion/onnx-conversion.md)
> 。

基础模型上传后，继续在模型注册表工作流中进行转换。

## 2. 在 HubAI 中转换模型

继续使用 [详细转换](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md) 将上传的模型转换为可部署的 RVC 输出，无需再次上传。

完成的转换步骤的输出包括：

 * 一个附加到现有 HubAI 模型条目的已转换模型实例
 * 一个可复制的 HubAI 模型引用，您可以将其传递给 generic-example

最简单的交接方式是将转换后的结果保留在模型注册表条目中，以便以后从 HubAI 或 oak-examples 引用它。

之后，从模型注册表页面复制模型引用，如 [上传/下载](https://docs.luxonis.com/cloud/hubai/model-registry/upload-download.md) 所示。

> **快速转换仍然可用**
> [快速转换](https://docs.luxonis.com/cloud/hubai/quick-conversion.md)
> 仍然适用于一次性任务，尤其是当您希望在一个地方上传、转换和下载模型时。在本教程中，它不是主要路径，因为模型已经上传到 HubAI。

## 3. 创建团队 API 密钥

如果模型是公开的，可以跳过此步骤。如果是团队拥有且私有的，请从 [API 密钥](https://docs.luxonis.com/cloud/api/api-keys.md) 创建密钥。

对于本地脚本，例如 generic-example，建议在运行时通过 DEPTHAI_HUB_API_KEY 设置密钥，而不是硬编码在源文件中。推荐的密钥处理模式记录在 [API
密钥良好实践](https://docs.luxonis.com/software-v3/oak-apps/apikey-good-practices.md) 中。

## 4. 运行 generic-example 并检查输出

[来自 oak-examples 的通用示例](https://github.com/luxonis/oak-examples/tree/main/neural-networks/generic-example) 是验证来自 HubAI
模型的最快可编辑路径。它期望通过 --model 传递一个 HubAI 模型引用，对于私有模型，它可以从 DEPTHAI_HUB_API_KEY 或 --api_key 读取密钥。

```bash
git clone --depth 1 --branch main https://github.com/luxonis/oak-examples.git
cd oak-examples/neural-networks/generic-example
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export DEPTHAI_HUB_API_KEY="<YOUR_TEAM_API_KEY>"
python3 main.py --model "<YOUR_MODEL_REFERENCE>"
```

在 Windows 上，使用 python 代替 python3，使用 venv\\Scripts\\activate 激活虚拟环境，并使用 set DEPTHAI_HUB_API_KEY=<YOUR_TEAM_API_KEY> 设置变量。

当脚本成功启动时，它会从 HubAI 下载模型，创建管道，并在本地可视化会话中提供查看器指令。使用该会话确认设备上的模型输出正确。

常见变体：

 * 添加 --overlay_mode 用于数组输出，例如分割或类似深度的地图。
 * 添加 --media_path <PATH_TO_IMAGE_OR_VIDEO> 如果您希望测试文件而不是实时相机输入。
 * 如果您不希望导出 DEPTHAI_HUB_API_KEY，可以传递 --api_key "<YOUR_TEAM_API_KEY>"。