Skip to content

hsml.model #

Model #

NOT_FOUND_ERROR_CODE class-attribute instance-attribute #

NOT_FOUND_ERROR_CODE = 360000

Metadata object representing a model in the Model Registry.

created property writable #

Creation date of the model.

creator property writable #

Creator of the model.

description property writable #

Description of the model.

environment property writable #

Input example of the model.

framework property writable #

Framework of the model.

id property writable #

Id of the model.

input_example property writable #

input_example of the model.

missing_mandatory_tags property #

missing_mandatory_tags: list[dict[str, Any]]

Mandatory tags configured for models that this model is missing.

Populated from the backend response. Empty when all mandatory model tags are set.

model_files_path property #

Path of the model files including version and files folder.

Resolves to /Projects/{project_name}/Models/{name}/{version}/Files.

model_path property #

Path of the model with version folder omitted.

Resolves to /Projects/{project_name}/Models/{name}.

model_registry_id property writable #

model_registry_id of the model.

model_schema property writable #

Model schema of the model.

name property writable #

Name of the model.

program property writable #

Executable used to export the model.

project_name property writable #

project_name of the model.

shared_registry_project_name property writable #

shared_registry_project_name of the model.

training_metrics property writable #

Training metrics of the model.

user property writable #

User of the model.

version property writable #

Version of the model.

version_path property #

Path of the model including version folder.

Resolves to /Projects/{project_name}/Models/{name}/{version}.

add_tag #

add_tag(name: str, value: Any)

Attach a tag to a model.

A tag consists of a pair. Tag names are unique identifiers across the whole cluster. The value of a tag can be any valid json - primitives, arrays or json objects.

PARAMETER DESCRIPTION
name

Name of the tag to be added.

TYPE: str

value

Value of the tag to be added.

TYPE: Any

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to add the tag.

clear_cache staticmethod #

clear_cache(
    project_name: str | None = None,
    model_name: str | None = None,
    version: int | None = None,
) -> int

Clear cached downloaded models.

Utility method to clear the model cache from every fallback location (temp dir, the Hopsworks home .cache, and the working directory). Use this to free disk space when cached models are no longer needed.

The filters narrow from broad to specific: model_name requires project_name, and version requires both project_name and model_name.

PARAMETER DESCRIPTION
project_name

If specified, only clear cache for this project. If None, clears all cached models.

TYPE: str | None DEFAULT: None

model_name

If specified (requires project_name), only clear cache for this specific model. If None, clears all models in project.

TYPE: str | None DEFAULT: None

version

If specified (requires project_name and model_name), only clear cache for this specific model version. If None, clears all versions.

TYPE: int | None DEFAULT: None

RETURNS DESCRIPTION
int

Number of model versions removed from cache.

RAISES DESCRIPTION
ValueError

If model_name is given without project_name, or version is given without both project_name and model_name.

Example
# Clear all cached models
Model.clear_cache()

# Clear all models for a specific project
Model.clear_cache(project_name="my_project")

# Clear all versions of a specific model
Model.clear_cache(project_name="my_project", model_name="my_model")

# Clear a specific model version
Model.clear_cache(project_name="my_project", model_name="my_model", version=1)

create_model_monitoring #

create_model_monitoring(
    name: str,
    description: str | None = None,
    start_date_time: int | str | None = None,
    end_date_time: int | str | None = None,
    cron_expression: str | None = "0 0 12 ? * * *",
) -> FeatureMonitoringConfig

Create a model monitoring config for this model.

Resolves this model's parent feature view via provenance and delegates to feature_view.create_model_monitoring with this model's name and version already filled in. The resulting config targets the FV's logging feature group, filters by this model + version, and defaults the reference training dataset to the version that was used to train the model.

Experimental

Public API is subject to change, this feature is not suitable for production use-cases.

Example
mr = project.get_model_registry()
my_model = mr.get_model("my_model", version=1)

my_model.create_model_monitoring(
    name="psi_drift",
).with_detection_window(
    time_offset="1d", window_length="1d",
).with_reference_training_dataset(  # defaults to model's TD version
).compare_on_distribution(
    feature_name="amount", metric="PSI", threshold=0.2,
).save()
PARAMETER DESCRIPTION
name

Name of the feature monitoring configuration.

TYPE: str

description

Description of the feature monitoring configuration.

