Skip to content

Reference for hub_sdk/modules/models.py

Note

This file is available at https://github.com/ultralytics/hub-sdk/blob/main/hub_sdk/modules/models.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!


hub_sdk.modules.models.Models

Models(
    model_id: Optional[str] = None, headers: Optional[Dict[str, Any]] = None
)

Bases: CRUDClient

A class representing a client for interacting with Models through CRUD operations. This class extends the CRUDClient class and provides specific methods for working with Models.

Attributes:

NameTypeDescription
base_endpointstr

The base endpoint URL for the API, set to "models".

hub_clientModelUpload

An instance of ModelUpload used for interacting with model uploads.

id(str, None)

The unique identifier of the model, if available.

datadict

A dictionary to store model data.

metrics

Placeholder for storing model metrics, if available after retrieval.

Note

The 'id' attribute is set during initialization and can be used to uniquely identify a model. The 'data' attribute is used to store model data fetched from the API.

Parameters:

NameTypeDescriptionDefault
model_idstr

The unique identifier of the model.

None
headersdict

Headers to be included in API requests.

None
Source code in hub_sdk/modules/models.py
def __init__(self, model_id: Optional[str] = None, headers: Optional[Dict[str, Any]] = None):
    """
    Initialize a Models instance.

    Args:
        model_id (str, optional): The unique identifier of the model.
        headers (dict, optional): Headers to be included in API requests.
    """
    self.base_endpoint = "models"
    super().__init__(self.base_endpoint, "model", headers)
    self.hub_client = ModelUpload(headers)
    self.id = model_id
    self.data = {}
    self.metrics = None
    if model_id:
        self.get_data()

create_model

create_model(model_data: dict) -> None

Creates a new model with the provided data and sets the model ID for the current instance.

Parameters:

NameTypeDescriptionDefault
model_datadict

A dictionary containing the data for creating the model.

required

Returns:

TypeDescription
None

The method does not return a value.

Source code in hub_sdk/modules/models.py
def create_model(self, model_data: dict) -> None:
    """
    Creates a new model with the provided data and sets the model ID for the current instance.

    Args:
        model_data (dict): A dictionary containing the data for creating the model.

    Returns:
        (None): The method does not return a value.
    """
    try:
        response = super().create(model_data)

        if response is None:
            self.logger.error("Received no response from the server while creating the model.")
            return

        # Ensuring the response object has the .json() method
        if not hasattr(response, "json"):
            self.logger.error("Invalid response object received while creating the model.")
            return

        resp_data = response.json()
        if resp_data is None:
            self.logger.error("No data received in the response while creating the model.")
            return

        self.id = resp_data.get("data", {}).get("id")

        # Check if the ID was successfully retrieved
        if not self.id:
            self.logger.error("Model ID not found in the response data.")
            return

        self.get_data()

    except Exception as e:
        self.logger.error(f"An error occurred while creating the model: {str(e)}")

delete

delete(hard: bool = False) -> Optional[Response]

Delete the model resource represented by this instance.

Parameters:

NameTypeDescriptionDefault
hardbool

If True, perform a hard (permanent) delete.

False
Note

The 'hard' parameter determines whether to perform a soft delete (default) or a hard delete. In a soft delete, the model might be marked as deleted but retained in the system. In a hard delete, the model is permanently removed from the system.

Returns:

TypeDescription
Optional[Response]

Response object from the delete request, or None if delete fails.

Source code in hub_sdk/modules/models.py
def delete(self, hard: bool = False) -> Optional[Response]:
    """
    Delete the model resource represented by this instance.

    Args:
        hard (bool, optional): If True, perform a hard (permanent) delete.

    Note:
        The 'hard' parameter determines whether to perform a soft delete (default) or a hard delete.
        In a soft delete, the model might be marked as deleted but retained in the system.
        In a hard delete, the model is permanently removed from the system.

    Returns:
        (Optional[Response]): Response object from the delete request, or None if delete fails.
    """
    return super().delete(self.id, hard)

export

export(format: str) -> Optional[Response]

Export to Ultralytics HUB.

Args: format (str): Export format here. Here are supported export formats

