unionml.model.Model#
- class unionml.model.Model(name='model', init=None, *, dataset, hyperparameter_config=None)#
Initialize a UnionML Model.
The term UnionML Model refers to the specification of a model, which the user defines through the functional entrypoints, e.g.
unionml.model.Model.trainer()
. The term model object is used to refer to some instance of model from a machine learning framework such as the subclasses of theBaseEstimator
class in sklearn,Module
in pytorch, etc.- Parameters:
name (
str
) – name of the modelinit (
Union
[Type
,Callable
,None
]) – a class or callable that produces a model object (e.g. an sklearn estimator) when invoked.dataset (
Dataset
) – a UnionML Dataset object to bind to the model.hyperparameter_config (
Optional
[Dict
[str
,Type
]]) –A dictionary mapping hyperparameter names to types. This is used to determine the hyperparameter names and types associated with the model object produced by the
init
argument. For example:>>> { ... "hyperparameter1": int, ... "hyperparameter2": str, ... "hyperparameter3": float, ... }
Methods
Add a prediction schedule to the model.
Add a training schedule to the model.
Register a function for producing metrics for given model object.
Register a function for initializing a model object.
Load a model object from disk.
Load a model object from an environment variable pointing to the model file.
Register a function for deserializing a model object to disk.
Generate predictions locally.
Create a Flyte task for generating predictions from a model object.
Create a Flyte prediction workflow using raw features.
Create a Flyte task for generating predictions from a model object.
Create a Flyte prediction workflow using features from the
dataset.reader
as the data source.Register a function that generates predictions from a model object.
Configure the
unionml.Model
for remote backend deployment.Activate deployed schedules.
Deactivate deployed schedules.
Deploy model services to a Flyte backend.
Fetch predictions from a Flyte execution.
Fetch predictions from a Flyte execution.
Lists all the model versions of this UnionML app, in reverse chronological order.
Lists all the prediction ids of this UnionML app, in reverse chronological order.
Lists executions associated with a prediction schedule, sorted from most to least recent.
Lists executions associated with a training schedule, sorted from most to least recent.
Load a
ModelArtifact
based on the provided Flyte execution.Generate predictions on a remote Flyte backend.
Train a model object on a remote Flyte backend.
Wait for a
FlyteWorkflowExecution
to complete and returns the execution's output.Get a
ModelArtifact
from multiple sources.Save the model object to disk.
Register a function for serializing a model object to disk.
Schedule the prediction service when the UnionML app is deployed.
Schedule the training service when the UnionML app is deployed.
Create a FastAPI serving app.
Train a model object locally
Create a Flyte task for training a model object.
Create a Flyte training workflow for model object training.
Register a function for training a model object.
Attributes
Model artifact associated with the
unionml.Model
.Path to the config file associated with the Flyte backend.
Exposes the
unionml.Dataset
associated with the model.Path to Docker file used to package the UnionML app.
Hyperparameter type of the model object based on the
init
function signature.model_type
predict_callbacks
Name of the prediction workflow used to generate predictions from raw features.
Name of the prediction workflow used to generate predictions from the
dataset.reader
.Names of all the prediction schedules.
Scheduled prediction jobs.
prediction_type
Docker registry used to push UnionML app.
Name of the training workflow.
Parameters used to create a Flyte workflow for model object training.
Names of all the training schedules.
Scheduled training jobs.
- _default_loader(file, *args, **kwargs)#
Default model loader.
Supports
sklearn
estimators,pytorch
modules, andkeras
models.- Parameters:
- Return type:
The methods/functions for each associated model type are:
sklearn
estimators: joblib.loadpytorch
modules: torch.loadkeras
models: Model.load_model
- _default_saver(model_obj, hyperparameters, file, *args, **kwargs)#
Default model saver.
Supports
sklearn
estimators,pytorch
modules, andkeras
models.- Parameters:
model_obj (
Any
) – model object to serialize.hyperparameters (
Union
[dict
,BaseHyperparameters
,None
]) – hyperparameters associated with the model object.file (
Union
[str
,PathLike
,IO
]) – str, path-like, or file-like object to write the contents of the model object to.args – additional args to forward to the underlying serialization function.
kwargs – additional kwargs to forward to the underlying serialization function.
- Return type:
The methods/functions for each associated model type are:
sklearn
estimators: joblib.dumppytorch
modules: torch.savekeras
models: Model.save
- add_predictor_schedule(schedule)#
Add a prediction schedule to the model.
- Parameters:
schedule (
Schedule
) – schedule specification to add
- add_trainer_schedule(schedule)#
Add a training schedule to the model.
- Parameters:
schedule (
Schedule
) – schedule specification to add
- property artifact: Optional[ModelArtifact]#
Model artifact associated with the
unionml.Model
.This attribute is set when calling the following methods: -
train
-load
-load_from_env
-load_from_env
-remote_load
-remote_train
with thewait=True
kwarg.
- evaluator(fn)#
Register a function for producing metrics for given model object.
- property hyperparameter_type: Type#
Hyperparameter type of the model object based on the
init
function signature.
- init(fn)#
Register a function for initializing a model object.
- load(file, *args, **kwargs)#
Load a model object from disk.
- File:
a string or path-like object to load a model from.
- Parameters:
args – positional arguments forwarded to
unionml.Model.loader()
.kwargs – key-word arguments forwarded to
unionml.Model.loader()
.
- load_from_env(env_var='UNIONML_MODEL_PATH', *args, **kwargs)#
Load a model object from an environment variable pointing to the model file.
- Env_var:
environment variable referencing a path to load a model from.
- Parameters:
args – positional arguments forwarded to
unionml.Model.loader()
.kwargs – key-word arguments forwarded to
unionml.Model.loader()
.
- loader(fn)#
Register a function for deserializing a model object to disk.
- predict(features=None, **reader_kwargs)#
Generate predictions locally.
You can either pass this function raw features via the
features
argument or you can pass in keyword arguments that will be forwarded to theunionml.Dataset.reader()
method as the feature source.- Parameters:
features (
Optional
[Any
]) – Raw features that are pre-processed by the :py:class:unionml.Dataset
methods in the following order: -unionml.dataset.Dataset.feature_loader()
-unionml.dataset.Dataset.feature_transformer()
reader_kwargs – keyword arguments that correspond to the
unionml.Dataset.reader()
method signature.
- predict_from_features_task()#
Create a Flyte task for generating predictions from a model object.
This is used in the Flyte workflow produced by
predict_from_features_workflow
.
- predict_from_features_workflow()#
Create a Flyte prediction workflow using raw features.
- property predict_from_features_workflow_name#
Name of the prediction workflow used to generate predictions from raw features.
- predict_task()#
Create a Flyte task for generating predictions from a model object.
This is used in the Flyte workflow produced by
predict_workflow
.
- predict_workflow()#
Create a Flyte prediction workflow using features from the
dataset.reader
as the data source.
- property predict_workflow_name#
Name of the prediction workflow used to generate predictions from the
dataset.reader
.
- predictor(fn=None, callbacks=None, **predict_task_kwargs)#
Register a function that generates predictions from a model object.
This function is the primary entrypoint for defining your application’s prediction behavior.
See the User Guide for more.
- Parameters:
fn – function to use as the predictor.
train_task_kwargs – keyword arguments to pass into the flytekit task that will be composed of the input
fn
and functions defined in the boundDataset
.
- remote(registry=None, image_name=None, dockerfile='Dockerfile', patch_destination_dir='/root', config_file=None, project=None, domain=None)#
Configure the
unionml.Model
for remote backend deployment.- Parameters:
registry (
Optional
[str
]) – Docker registry used to push UnionML app.image_name (
Optional
[str
]) – image name to give to the Docker image associated with the UnionML app.dockerfile (
str
) – path to the Dockerfile used to package the UnionML app.patch_destination_dir (
str
) – path where the UnionML source is installed within the docker image, and in case of patch registration, this would be replaced. In Flyte terms, patch registration is often called fast-registration.config_file (
Optional
[str
]) – path to the flytectl config to use for deploying your UnionML app to a Flyte backend.project (
Optional
[str
]) – deploy your app to this Flyte project name.domain (
Optional
[str
]) – deploy your app to this Flyte domain name.
- remote_activate_schedules(app_version=None, schedule_names=None)#
Activate deployed schedules.
- remote_deactivate_schedules(app_version=None, schedule_names=None)#
Deactivate deployed schedules.
- remote_deploy(app_version=None, allow_uncommitted=False, patch=False, schedule=True)#
Deploy model services to a Flyte backend.
- Parameters:
app_version (
Optional
[str
]) – the version to use to deploy the UnionML app. If None, uses gitsha as the version.allow_uncommitted (
bool
) – If True, deploys uncommitted changes in the unionml project. Otherwise, raise a :py:class`~unionml.remote.VersionFetchError`patch (
bool
) – if True, this bypasses the Docker build process and only updates the UnionML app source code using the latest available image.schedule (
bool
) – indicates whether or not to deploy the training and prediction schedules.
- Return type:
- Returns:
app version string
- remote_fetch_model(execution)#
Fetch predictions from a Flyte execution.
- Parameters:
execution (
FlyteWorkflowExecution
) – a Flyte workflow execution, which is the output ofremote_predict(..., wait=False)
.- Return type:
- remote_fetch_predictions(execution)#
Fetch predictions from a Flyte execution.
- Parameters:
execution (
FlyteWorkflowExecution
) – a Flyte workflow execution, which is the output ofremote_predict(..., wait=False)
.- Return type:
- remote_list_model_versions(app_version=None, limit=10)#
Lists all the model versions of this UnionML app, in reverse chronological order.
- remote_list_prediction_ids(app_version=None, limit=10)#
Lists all the prediction ids of this UnionML app, in reverse chronological order.
Prediction ids are unique identifiers given to each batch prediction run that’s executed remotely on a Flyte cluster.
- remote_list_scheduled_prediction_runs(schedule_name, app_version=None, limit=5)#
Lists executions associated with a prediction schedule, sorted from most to least recent.
- Parameters:
- Return type:
- Returns:
a list of
FlyteWorkflowExecution
objects
- remote_list_scheduled_training_runs(schedule_name, app_version=None, limit=5)#
Lists executions associated with a training schedule, sorted from most to least recent.
- Parameters:
- Return type:
- Returns:
a list of
FlyteWorkflowExecution
objects
- remote_load(execution)#
Load a
ModelArtifact
based on the provided Flyte execution.- Parameters:
execution (
FlyteWorkflowExecution
) – a Flyte workflow execution, which is the output ofremote_train(..., wait=False)
.
- remote_predict(app_version=None, model_version=None, wait=True, *, features=None, **reader_kwargs)#
Generate predictions on a remote Flyte backend.
You can either pass this function raw features via the
features
argument or you can pass in keyword arguments that will be forwarded to theunionml.Dataset.reader()
method as the feature source.- Parameters:
app_version (
Optional
[str
]) – if provided, executes a prediction job using the specified UnionML app version. By default, this uses the latest app version deployed on the Flyte remote cluster.model_version (
Optional
[str
]) – if provided, executes a prediction job using the specified model version. By default, this uses the latest Flyte execution id as the model version.wait (
bool
) – if True, this is a synchronous operation, returning aModelArtifact
. Otherwise, this function returns aFlyteWorkflowExecution
.Raw features that are pre-processed by the :py:class:
unionml.Dataset
methods in the following order:reader_kwargs – keyword arguments that correspond to the
unionml.Dataset.reader()
method signature.
- Return type:
- Returns:
the predictions if wait is
True
, or aFlyteWorkflowExecution
object if wait isFalse
.
- remote_train(app_version=None, wait=True, *, hyperparameters=None, loader_kwargs=None, splitter_kwargs=None, parser_kwargs=None, trainer_kwargs=None, **reader_kwargs)#
Train a model object on a remote Flyte backend.
- Parameters:
app_version (
Optional
[str
]) – if provided, executes a training job using the specified UnionML app version. By default, this uses the latest app version deployed on the Flyte remote cluster.wait (
bool
) – if True, this is a synchronous operation, returning aModelArtifact
. Otherwise, this function returns aFlyteWorkflowExecution
.hyperparameters (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping hyperparameter names to values. This is passed into theinit
callable to initialize a model object.loader_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.loader()
function. This will override any defaults set in the function definition.splitter_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.splitter()
function. This will override any defaults set in the function definition.parser_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.parser()
function. This will override any defaults set in the function definition.trainer_kwargs (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping training parameter names to values. There training parameters are determined by the keyword-only arguments of themodel.trainer
function.reader_kwargs – keyword arguments that correspond to the
unionml.Dataset.reader()
method signature.
- Return type:
- Returns:
the trained model if wait is
True
, or aFlyteWorkflowExecution
object if wait isFalse
.
- remote_wait(execution, **kwargs)#
Wait for a
FlyteWorkflowExecution
to complete and returns the execution’s output.- Return type:
- resolve_model_artifact(model_object=None, model_version=None, app_version=None, model_file=None, loader_kwargs=None)#
Get a
ModelArtifact
from multiple sources.This method produces a model artifact from the following sources: - an in-memory
model_object
- a Flyte cluster execution viamodel_version
andapp_version
- a serialized model object viamodel_file
andloader_kwargs
If no arguments are provided, this method simply returns the
artifact
.- Parameters:
model –
Model
to use for resolving a model object.model_object (
Optional
[Any
]) – model object to use for prediction.model_version (
Optional
[str
]) – model version identifier to use for prediction.app_version (
Optional
[str
]) – ifmodel_version
is specified, this argument indicates the app version to use for fetching the model artifact.model_file (
Union
[str
,Path
,None
]) – a filepath to a serialized model object.loader_kwargs (
Optional
[dict
]) – additional keyword arguments to be forwarded to theunionml.model.Model.loader()
function.
- Return type:
- save(file, *args, **kwargs)#
Save the model object to disk.
- saver(fn)#
Register a function for serializing a model object to disk.
- schedule_prediction(name, *, expression=None, offset=None, fixed_rate=None, reader_time_arg=None, activate_on_deploy=True, launchplan_kwargs=None, model_object=None, model_version=None, app_version=None, model_file=None, loader_kwargs=None, **reader_kwargs)#
Schedule the prediction service when the UnionML app is deployed.
The model used for prediction must be from one of the following sources:
An in-memory model object specified via the
model_object
argument.A model version associated with a Flyte cluster execution speciied via the
model_version
andapp_version
arguments.A serialized model object specified via the
model_file
argument.
- Parameters:
name (
str
) – unique name of the launch planexpression (
Optional
[str
]) – a cron expression (see here) or valid croniter schedule for e.g. @hourly, @daily, @weekly, @monthly, @yearly (see here).offset (
Optional
[str
]) – duration to offset the schedule, must be a valid ISO 8601 duration <https://en.wikipedia.org/wiki/ISO_8601>__ . Only used if ``expression` is specified.fixed_rate (
Optional
[timedelta
]) – atimedelta
object representing fixed rate with which to run the workflow.reader_time_arg (
Optional
[str
]) – if notNone
, the name of thereader()
argument that will receive the kickoffdatetime
of the scheduled launchplan.activate_on_deploy (
bool
) – Whether or not to automatically activate this schedule on app deployment.launchplan_kwargs (
Optional
[dict
]) – additional keyword arguments to pass toLaunchPlan
model_object (
Optional
[Any
]) – model object to use for prediction.model_version (
Optional
[str
]) – model version identifier to use for prediction.app_version (
Optional
[str
]) – ifmodel_version
is specified, this argument indicates the app version to use for fetching the model artifact.model_file (
Union
[str
,Path
,None
]) – a filepath to a serialized model object.loader_kwargs (
Optional
[dict
]) – additional keyword arguments to be forwarded to theunionml.model.Model.loader()
function.reader_kwargs – keyword arguments that correspond to the
unionml.dataset.Dataset.reader()
method signature.
- schedule_training(name, *, expression=None, offset=None, fixed_rate=None, reader_time_arg=None, activate_on_deploy=True, launchplan_kwargs=None, hyperparameters=None, loader_kwargs=None, splitter_kwargs=None, parser_kwargs=None, trainer_kwargs=None, **reader_kwargs)#
Schedule the training service when the UnionML app is deployed.
- Parameters:
name (
str
) – unique name of the launch planexpression (
Optional
[str
]) – a cron expression (see here) or valid croniter schedule for e.g. @daily, @hourly, @weekly, @yearly (see here).offset (
Optional
[str
]) – duration to offset the schedule, must be a valid ISO 8601 duration <https://en.wikipedia.org/wiki/ISO_8601>__ . Only used if ``expression` is specified.fixed_rate (
Optional
[timedelta
]) – atimedelta
object representing fixed rate with which to run the workflow.reader_time_arg (
Optional
[str
]) – if notNone
, the name of thereader()
argument that will receive the kickoffdatetime
of the scheduled launchplan.activate_on_deploy (
bool
) – Whether or not to automatically activate this schedule on app deployment.launchplan_kwargs (
Optional
[dict
]) – additional keyword arguments to pass toLaunchPlan
hyperparameters (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping hyperparameter names to values. This is passed into theinit
callable to initialize a model object.loader_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.loader()
function. This will override any defaults set in the function definition.splitter_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.splitter()
function. This will override any defaults set in the function definition.parser_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.Dataset.parser()
function. This will override any defaults set in the function definition.trainer_kwargs (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping training parameter names to values. There training parameters are determined by the keyword-only arguments of themodel.trainer
function.reader_kwargs – keyword arguments that correspond to the
unionml.dataset.Dataset.reader()
method signature.
- serve(app, remote=False, app_version=None, model_version='latest')#
Create a FastAPI serving app.
- Parameters:
app (
FastAPI
) – AFastAPI
app to use for model serving.
- train(hyperparameters=None, loader_kwargs=None, splitter_kwargs=None, parser_kwargs=None, trainer_kwargs=None, **reader_kwargs)#
Train a model object locally
- Parameters:
hyperparameters (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping hyperparameter names to values. This is passed into theinit
callable to initialize a model object.loader_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.dataset.Dataset.loader()
function. This will override any defaults set in the function definition.splitter_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.dataset.Dataset.splitter()
function. This will override any defaults set in the function definition.parser_kwargs (
Optional
[Dict
[str
,Any
]]) – key-word arguments to pass to the registeredunionml.dataset.Dataset.parser()
function. This will override any defaults set in the function definition.trainer_kwargs (
Optional
[Dict
[str
,Any
]]) – a dictionary mapping training parameter names to values. There training parameters are determined by the keyword-only arguments of themodel.trainer
function.reader_kwargs – keyword arguments that correspond to the
unionml.Dataset.reader()
method signature.
- Return type:
The train method invokes an execution graph that composes together the following functions to train and evaluate a model:
unionml.Dataset.reader()
unionml.Dataset.loader()
unionml.Dataset.splitter()
unionml.Dataset.parser()
unionml.Model.trainer()
unionml.Model.predictor()
unionml.Model.evaluator()
- train_task()#
Create a Flyte task for training a model object.
This is used in the Flyte workflow produced by
train_workflow
.
- train_workflow()#
Create a Flyte training workflow for model object training.
- property train_workflow_name#
Name of the training workflow.
- trainer(fn=None, **train_task_kwargs)#
Register a function for training a model object.
This function is the primary entrypoint for defining your application’s model-training behavior.
See the User Guide for more.
- Parameters:
train_task_kwargs – keyword arguments to pass into the flytekit task that will be composed of the input
fn
and functions defined in the boundDataset
.