TYPE: str | None DEFAULT: None

start_date_time

Start date and time from which to start computing statistics.

TYPE: int | str | None DEFAULT: None

end_date_time

End date and time at which to stop computing statistics.

TYPE: int | str | None DEFAULT: None

cron_expression

Cron expression scheduling the FM job (UTC, Quartz).

TYPE: str | None DEFAULT: '0 0 12 ? * * *'

RAISES DESCRIPTION
hopsworks.client.exceptions.FeatureStoreException

If this model has no parent feature view recorded in its provenance, or if downstream FV validation fails (no logging enabled, no recorded TD version, ...).

RETURNS DESCRIPTION
FeatureMonitoringConfig

A FeatureMonitoringConfig builder. Call with_detection_window,

FeatureMonitoringConfig

with_reference_*, compare_on / compare_on_distribution,

FeatureMonitoringConfig

and save() to register it.

delete #

delete()

Delete the model.

Potentially dangerous operation

This operation drops all metadata associated with this version of the model and deletes the model files.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case the backend encounters an issue

delete_tag #

delete_tag(name: str)

Delete a tag attached to a model.

PARAMETER DESCRIPTION
name

Name of the tag to be removed.

TYPE: str

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to delete the tag.

deploy #

deploy(
    name: str | None = None,
    description: str | None = None,
    artifact_version: str | None = None,
    serving_tool: str | None = None,
    script_file: str | None = None,
    config_file: str | None = None,
    resources: PredictorResources | dict | None = None,
    inference_logger: InferenceLogger | dict | None = None,
    inference_batcher: InferenceBatcher
    | dict
    | None = None,
    scaling_configuration: PredictorScalingConfig
    | dict
    | None = None,
    transformer: Transformer | dict | None = None,
    api_protocol: str | None = IE.API_PROTOCOL_REST,
    environment: str | None = None,
    env_vars: dict | None = None,
    vllm_variant: str | None = None,
    vllm_image_tag: str | None = None,
    tags: tag.Tag
    | dict[str, Any]
    | list[tag.Tag | dict[str, Any]]
    | None = None,
    schema: DeploymentSchema | dict | None = None,
    passed_features: list[str] | None = None,
    default_predictor: bool | None = None,
    knative_mode: bool | None = None,
) -> deployment.Deployment

Deploy the model.

A Python model registered with a feature view and deployed without a script gets the library's default predictor: requests carry serving keys, passed features, and request parameters as described by deployment.schema, the predictor looks up and transforms the feature vector, runs the model, and logs the request when the feature view has logging enabled.

Example
import hopsworks

project = hopsworks.login()

# get Hopsworks Model Registry handle
mr = project.get_model_registry()

# retrieve the trained model you want to deploy
my_model = mr.get_model("my_model", version=1)

my_deployment = my_model.deploy()

# a Python model registered with feature_view= deploys without a
# predictor script; clients send the serving keys and passed features
fraud_model = mr.get_model("fraud", version=1)
fraud_deployment = fraud_model.deploy(passed_features=["amount"])
fraud_deployment.start(await_running=600)
fraud_deployment.schema.describe()
fraud_deployment.predict(
    inputs=[{"cc_num": 4473593503484549, "amount": 12.5}]
)
PARAMETER DESCRIPTION
name

Name of the deployment.

TYPE: str | None DEFAULT: None

description

Description of the deployment.

TYPE: str | None DEFAULT: None

artifact_version

Deprecated. Version number of the model artifact to deploy, CREATE to create a new model artifact or MODEL-ONLY to reuse the shared artifact containing only the model files.

TYPE: str | None DEFAULT: None

serving_tool

Serving tool used to deploy the model server.

TYPE: str | None DEFAULT: None

script_file

Path to a custom predictor script implementing the Predict class, either local or already uploaded to HopsFS.

TYPE: str | None DEFAULT: None

config_file

Model server configuration file to be passed to the model deployment, either local or already uploaded to HopsFS. It can be accessed via CONFIG_FILE_PATH environment variable from a predictor or transformer script. For LLM deployments without a predictor script, this file is used to configure the vLLM engine.

TYPE: str | None DEFAULT: None

resources

Resources to be allocated for the predictor.

TYPE: PredictorResources | dict | None DEFAULT: None

inference_logger

Inference logger configuration.

