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

本页目录

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

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"找到 {len(models)} 个模型")
3
4response = client.convert.RVC4(
5    path="path/to/model.onnx",
6    name="my-converted-model",
7)
8
9print(f"转换后的模型已下载到：{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="我的模型很棒",
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="更新的描述"
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="我的第一个变体。"
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)

实例管理

实例 是 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    quantization_mode="INT8_STANDARD",
6    quantization_data="GENERAL",
7)
8
9downloaded_path = response.downloaded_path
10instance = response.instance
这个简单的示例展示了如何使用 GENERAL 量化数据以 INT8 精度将模型转换为 RVC4 格式。它还将创建一个名为 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 在线转换 指南。