Returns:

TypeDescription
Optional[Response]

Response object from the export request, or None if export fails.

Source code in hub_sdk/modules/models.py
def export(self, format: str) -> Optional[Response]:
    """
    Export to Ultralytics HUB.

    Args: format (str): Export format here. Here are supported export [formats](
    https://docs.ultralytics.com/modes/export/#export-formats)

    Returns:
        (Optional[Response]): Response object from the export request, or None if export fails.
    """
    return self.hub_client.export(self.id, format)  # response

get_architecture

get_architecture() -> Optional[str]

Get the architecture name of the model.

Returns:

TypeDescription
Optional[str]

The architecture name followed by '.yaml' or None if not available.

Source code in hub_sdk/modules/models.py
def get_architecture(self) -> Optional[str]:
    """
    Get the architecture name of the model.

    Returns:
        (Optional[str]): The architecture name followed by '.yaml' or None if not available.
    """
    return self.data.get("cfg")

get_data

get_data() -> None

Retrieves data for the current model instance.

If a valid model ID has been set, it sends a request to fetch the model data and stores it in the instance. If no model ID has been set, it logs an error message.

Returns:

TypeDescription
None

The method does not return a value.

Source code in hub_sdk/modules/models.py
def get_data(self) -> None:
    """
    Retrieves data for the current model instance.

    If a valid model ID has been set, it sends a request to fetch the model data and stores it in the instance.
    If no model ID has been set, it logs an error message.

    Returns:
        (None): The method does not return a value.
    """
    if not self.id:
        self.logger.error("No model id has been set. Update the model id or create a model.")
        return

    try:
        response = super().read(self.id)

        if response is None:
            self.logger.error(f"Received no response from the server for model ID: {self.id}")
            return

        # Check if the response has a .json() method (it should if it's a response object)
        if not hasattr(response, "json"):
            self.logger.error(f"Invalid response object received for model ID: {self.id}")
            return

        resp_data = response.json()
        if resp_data is None:
            self.logger.error(f"No data received in the response for model ID: {self.id}")
            return

        data = resp_data.get("data", {})
        self.data = self._reconstruct_data(data)
        self.logger.debug(f"Model data retrieved for ID: {self.id}")

    except Exception as e:
        self.logger.error(f"An error occurred while retrieving data for model ID: {self.id}, {str(e)}")

get_dataset_url

get_dataset_url() -> Optional[str]

Get the dataset URL associated with the model.

Returns:

TypeDescription
Optional[str]

The URL of the dataset or None if not available.

Source code in hub_sdk/modules/models.py
def get_dataset_url(self) -> Optional[str]:
    """
    Get the dataset URL associated with the model.

    Returns:
        (Optional[str]): The URL of the dataset or None if not available.
    """
    return self.data.get("data")

get_metrics

get_metrics() -> Optional[List[Dict[str, Any]]]

Get metrics to of model.

Returns:

TypeDescription
(list(dict), optional)

The list of metrics objects, or None if it fails.

Source code in hub_sdk/modules/models.py
def get_metrics(self) -> Optional[List[Dict[str, Any]]]:
    """
    Get metrics to of model.

    Returns:
        (list(dict), optional): The list of metrics objects, or None if it fails.
    """
    if self.metrics:
        return self.metrics

    endpoint = f"{HUB_API_ROOT}/v1/{self.base_endpoint}/{self.id}/metrics"
    try:
        results = self.get(endpoint)
        self.metrics = results.json().get("data")
        return self.metrics
    except Exception as e:
        self.logger.error(f"Model Metrics not found: {e}")

get_weights_url

get_weights_url(weight: str = 'best') -> Optional[str]

Get the URL of the model weights.

Parameters:

NameTypeDescriptionDefault
weightstr

Type of weights to retrieve.

'best'

Returns:

TypeDescription
Optional[str]

The URL of the specified weights or None if not available.

Source code in hub_sdk/modules/models.py
def get_weights_url(self, weight: str = "best") -> Optional[str]:
    """
    Get the URL of the model weights.

    Args:
        weight (str, optional): Type of weights to retrieve.

    Returns:
        (Optional[str]): The URL of the specified weights or None if not available.
    """
    if weight == "last":
        return self.data.get("resume")

    return self.data.get("weights")

