# instances

Python API: `hubai_sdk.services.instances`

管理具体的模型工件及其文件。

一个实例属于一个模型变体，代表一个特定的工件格式，例如 ONNX 输入或 RVC4 导出。该服务支持列出和创建实例、上传源文件、读取 NN Archive 配置以及下载输出文件。

 * `下载行为：`：[download_instance](/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/instances.md)
   写入与实例关联的所有文件。如果省略 `output_dir`，它将在当前工作目录中创建一个以实例 slug 命名的目录。除非 `force=True`，否则将重用现有目标文件。

> **示例**
> ```python
from hubai_sdk.utils.types import ModelType

instance = client.instances.create_instance(
    "network",
    variant_id=variant.id,
    model_type=ModelType.ONNX,
    input_shape=[1, 3, 640, 640],
)
client.instances.upload_file("network.onnx", instance.id)
```

> **注意**
> 大多数用户不需要手动创建和上传实例。[hubai_sdk.services.convert](/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/services/convert.md) 中的函数协调这些步骤以完成托管转换。

## 函数

### create_instance

```python
def create_instance(name: str, *, variant_id: UUID | str, model_type: ModelType, parent_id: UUID | str | None = None,
quantization_mode: QuantizationMode | None = None, quantization_data: QuantizationData | None = None, tags: list[str] | None =
None, input_shape: list[int] | None = None, is_deployable: bool | None = None, yolo_version: YoloVersion | None = None) ->
ModelInstanceResponse:
```

在变体下创建模型工件。

参数

 * `name` (`str`): 人类可读的实例名称。
 * `variant_id` (`UUID | str`): 拥有此实例的模型变体的 UUID。
 * `model_type` (`ModelType`): 源或导出的工件类型。
 * `parent_id` (`UUID | str | None`): 当此实例是导出时，源实例的 UUID。
 * `quantization_mode` (`QuantizationMode | None`): 模型的量化模式。必须是 `INT8_STANDARD`、`INT8_ACCURACY_FOCUSED`、`INT8_INT16_MIXED`、`INT8_INT16_MIXED_ACCURACY_FOCUSED` 或 `FP16_STANDARD` 之一。`INT8_STANDARD` 是标准的 INT8 量化，经过校准以获得最佳性能和模型大小。`INT8_ACCURACY_FOCUSED` 是 INT8 量化，经过校准，可能会提高准确性，而不会降低性能或增加模型大小，具体取决于模型。`INT8_INT16_MIXED` 在所有层中使用 8 位权重和 16 位激活，以提高数值稳定性和准确性，但会牺牲性能和模型大小。`INT8_INT16_MIXED_ACCURACY_FOCUSED` 是一种混合 INT8 和 INT16 基于校准的模式，它优先考虑准确性而不是吞吐量。`FP16_STANDARD` 是 FP16 量化，未经校准，适用于需要更高准确性和数值稳定性但会牺牲性能和模型大小的模型。
 * `quantization_data` (`QuantizationData | None`): 模型的量化数据。这可以是预定义域 `DRIVING`、`FOOD`、`GENERAL`、`INDOORS`、`RANDOM`、`WAREHOUSE`、`CLIP`、`CUSTOM` 或 `UNKNOWN` 之一，也可以是数据集 ID。对于转换助手，请传递本地 `.zip` 路径本身而不是 `CUSTOM`；SDK 在实例创建之前会规范化该输入。
 * `tags` (`list[str] | None`): 模型实例的标签。
 * `input_shape` (`list[int] | None`): 模型实例的输入形状。
 * `is_deployable` (`bool | None`): 模型实例是否可部署。
 * `yolo_version` (`YoloVersion | None`): 如果模型实例是 YOLO 模型，则为 YOLO 版本。

返回

 * `ModelInstanceResponse`: 创建的模型实例资源。

### create_instance_cli

```python
def create_instance_cli(name: str, *, variant_id: UUID | str, model_type: ModelType, parent_id: UUID | str | None = None,
quantization_mode: QuantizationMode | None = None, quantization_data: QuantizationData | None = None, tags: list[str] | None =
None, input_shape: list[int] | None = None, is_deployable: bool | None = None, yolo_version: YoloVersion | None = None):
```

创建新的模型实例。

### delete_instance

