概览硬件软件云平台
此页面由 AI 自动翻译。查看英文原版
Hub 控制
舰队管理
Luxonis HubAI
平台集成
组织
高级

本页目录

  • Overview
  • Installation
  • Quick Start
  • Installation
  • Authentication
  • Model Management
  • Variant Management
  • New Verison of the Variant
  • 实例管理
  • 转换

Models SDK

Overview

hubai-sdk 包是一个 Python 库，用于以编程方式与 Luxonis Hub 的 AI 和模型 区域进行交互。它能够直接从您的 Python 代码或命令行自动化模型管理和转换工作流。主要特点：
  • 以编程方式访问模型、变体和实例
  • 自动将模型转换为 RVC2、RVC3、RVC4 和 Hailo 格式
  • 用于所有操作的命令行界面
  • 支持类型提示的类型安全 Python API
  • 支持 Python 脚本和 CLI 工作流

Installation

该包托管在 PyPI 上，因此您可以使用 pip 进行安装：
Command Line
1pip install hubai-sdk

Quick Start

要使用此 SDK，您首先需要从 Hub 获取 API 密钥。您可以通过注册免费帐户并在设置中生成 API 密钥来完成此操作。
Python
1import os
2from hubai_sdk import HubAIClient
3
4client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
5
6# 列出所有模型
7models = client.models.list_models()
8print(f"找到 {len(models)} 个模型")
9
10# 获取特定模型
11model = client.models.get_model(models[0].id)
12print(f"模型：{model.name}")
13
14# 将模型转换为 RVC4 格式（适用于 OAK4 设备）
15response = client.convert.RVC4(
16    path="/path/to/your/nn_archive.tar.xz",
17    name="my-converted-model",
18    target_precision="INT8",
19    quantization_data="GENERAL",
20)
21
22print(f"转换后的模型已下载到：{response.downloaded_path}")
您还可以使用 hubai 命令从命令行运行所有命令。
Command Line
1# 先登录
2hubai login
3
4# 列出模型
5hubai model ls
6
7# 获取模型信息
8hubai model info <model-id-or-slug>
9
10# 将模型转换为 RVC4 格式
11hubai convert rvc4 <path-to-nn-archive.tar.xz> --name my-converted-model --target-precision INT8 --quantization-data GENERAL

Installation

该包适用于 Python 3.10 及更高版本，可以使用 pip 进行安装：
Command Line
1pip install hubai-sdk
此外，您还可以从源代码安装该包：
Command Line
1git clone https://github.com/luxonis/hubai-sdk.git
2cd hubai-sdk
3pip install -e .

Authentication

要使用此 SDK，您需要在 Hub 上创建一个帐户，并在您的 团队设置 中生成 API 密钥。获得 API 密钥后，您可以将其设置为环境变量：

Model Management

模型 是 AI 和模型区域的基本元素，可以使用 HubAIClient.models 命名空间以编程方式进行管理。您可以列出模型、检索特定模型的相关信息、创建新模型、更新现有模型以及删除模型。
Python
1# 列出模型
2models = client.models.list_models(
3    tasks=["OBJECT_DETECTION"],
4    is_public=True,
5    limit=10
6)
7
8# 获取模型信息
9model = client.models.get_model("model-id-or-slug")
10
11# 创建一个新模型
12new_model = client.models.create_model(
13    name="my-model",
14    license_type="MIT",
15    is_public=False,
16    description="My awesome model",
17    tasks=["OBJECT_DETECTION"]
18)
19
20# 更新现有模型（仅传递要更新的字段）
21updated_model = client.models.update_model(
22    model_id,
23    license_type="Apache 2.0",
24    description="Updated description"
25)
26
27# 删除模型
28client.models.delete_model(model_id)
您拥有返回对象的完整类型提示，并可以使用它们来访问模型属性。

Variant Management

