概览硬件软件云平台
入门指南
车队管理
AI 与模型
教程
平台集成
组织
高级

本页目录

  • 概述
  • 安装
  • 身份验证
  • 快速开始
  • 模型管理
  • 变体管理
  • 变体的新版本
  • 实例管理
  • 转换

HubAI SDK

概述

hubai-sdk 包提供了对 Luxonis Hub 的 AI 与模型 区域的程序化访问。您可以使用它来管理模型、变体和实例，或者从 Python 或命令行触发在线转换。关键功能：
  • 管理 Hub AI 中的模型、变体和实例
  • 为 RVC2、RVC3、RVC4 和 Hailo 目标运行在线转换
  • 通过 Python 脚本或 hubai CLI 使用相同的工作流
  • 访问 Hub UI 中未公开的高级转换选项

安装

该包适用于 Python 3.10 及以上版本。
Command Line
1pip install hubai-sdk
您也可以从源码安装：
Command Line
1git clone https://github.com/luxonis/hubai-sdk.git
2cd hubai-sdk
3pip install -e .

身份验证

在您的团队设置中创建一个 API 密钥，然后将其暴露为环境变量：
Command Line
1export HUBAI_API_KEY="your-api-key"
在 Python 中初始化客户端：
Python
1import os
2
3from hubai_sdk import HubAIClient
4
5client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
所有 SDK 工作流也可以通过 hubai CLI 使用。首先登录：
Command Line
1hubai login

快速开始

下面的示例展示了一个最小的端到端流程：列出几个模型并运行在线转换。
Python
1models = client.models.list_models(limit=5)
2print(f"Found {len(models)} models")
3
4response = client.convert.RVC4(
5    path="path/to/model.onnx",
6    name="my-converted-model",
7)
8
9print(f"Converted model downloaded to: {response.downloaded_path}")

模型管理

模型是 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    new_model.id,
23    license_type="Apache 2.0",
24    description="Updated description"
25)
26
27# 删除模型
28client.models.delete_model(new_model.id)
您将获得返回对象的完整类型提示，并且可以使用它们访问模型属性。

变体管理

变体是模型的特定版本，通常通过输入分辨率（例如，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")

变体的新版本

您还可以创建变体的新版本。如果您有同一模型的更新权重，这会很有用。可以通过提供相同的变体名称、相同的模型 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)

实例管理

实例是变体的已编译、针对特定平台的版本——实际部署到硬件上的制品。有关转换为特定平台实例的更多信息，请参阅转换指南。您可以列出实例、获取特定实例的信息、创建新实例、下载实例、检索实例的文件和配置、上传文件到实例以及删除实例。
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    quantization_mode="INT8_STANDARD",
6    quantization_data="GENERAL",
7)
8
9downloaded_path = response.downloaded_path
10instance = response.instance
这个简单的示例展示了如何将模型转换为 RVC4 格式，使用 INT8 精度和 GENERAL 量化数据。它还会创建一个名为 my-converted-model 的模型。转换完成后，转换后的模型会下载到 downloaded_path，并且模型实例会返回在 instance 变量中。
Python
1# 将 YOLO 模型转换为 RVC4 格式
2response = client.convert.RVC4(
3    path="path/to/your/yolo-model.pt",
4    name="my-converted-yolo-model",
5    quantization_mode="INT8_STANDARD",
6    quantization_data="GENERAL",
7    yolo_input_shape=[512, 288],
8    yolo_class_names=["list", "of", "class", "names"],
9    yolo_version="yolov8",  # 可选覆盖
10)
上面的示例演示了如何将 YOLO 模型转换为 RVC4 格式。您可以直接提供模型 .pt 权重文件的路径。必须指定模型的输入形状，并且可以选择包含类别名称。建议提供类别名称，否则在转换过程中会自动检索。您无需显式设置 yolo_version。如果省略，后端会尝试从 PyTorch 模型文件中自动检测版本，但文件仍需来自支持的 YOLO 版本之一。 SDK 当前暴露的显式 yolo_version 值包括：yolov5、yolov6r1、yolov6r3、yolov6r4、yolov7、yolov8、yolov9、yolov10、yolov11、yolov12、yolov26 和 goldyolo。 有关支持的 YOLO 系列、变体及当前限制的完整信息，请参阅上游的受支持模型表。有关在线转换的更多信息，请参阅 Hub 在线转换 指南。