instances
最后更新
hubai_sdk.services.instances管理具体的模型工件及其文件。一个实例属于一个模型变体,代表一个特定的工件格式,例如 ONNX 输入或 RVC4 导出。该服务支持列出和创建实例、上传源文件、读取 NN Archive 配置以及下载输出文件。下载行为::download_instance 写入与实例关联的所有文件。如果省略output_dir,它将在当前工作目录中创建一个以实例 slug 命名的目录。除非force=True,否则将重用现有目标文件。
示例
Python
1from hubai_sdk.utils.types import ModelType
2
3instance = client.instances.create_instance(
4 "network",
5 variant_id=variant.id,
6 model_type=ModelType.ONNX,
7 input_shape=[1, 3, 640, 640],
8)
9client.instances.upload_file("network.onnx", instance.id)注意
大多数用户不需要手动创建和上传实例。hubai_sdk.services.convert 中的函数协调这些步骤以完成托管转换。
函数
create_instance
Python
1def 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
1def 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
1def delete_instance(identifier: UUID | str):identifier(UUID | str): 模型实例 ID、原始 slug 或确切的实例资源路径。
delete_instance_cli
Python
1def delete_instance_cli(identifier: UUID | str):download_instance
Python
1def 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
1def download_instance_cli(identifier: UUID | str, output_dir: str | None = None, force: bool = False, model_type: ModelType | None = None):get_config
Python
1def get_config(identifier: UUID | str) -> ArchiveConfigurationResponse:identifier(UUID | str): 模型实例 ID、原始 slug 或确切的实例资源路径。
ArchiveConfigurationResponse: 模型实例的 NN 存档配置。
get_config_cli
Python
1def get_config_cli(identifier: UUID | str):get_files
Python
1def get_files(identifier: UUID | str) -> list[ModelInstanceFileResponse]:identifier(UUID | str): 模型实例 ID、原始 slug 或确切的实例资源路径。
list[ModelInstanceFileResponse]: 模型实例的文件元数据。
get_files_cli
Python
1def get_files_cli(identifier: UUID | str):get_instance
Python
1def get_instance(identifier: UUID | str) -> ModelInstanceResponse:identifier(UUID | str): 模型实例 ID、原始 slug 或<model>:<variant>:<instance-hash>资源路径,可选地以<team>/为前缀。
ModelInstanceResponse: 解析的模型实例资源。
get_instance_info_cli
Python
1def get_instance_info_cli(identifier: UUID | str):list_instances
Python
1def 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 和 ModelInstanceResponse.model_variant_name 为None。启用此功能会为每个结果执行两次额外的 API 请求。limit(int): 要返回的模型实例的最大数量。sort(str): 用于对模型实例进行排序的字段。它应该是 ModelInstanceResponse 中的字段名称,例如"name"、"id"或"updated"。order(Order): 排序顺序。必须是"asc"或"desc"。
list[ModelInstanceResponse]: 匹配的模型实例资源列表。
list_instances_cli
Python
1def 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):upload_file
Python
1def 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
1def upload_file_cli(file_path: str, identifier: UUID | str):upload_quantization_zip
Python
1def 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 无法发出或完成上传。