has_best_weights

has_best_weights() -> bool

Check if the model has best weights saved.

Returns:

TypeDescription
bool

True if best weights available, False otherwise.

Source code in hub_sdk/modules/models.py
def has_best_weights(self) -> bool:
    """
    Check if the model has best weights saved.

    Returns:
        (bool): True if best weights available, False otherwise.
    """
    return self.data.get("has_best_weights", False)

is_custom

is_custom() -> bool

Check if the model is custom.

Returns:

TypeDescription
bool

True if custom, False otherwise.

Source code in hub_sdk/modules/models.py
def is_custom(self) -> bool:
    """
    Check if the model is custom.

    Returns:
        (bool): True if custom, False otherwise.
    """
    return self.data.get("is_custom", False)

is_pretrained

is_pretrained() -> bool

Check if the model is pretrained.

Returns:

TypeDescription
bool

True if pretrained, False otherwise.

Source code in hub_sdk/modules/models.py
def is_pretrained(self) -> bool:
    """
    Check if the model is pretrained.

    Returns:
        (bool): True if pretrained, False otherwise.
    """
    return self.data.get("is_pretrained", False)

is_resumable

is_resumable() -> bool

Check if the model training can be resumed.

Returns:

TypeDescription
bool

True if resumable, False otherwise.

Source code in hub_sdk/modules/models.py
def is_resumable(self) -> bool:
    """
    Check if the model training can be resumed.

    Returns:
        (bool): True if resumable, False otherwise.
    """
    return self.data.get("has_last_weights", False)

is_trained

is_trained() -> bool

Check if the model is trained.

Returns:

TypeDescription
bool

True if trained, False otherwise.

Source code in hub_sdk/modules/models.py
def is_trained(self) -> bool:
    """
    Check if the model is trained.

    Returns:
        (bool): True if trained, False otherwise.
    """
    return self.data.get("status") == "trained"

predict

predict(image: str, config: Dict[str, Any]) -> Optional[Response]

Predict to Ultralytics HUB.

Parameters:

NameTypeDescriptionDefault
imagestr

The path to the image file.

required
configdict

A configuration for the prediction (JSON).

required

Returns:

TypeDescription
Optional[Response]

Response object from the predict request, or None if upload fails.

Source code in hub_sdk/modules/models.py
def predict(self, image: str, config: Dict[str, Any]) -> Optional[Response]:
    """
    Predict to Ultralytics HUB.

    Args:
        image (str): The path to the image file.
        config (dict): A configuration for the prediction (JSON).

    Returns:
        (Optional[Response]): Response object from the predict request, or None if upload fails.
    """
    return self.hub_client.predict(self.id, image, config)  # response

start_heartbeat

start_heartbeat(interval: int = 60)

Starts sending heartbeat signals to a remote hub server.

This method initiates the sending of heartbeat signals to a hub server in order to indicate the continued availability and health of the client.

Parameters:

NameTypeDescriptionDefault
intervalint

The time interval, in seconds, between consecutive heartbeats.

60

Returns:

TypeDescription
None

The method does not return a value.

Note

Heartbeats are essential for maintaining a connection with the hub server and ensuring that the client remains active and responsive.

Source code in hub_sdk/modules/models.py
def start_heartbeat(self, interval: int = 60):
    """
    Starts sending heartbeat signals to a remote hub server.

    This method initiates the sending of heartbeat signals to a hub server
    in order to indicate the continued availability and health of the client.

    Args:
        interval (int): The time interval, in seconds, between consecutive heartbeats.

    Returns:
        (None): The method does not return a value.

    Note:
        Heartbeats are essential for maintaining a connection with the hub server
        and ensuring that the client remains active and responsive.
    """
    self.hub_client._register_signal_handlers()
    self.hub_client._start_heartbeats(self.id, interval)

stop_heartbeat

stop_heartbeat() -> None

Stops sending heartbeat signals to a remote hub server.

This method terminates the sending of heartbeat signals to the hub server, effectively signaling that the client is no longer available or active.