```python
def delete_instance(identifier: UUID | str):
```

从 HubAI 删除模型实例。

参数

 * `identifier` (`UUID | str`): 模型实例 ID、原始 slug 或确切的实例资源路径。

### delete_instance_cli

```python
def delete_instance_cli(identifier: UUID | str):
```

删除模型实例。

### download_instance

```python
def download_instance(identifier: UUID | str, output_dir: str | None = None, force: bool = False, model_type: ModelType | None =
None) -> Path:
```

下载附加到模型实例的每个文件。

参数

 * `identifier` (`UUID | str`): 当省略 `model_type` 时，要下载的实例的 ID、原始 slug 或 `<model>:<variant>:<instance-hash>` 资源路径，可选地以 `<team>/` 为前缀。当提供 `model_type` 时，模型版本 ID、原始模型版本 slug 或 `<model>:<variant>[:<version>]` 资源路径，可选地以 `<team>/` 为前缀，其实例应下载。
 * `output_dir` (`str | None`): 保存下载文件的目录路径。如果未指定，下载器将在当前工作目录下创建一个以模型实例 slug 命名的目录。
 * `force` (`bool`): 即使文件已存在，是否强制下载文件。
 * `model_type` (`ModelType | None`): 从已识别的变体中选择此类型的实例。匹配必须是唯一的。

返回

 * `Path`: 下载文件的路径。当实例有多个文件时，这是处理的最后一个文件。

引发

 * `ResourceNotFoundError`: 如果无法解析 `identifier`。
 * `InputError`: 如果提供了 `model_type` 并且没有实例或多个实例匹配它。
 * `HubApiError`: 如果实例没有文件或下载失败。

### download_instance_cli

```python
def download_instance_cli(identifier: UUID | str, output_dir: str | None = None, force: bool = False, model_type: ModelType | None
= None):
```

从模型实例下载文件。

### get_config

```python
def get_config(identifier: UUID | str) -> ArchiveConfigurationResponse:
```

返回模型实例的 NN Archive 配置。

参数

 * `identifier` (`UUID | str`): 模型实例 ID、原始 slug 或确切的实例资源路径。

返回

 * `ArchiveConfigurationResponse`: 模型实例的 NN 存档配置。

### get_config_cli

```python
def get_config_cli(identifier: UUID | str):
```

返回模型实例的配置。

### get_files

```python
def get_files(identifier: UUID | str) -> list[ModelInstanceFileResponse]:
```

返回附加到模型实例的文件的元数据。

参数

 * `identifier` (`UUID | str`): 模型实例 ID、原始 slug 或确切的实例资源路径。

返回

 * `list[ModelInstanceFileResponse]`: 模型实例的文件元数据。

### get_files_cli

```python
def get_files_cli(identifier: UUID | str):
```

返回模型实例的文件。

### get_instance

```python
def get_instance(identifier: UUID | str) -> ModelInstanceResponse:
```

通过 UUID、slug 或资源路径获取一个模型实例。

参数

 * `identifier` (`UUID | str`): 模型实例 ID、原始 slug 或 `<model>:<variant>:<instance-hash>` 资源路径，可选地以 `<team>/` 为前缀。

返回

 * `ModelInstanceResponse`: 解析的模型实例资源。

### get_instance_info_cli

```python
def get_instance_info_cli(identifier: UUID | str):
```

返回有关模型实例的信息。

### list_instances

```python
def list_instances(*, platforms: list[ModelType] | None = None, search: str | None = None, model_id: UUID | str | None = None,
variant_id: UUID | str | None = None, model_type: ModelType | None = None, parent_id: UUID | str | None = None, model_class:
ModelClass | None = None, name: str | None = None, hash: str | None = None, status: Status | None = None, is_public: bool | None =
None, compression_level: Literal[0, 1, 2, 3, 4, 5] | None = None, optimization_level: Literal[-100, 0, 1, 2, 3, 4] | None = None,
include_model_name: bool = False, limit: int = 50, sort: str = 'updated', order: Order = 'desc') -> list[ModelInstanceResponse]:
```

列出经过身份验证的团队可见的模型实例。