TYPE: InferenceLogger | dict | None DEFAULT: None

inference_batcher

Inference batcher configuration.

TYPE: InferenceBatcher | dict | None DEFAULT: None

scaling_configuration

Scaling configuration for the predictor.

TYPE: PredictorScalingConfig | dict | None DEFAULT: None

transformer

Transformer to be deployed together with the predictor.

TYPE: Transformer | dict | None DEFAULT: None

api_protocol

API protocol to be enabled in the deployment (i.e., 'REST' or 'GRPC').

TYPE: str | None DEFAULT: IE.API_PROTOCOL_REST

environment

The inference environment to use.

TYPE: str | None DEFAULT: None

env_vars

Environment variables to set on the predictor.

TYPE: dict | None DEFAULT: None

vllm_variant

vLLM image variant for vLLM deployments. One of 'VLLM' or 'VLLM_OMNI'. Ignored for non-vLLM model servers.

TYPE: str | None DEFAULT: None

vllm_image_tag

vLLM image tag override. If set, it must be one of the tags ModelServing.get_vllm_image_tags returns for the matching vllm_variant; the two variants advertise different tags, and an unqualified call lists the standard vLLM ones. On a new deployment, None selects the newest advertised tag of that variant. On an update, None means "unchanged": the deployment keeps its current tag, so moving it to the cluster default takes naming that tag explicitly. A deployment also keeps its tag after an admin stops advertising it. Ignored for non-vLLM model servers.

TYPE: str | None DEFAULT: None

tags

Optionally the tags to attach to the deployment when it is created, in the same shapes accepted by feature groups. A single Tag, a {"name": "owner", "value": "team-a"} dict, or a list of either, for example [{"name": "owner", "value": "team-a"}]. The tags ride the create request, so any mandatory deployment tags missing from them cause the backend to reject the creation.

TYPE: tag.Tag | dict[str, Any] | list[tag.Tag | dict[str, Any]] | None DEFAULT: None

schema

Deployment schema describing the prediction requests. Inferred from the feature view when the default predictor is used; a given schema must then keep the inferred fields and may only refine types and descriptions.

TYPE: DeploymentSchema | dict | None DEFAULT: None

passed_features

Feature view features whose values clients send with each request instead of the online store providing them. Only with the default predictor.

TYPE: list[str] | None DEFAULT: None

default_predictor

None selects the default predictor automatically for Python models with a feature view and no script, True requires it (also for sklearn models, and together with a script_file that subclasses it), False never uses it.

TYPE: bool | None DEFAULT: None

knative_mode

Whether to deploy in KServe Knative mode. None (default) lets the backend decide: LLM (vLLM) deployments default to Standard, every other deployment defaults to Knative mode; on an update, None keeps the deployment's current mode. Standard mode does not scale to zero (minimum one instance). It autoscales on a CPU or memory metric between min_instances and max_instances (default: CPU at 80% up to the cluster maximum), and runs a fixed replica count without autoscaler when min_instances == max_instances (the default for LLM deployments).

TYPE: bool | None DEFAULT: None

RETURNS DESCRIPTION
deployment.Deployment

The deployment metadata object of a new or existing deployment.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case the backend encounters an issue

download #

download(local_path: str | None = None) -> str

Download the model files.

If local_path is not provided, the model is downloaded to a cache directory under /tmp/hopsworks/models/{project_name}/{model_name}/{version}/{id}/ and reused across subsequent downloads, including across processes. Cached models persist beyond program exit. The cache path includes the backend model id, so a model version that is deleted and recreated is re-downloaded automatically without manual cache invalidation. If the temp location is unusable (disk full, read-only, or no permission), the download falls back to ~/.hopsworks/cache/models and then the current working directory. Use Model.clear_cache to reclaim disk space.

PARAMETER DESCRIPTION
local_path

path where to download the model files in the local filesystem. If None, downloads to cache directory (recommended for idempotent reuse).

TYPE: str | None DEFAULT: None

RETURNS DESCRIPTION
str

Absolute path to local folder containing the model files.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case the backend encounters an issue

get_feature_view #

get_feature_view(
    init: bool = True, online: bool = False
) -> feature_view.FeatureView | None

Get the parent feature view of this model, based on explicit provenance.

Only accessible, usable feature view objects are returned. Otherwise an Exception is raised. For more details, call the base method - get_feature_view_provenance

