# HubAI SDK

## 概述

[hubai-sdk](https://github.com/luxonis/hubai-sdk) 包提供了对 Luxonis Hub 的 [AI 与模型](https://docs.luxonis.com/cloud/hubai.md)
区域的程序化访问。您可以使用它来管理模型、变体和实例，或者从 Python 或命令行触发在线转换。

关键功能：

 * 管理 Hub AI 中的模型、变体和实例
 * 为 RVC2、RVC3、RVC4 和 Hailo 目标运行在线转换
 * 通过 Python 脚本或 hubai CLI 使用相同的工作流
 * 访问 Hub UI 中未公开的高级转换选项

> 如果您只需要转换工作流，请参阅
> [HubAI 在线转换指南](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md)
> 。

## 安装

该包适用于 Python 3.10 及以上版本。

```bash
pip install hubai-sdk
```

您也可以从源码安装：

```bash
git clone https://github.com/luxonis/hubai-sdk.git
cd hubai-sdk
pip install -e .
```

## 身份验证

在您的[团队设置](https://docs.luxonis.com/cloud/api/api-keys.md)中创建一个 API 密钥，然后将其暴露为环境变量：

```bash
export HUBAI_API_KEY="your-api-key"
```

在 Python 中初始化客户端：

```python
import os

from hubai_sdk import HubAIClient

client = HubAIClient(api_key=os.getenv("HUBAI_API_KEY"))
```

所有 SDK 工作流也可以通过 hubai CLI 使用。首先登录：

```bash
hubai login
```

## 快速开始

下面的示例展示了一个最小的端到端流程：列出几个模型并运行在线转换。

```python
models = client.models.list_models(limit=5)
print(f"Found {len(models)} models")

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

print(f"Converted model downloaded to: {response.downloaded_path}")
```

## 模型管理

[模型](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md)是 AI 与模型区域的基本元素，可以使用 HubAIClient.models
命名空间以编程方式进行管理。您可以列出模型、检索特定模型的信息、创建新模型、更新现有模型以及删除模型。

```python
# 列出模型
models = client.models.list_models(
    tasks=["OBJECT_DETECTION"],
    is_public=True,
    limit=10
)

# 获取模型信息
model = client.models.get_model("model-id-or-slug")

# 创建新模型
new_model = client.models.create_model(
    name="my-model",
    license_type="MIT",
    is_public=False,
    description="My awesome model",
    tasks=["OBJECT_DETECTION"]
)

# 更新现有模型（仅传递您想要更新的字段）
updated_model = client.models.update_model(
    new_model.id,
    license_type="Apache 2.0",
    description="Updated description"
)

# 删除模型
client.models.delete_model(new_model.id)
```

您将获得返回对象的完整类型提示，并且可以使用它们访问模型属性。

## 变体管理

[变体](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md)是模型的特定版本，通常通过输入分辨率（例如，224x224）、用于训练的数据集（例如，COCO）或模型架构中的一些较小变化来区分。

您可以列出变体、检索特定变体的信息、创建新变体以及删除变体。

```python
# 列出变体
variants = client.variants.list_variants(model_id="model-id")

# 获取变体信息
variant = client.variants.get_variant("variant-id")

new_variant = client.variants.create_variant(
    name="my-variant",
    model_id="model-id",
    variant_version="1.0.0",
    description="My first variant."
)

# 删除变体
client.variants.delete_variant("variant-id")
```

### 变体的新版本

您还可以创建变体的新版本。如果您有同一模型的更新权重，这会很有用。可以通过提供相同的变体名称、相同的模型 ID 和新的版本号来创建新版本。

```python
variant = client.variants.get_variant("variant-id")

new_version_of_variant = client.variants.create_variant(
    name=variant.name,
    model_id=variant.model_id,
    variant_version="new-version-number",
)
```

## 实例管理

[实例](https://docs.luxonis.com/cloud/hubai/model-registry/concepts.md)是变体的已编译、针对特定平台的版本——实际部署到硬件上的制品。有关转换为特定平台实例的更多信息，请参阅[转换](https://docs.luxonis.com/cloud/hubai/model-registry/detailed-conversion.md)指南。

您可以列出实例、获取特定实例的信息、创建新实例、下载实例、检索实例的文件和配置、上传文件到实例以及删除实例。

```python
# 列出实例
instances = client.instances.list_instances(model_id="model-id", variant_id="variant-id")

# 获取实例信息
instance = client.instances.get_instance("instance-id")

# 下载实例
downloaded_path = client.instances.download_instance("instance-id", output_dir="/path/to/output/directory")

# 创建新实例
from hubai_sdk.utils.types import ModelType

instance = client.instances.create_instance(
    name="my-instance",
    variant_id="variant-id",
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 288, 512]
)

# 检索实例的配置
config = client.instances.get_config("instance-id")

# 检索实例的文件
files = client.instances.get_files("instance-id")

# 上传文件到实例
client.instances.upload_file("path/to/nn_archive.tar.xz", "instance-id")

# 删除实例
client.instances.delete_instance("instance-id")
```

## 转换

您可以使用 HubAIClient.convert 命名空间将模型转换为不同格式。

```python
# 将模型转换为 RVC4 格式
response = client.convert.RVC4(
    path="/path/to/your/nn_archive.tar.xz",
    name="my-converted-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
)

downloaded_path = response.downloaded_path
instance = response.instance
```

这个简单的示例展示了如何将模型转换为 RVC4 格式，使用 INT8 精度和 GENERAL 量化数据。它还会创建一个名为 my-converted-model 的模型。转换完成后，转换后的模型会下载到 downloaded_path，并且模型实例会返回在
instance 变量中。

```python
# 将 YOLO 模型转换为 RVC4 格式
response = client.convert.RVC4(
    path="path/to/your/yolo-model.pt",
    name="my-converted-yolo-model",
    quantization_mode="INT8_STANDARD",
    quantization_data="GENERAL",
    yolo_input_shape=[512, 288],
    yolo_class_names=["list", "of", "class", "names"],
    yolo_version="yolov8",  # 可选覆盖
)
```

上面的示例演示了如何将 YOLO 模型转换为 RVC4 格式。您可以直接提供模型 .pt 权重文件的路径。必须指定模型的输入形状，并且可以选择包含类别名称。建议提供类别名称，否则在转换过程中会自动检索。您无需显式设置
yolo_version。如果省略，后端会尝试从 PyTorch 模型文件中自动检测版本，但文件仍需来自支持的 YOLO 版本之一。 SDK 当前暴露的显式 yolo_version
值包括：yolov5、yolov6r1、yolov6r3、yolov6r4、yolov7、yolov8、yolov9、yolov10、yolov11、yolov12、yolov26 和 goldyolo。 有关支持的 YOLO
系列、变体及当前限制的完整信息，请参阅上游的[受支持模型表](https://github.com/luxonis/tools?tab=readme-ov-file#-supported-models)。

有关在线转换的更多信息，请参阅 [Hub 在线转换](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/online/hubai.md) 指南。