参数

 * `platforms` (`list[ModelType] | None`): 按平台筛选列出的模型实例。
 * `search` (`str | None`): 通过自由文本查询搜索列出的模型实例。
 * `model_id` (`UUID | str | None`): 按模型 ID 筛选列出的模型实例。
 * `variant_id` (`UUID | str | None`): 按变体 ID 筛选列出的模型实例。
 * `model_type` (`ModelType | None`): 按模型类型筛选列出的模型实例。
 * `parent_id` (`UUID | str | None`): 按父 ID 筛选列出的模型实例。
 * `model_class` (`ModelClass | None`): 按模型类筛选列出的模型实例。
 * `name` (`str | None`): 按名称筛选列出的模型实例。
 * `hash` (`str | None`): 按哈希筛选列出的模型实例。
 * `status` (`Status | None`): 按状态筛选列出的模型实例。
 * `is_public` (`bool | None`): 按可见性筛选列出的模型实例。
 * `compression_level` (`Literal[0, 1, 2, 3, 4, 5] | None`): 按压缩级别筛选列出的模型实例。仅与 Hailo 模型相关。
 * `optimization_level` (`Literal[-100, 0, 1, 2, 3, 4] | None`): 按优化级别筛选列出的模型实例。仅与 Hailo 模型相关。
 * `include_model_name` (`bool`): 如果为 `True`，则在响应中包含模型名称和模型变体名称。否则，[ModelInstanceResponse.model_name](/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) 和 [ModelInstanceResponse.model_variant_name](/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) 为 `None`。启用此功能会为每个结果执行两次额外的 API 请求。
 * `limit` (`int`): 要返回的模型实例的最大数量。
 * `sort` (`str`): 用于对模型实例进行排序的字段。它应该是 [ModelInstanceResponse](/cloud/hubai/model-registry/hubai-sdk/hubai-sdk-api-reference/utils/sdk_models.md) 中的字段名称，例如 `"name"`、`"id"` 或 `"updated"`。
 * `order` (`Order`): 排序顺序。必须是 `"asc"` 或 `"desc"`。

返回

 * `list[ModelInstanceResponse]`: 匹配的模型实例资源列表。

### list_instances_cli

```python
def list_instances_cli(*, platforms: list[ModelType] | None = None, search: str | None = None, model_id: UUID | str | None = None,
variant_id: UUID | str | None = None, model_type: ModelType | None = None, parent_id: UUID | str | None = None, model_class:
ModelClass | None = None, name: str | None = None, hash: str | None = None, status: Status | None = None, is_public: bool | None =
None, compression_level: Literal[0, 1, 2, 3, 4, 5] | None = None, optimization_level: Literal[-100, 0, 1, 2, 3, 4] | None = None,
include_model_name: bool = False, limit: int = 50, sort: str = 'updated', order: Order = 'desc', field: Annotated[list[str] |
None, Parameter(name=['--field', '-f'])] = None):
```

列出 HubAI 中的模型实例。

### upload_file

```python
def upload_file(file_path: str, identifier: UUID | str):
```

将文件直接上传到模型实例的存储。

此函数通过首先从服务器获取签名上传策略，然后将文件直接上传到云存储来启动异步上传。

参数

 * `file_path` (`str`): 要上传的文件的路径。
 * `identifier` (`UUID | str`): 模型实例 ID、原始 slug 或确切的实例资源路径。

引发

 * `FileNotFoundError`: 如果 `file_path` 不存在。
 * `ResourceNotFoundError`: 如果无法解析 `identifier`。
 * `HubApiError`: 如果签名上传或其异步作业失败。

### upload_file_cli

```python
def upload_file_cli(file_path: str, identifier: UUID | str):
```

使用异步上传将文件上传到模型实例。

### upload_quantization_zip

```python
def upload_quantization_zip(file_path: str, job_id: UUID | str):
```

为导出作业上传自定义校准存档。

参数

 * `file_path` (`str`): 包含校准输入的本地 ZIP 存档的路径。
 * `job_id` (`UUID | str`): HubAI 返回的导出作业 UUID。

引发

 * `FileNotFoundError`: 如果 `file_path` 不存在。
 * `InputError`: 如果文件没有 `.zip` 扩展名。
 * `HubApiError`: 如果 HubAI 无法发出或完成上传。

## 属性

### app

### INSTANCE_INFO_KEYS

### INSTANCE_LIST_KEYS

### INSTANCE_LIST_KEYS_WITH_MODEL