Returns:

TypeDescription
None

The method does not return a value.

Note

Stopping heartbeats should be done carefully, as it may result in the hub server considering the client as disconnected or unavailable.

Source code in hub_sdk/modules/models.py
def stop_heartbeat(self) -> None:
    """
    Stops sending heartbeat signals to a remote hub server.

    This method terminates the sending of heartbeat signals to the hub server,
    effectively signaling that the client is no longer available or active.

    Returns:
        (None): The method does not return a value.

    Note:
        Stopping heartbeats should be done carefully, as it may result in the hub server
        considering the client as disconnected or unavailable.
    """
    self.hub_client._stop_heartbeats()

update

update(data: dict) -> Optional[Response]

Update the model resource represented by this instance.

Parameters:

NameTypeDescriptionDefault
datadict

The updated data for the model resource.

required

Returns:

TypeDescription
Optional[Response]

Response object from the update request, or None if update fails.

Source code in hub_sdk/modules/models.py
def update(self, data: dict) -> Optional[Response]:
    """
    Update the model resource represented by this instance.

    Args:
        data (dict): The updated data for the model resource.

    Returns:
        (Optional[Response]): Response object from the update request, or None if update fails.
    """
    return super().update(self.id, data)

upload_metrics

upload_metrics(metrics: dict) -> Optional[Response]

Upload model metrics to Ultralytics HUB.

Parameters:

NameTypeDescriptionDefault
metricsdict
required

Returns:

TypeDescription
Optional[Response]

Response object from the upload metrics request, or None if it fails.

Source code in hub_sdk/modules/models.py
def upload_metrics(self, metrics: dict) -> Optional[Response]:
    """
    Upload model metrics to Ultralytics HUB.

    Args:
        metrics (dict):

    Returns:
        (Optional[Response]): Response object from the upload metrics request, or None if it fails.
    """
    return self.hub_client.upload_metrics(self.id, metrics)  # response

upload_model

upload_model(
    epoch: int,
    weights: str,
    is_best: bool = False,
    map: float = 0.0,
    final: bool = False,
) -> Optional[Response]

Upload a model checkpoint to Ultralytics HUB.

Parameters:

NameTypeDescriptionDefault
epochint

The current training epoch.

required
weightsstr

Path to the model weights file.

required
is_bestbool

Indicates if the current model is the best one so far.

False
mapfloat

Mean average precision of the model.

0.0
finalbool

Indicates if the model is the final model after training.

False

Returns:

TypeDescription
Optional[Response]

Response object from the upload request, or None if upload fails.

Source code in hub_sdk/modules/models.py
def upload_model(
    self,
    epoch: int,
    weights: str,
    is_best: bool = False,
    map: float = 0.0,
    final: bool = False,
) -> Optional[Response]:
    """
    Upload a model checkpoint to Ultralytics HUB.

    Args:
        epoch (int): The current training epoch.
        weights (str): Path to the model weights file.
        is_best (bool): Indicates if the current model is the best one so far.
        map (float): Mean average precision of the model.
        final (bool): Indicates if the model is the final model after training.

    Returns:
        (Optional[Response]): Response object from the upload request, or None if upload fails.
    """
    return self.hub_client.upload_model(self.id, epoch, weights, is_best=is_best, map=map, final=final)





hub_sdk.modules.models.ModelList

ModelList(page_size=None, public=None, headers=None)

Bases: PaginatedList

Provides a paginated list interface for managing and querying models from the Ultralytics HUB API.

Parameters:

NameTypeDescriptionDefault
page_sizeint

The number of items to request per page.

None
publicbool

Whether the items should be publicly accessible.

None
headersdict

Headers to be included in API requests.

None
Source code in hub_sdk/modules/models.py
def __init__(self, page_size=None, public=None, headers=None):
    """
    Initialize a ModelList instance.

    Args:
        page_size (int, optional): The number of items to request per page.
        public (bool, optional): Whether the items should be publicly accessible.
        headers (dict, optional): Headers to be included in API requests.
    """
    base_endpoint = "models"
    super().__init__(base_endpoint, "model", page_size, public, headers)