变体 是模型的特定版本，通常根据输入分辨率（例如 224x224）、用于训练的数据集（例如 COCO）或模型架构的一些较小变体来区分。您可以列出变体、检索特定变体的相关信息、创建新变体以及删除变体。
Python
1# 列出变体
2variants = client.variants.list_variants(model_id="model-id")
3
4# 获取变体信息
5variant = client.variants.get_variant("variant-id")
6
7new_variant = client.variants.create_variant(
8    name="my-variant",
9    model_id="model-id",
10    variant_version="1.0.0",
11    description="My first variant."
12)
13
14# 删除变体
15client.variants.delete_variant("variant-id")

New Verison of the Variant

您还可以创建变体的新版本。如果您有较新的模型权重，这将非常有用。可以通过提供相同的变体名称、相同的模型 ID 和新的版本号来创建新版本。
Python
1variant = client.variants.get_variant("variant-id")
2
3new_version_of_variant = client.variants.create_variant(
4    name=variant.name,
5    model_id=variant.model_id,
6    variant_version="new-version-number",
7)

实例管理

Instance 是 Variant 的已编译、面向平台的版本——实际部署到硬件的工件。有关转换为特定于平台的实例的更多信息，请参阅 转换 指南。您可以列出实例、检索有关特定实例的信息、创建新实例、下载实例、检索实例的文件和配置、将文件上传到实例以及删除实例。
Python
1# 列出实例
2instances = client.instances.list_instances(model_id="model-id", variant_id="variant-id")
3
4# 获取实例信息
5instance = client.instances.get_instance("instance-id")
6
7# 下载实例
8downloaded_path = client.instances.download_instance("instance-id", output_dir="/path/to/output/directory")
9
10# 创建新实例
11from hubai_sdk.utils.types import ModelType
12
13instance = client.instances.create_instance(
14    name="my-instance",
15    variant_id="variant-id",
16    model_type=ModelType.ONNX,
17    input_shape=[1, 3, 288, 512]
18)
19
20# 检索实例的配置
21config = client.instances.get_config("instance-id")
22
23# 检索实例的文件
24files = client.instances.get_files("instance-id")
25
26# 将文件上传到实例
27client.instances.upload_file("path/to/nn_archive.tar.xz", "instance-id")
28
29# 删除实例
30client.instances.delete_instance("instance-id")

转换

您可以使用 HubAIClient.convert 命名空间将模型转换为不同的格式。
Python
1# 将模型转换为 RVC4 格式
2response = client.convert.RVC4(
3    path="/path/to/your/nn_archive.tar.xz",
4    name="my-converted-model",
5    target_precision="INT8",
6    quantization_data="GENERAL",
7)
8
9downloaded_path = response.downloaded_path
10instance = response.instance
这个简单的示例展示了如何使用 INT8 精度和 GENERAL 量化数据将模型转换为 RVC4 格式。它还将创建一个名为 my-converted-model 的模型。转换完成后，转换后的模型将下载到 downloaded_path，并且 Model Instance 将在 instance 变量中返回。
Python
1# 将 YOLO 模型转换为 RVC4 格式
2response = client.convert.RVC4(
3    path="path/to/your/yolo-model.pt",
4    name="my-converted-yolo-model",
5    target_precision="INT8",
6    quantization_data="GENERAL",
7    yolo_input_shape=[512, 288],
8    yolo_class_names=["list", "of", "class", "names"],
9    yolo_version="yolov8",  # 或任何其他 YOLO 版本
10)
上面的示例演示了如何将 YOLO 模型转换为 RVC4 格式。您可以直接提供模型 .pt 权重文件的路径。必须指定模型的输入形状，并且可以包含类名。建议提供类名，否则在转换过程中将自动检索它们。 当前支持的系列包括 YOLOv5、YOLOv6、YOLOv7、YOLOv8、YOLOv9、YOLOv10、YOLO11、YOLO12、YOLO26、YOLOE 和 Gold-YOLO。 有关支持的 YOLO 系列、变体以及当前限制的确切列表，请参阅上游 支持的模型表。有关在线转换的更多信息，请参阅 Hub 在线转换 指南。