PARAMETER DESCRIPTION
init

By default this is set to True. If you require a more complex initialization of the feature view for online or batch scenarios, you should set init to False to retrieve a non initialized feature view and then call init_batch_scoring() or init_serving() with the required parameters.

TYPE: bool DEFAULT: True

online

By default this is set to False and the initialization for batch scoring is considered the default scenario. If you set online to True, the online scenario is enabled and the init_serving() method is called. When inside a deployment, the only available scenario is the online one, thus the parameter is ignored and init_serving is always called (if init is set to True). If you want to override this behaviour, you should set init to False and proceed with a custom initialization.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
feature_view.FeatureView | None

Feature View Object or None if it does not exist.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to retrieve the feature view.

get_feature_view_provenance #

get_feature_view_provenance() -> explicit_provenance.Links

Get the parent feature view of this model, based on explicit provenance.

This feature view can be accessible, deleted or inaccessible. For deleted and inaccessible feature views, only a minimal information is returned.

RETURNS DESCRIPTION
explicit_provenance.Links

Object containing the section of provenance graph requested or None if it does not exist.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to retrieve the feature view provenance.

get_monitoring_configs #

get_monitoring_configs() -> list[FeatureMonitoringConfig]

Get the feature monitoring configurations for this model version.

Example
import hopsworks

project = hopsworks.login()

mr = project.get_model_registry()
my_model = mr.get_model("my_model", version=1)

fm_configs = my_model.get_monitoring_configs()
RETURNS DESCRIPTION
list[FeatureMonitoringConfig]

List of FeatureMonitoringConfig objects for this model version.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case the backend encounters an issue.

get_tag #

get_tag(name: str) -> Any | None

Get the value of a tag attached to a model.

PARAMETER DESCRIPTION
name

Name of the tag to get.

TYPE: str

RETURNS DESCRIPTION
Any | None

tag value, or None if it does not exist.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to retrieve the tag.

get_tags #

get_tags() -> dict[str, Any]

Retrieve all tags attached to a model.

RETURNS DESCRIPTION
dict[str, Any]

Dictionary of tag name/values.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case of a server error.

get_training_dataset_provenance #

get_training_dataset_provenance() -> (
    explicit_provenance.Links
)

Get the parent training dataset of this model, based on explicit provenance.

This training dataset can be accessible, deleted or inaccessible. For deleted and inaccessible training datasets, only a minimal information is returned.

RETURNS DESCRIPTION
explicit_provenance.Links

Object containing the section of provenance graph requested or None if it does not exist.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

in case the backend fails to retrieve the training dataset provenance.

get_url #

get_url()

Get url to the model in Hopsworks.

save #

save(
    model_path: str,
    await_registration: int = 480,
    keep_original_files: bool = False,
    upload_configuration: dict[str, Any] | None = None,
) -> Model

Persist this model including model files and metadata to the model registry.

PARAMETER DESCRIPTION
model_path

Local or remote (Hopsworks file system) path to the folder where the model files are located, or path to a specific model file.

TYPE: str

await_registration

Awaiting time for the model to be registered in Hopsworks.

TYPE: int DEFAULT: 480

keep_original_files

If the model files are located in hopsfs, whether to move or copy those files into the Models dataset. Default is False (i.e., model files will be moved)

TYPE: bool DEFAULT: False

upload_configuration

When saving a model from outside Hopsworks, the model is uploaded to the model registry using the REST APIs. Each model artifact is divided into chunks and each chunk uploaded independently. This parameter can be used to control the upload chunk size, the parallelism and the number of retries. upload_configuration can contain the following keys: * key chunk_size: size of each chunk in megabytes. Default 10. * key simultaneous_uploads: number of chunks to upload in parallel. Default 3. * key max_chunk_retries: number of times to retry the upload of a chunk in case of failure. Default 1.

TYPE: dict[str, Any] | None DEFAULT: None

RETURNS DESCRIPTION
Model

The model metadata object.

RAISES DESCRIPTION
hopsworks.client.exceptions.RestAPIError

In case the backend encounters an issue

set_tag #

set_tag(name: str, value: Any)

Deprecated: Use add_tag instead.

PARAMETER DESCRIPTION
name

name of the tag

TYPE: str

value

value of the tag

TYPE: Any