create_workspace
Method to get an existing workspace.
create_compute
Method to create a new compute or obtain an existing compute.
create_environment
Method to create a new environment or obtain an existing environment.
Method to get an existing workspace.
create_workspace(workspace_args)
workspace_args (dict) Accepted workspace_args dictionary keyworded arguments:
A dictionary of keyword args to get an existing workspace.
Workspace
Example: Getting the existing workspace
workspace=create_workspace(workspace_args={"subscription_id": <subscription_id>,
"resource_group": <resource_group>,
"workspace_name": <workspace_name>
}
)
Method to create a new compute or obtain an existing compute
create_compute(workspace,compute_type,compute_args)
workspace (azureml.core.Workspace):
Assigns an existing Workspace object.
compute_type (str):
Type of compute to be created. The following compute_type are supported:
-
'AmlComputeCluster'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.AmlCompute'. -
'AmlComputeInstance'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.ComputeInstance'. -
'AKS'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.aks'.
compute_args (dict) Accepted compute_args dictionary keyworded arguments:
A dictionary of keyword args to create a new Compute or get an existing Compute.
Compute
Example: Creation of a new compute with compute_type 'AmlComputeCluster'
compute=create_compute(workspace=<workspace-object>,
compute_type='AmlComputeCluster',
compute_args={'vm_size':'Standard_D12_v2',
'vm_priority':'lowpriority',
'compute_name':<compute-name>,
'min_nodes':0,
'max_nodes':4,
}
)
Example: Creation of a new compute with compute_type 'AmlComputeInstance'
compute=create_compute(workspace=<workspace-object>,
compute_type='AmlComputeInstance',
compute_args={
'vm_size':"Standard_D3_v2",
'compute_name':<compute-name>
}
)
Example: Creation of a new compute with compute_type 'AKS'
compute=create_compute(workspace=<workspace-object>,
compute_type='AKS',
compute_args={'compute_name':<compute-name>})
Method to create a new environment or obtain an existing environment
create_environment(workspace,environment_type,environment_args)
workspace (azureml.core.Workspace):
Assigns an existing Workspace object.
environment_type (str):
Specifies the method of creating an environment.The following environment_type are supported:
'CondaPackageEnvironment'for creating a new Environment or obtaining an existing environment by specifying pip, conda and private wheel dependency.'CondaSpecificationEnvironment'for creating a new Environment or obtaining an existing environment by passing a conda dependency file and private wheel dependency.
environment_args (dict) Accepted environment_args dictionary keyworded arguments:
A dictionary of keyword args to create a new Environment or get an existing Environment.
Environment
Example1: Creation of new Environment with environment_type 'CondaPackageEnvironment'
environment=create_environment(workspace=workspace,
environment_type='CondaPackageEnvironment',
environment_args={'name':<environment-name>,
'conda_packages':['scikit-learn'],
'pip_packages':['fedml_azure']}
)
Example2: Creation of new Environment with environment_type 'CondaSpecificationEnvironment'
Sample conda_dependency.yml
dependencies:
- python=3.6.2
- scikit-learn
- pip
- pip:
- fedml_azure
- azureml-defaults
- pandas
- hdbcli
environment=create_environment(workspace=workspace,
environment_type='CondaSpecificationEnvironment',
environment_args={'name':<environment-name>,
'file_path':'<conda_dependency.yml_path>'}
)
DwcAzureTrain class initializes the resources required for the model training, enables the training data to be read from SAP Datasphere in real time without storing it in any Azure Storage, trains a Machine Learning model and registers it.
DwcAzureTrain(workspace=None,workspace_args=None,experiment=None,experiment_args=None,compute_type=None,compute=None,compute_args=None,environment=None,environment_type=None,environment_args=None)
Initializes the resources for the training such as Workspace, Environment, Compute and Experiment
workspace_args (dict) Accepted workspace_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to get an existing workspace.
workspace (azureml.core.Workspace) (optional):
default value: None
Assigns an existing Workspace object.
experiment_args (dict) Accepted experiment_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Experiment or get an existing Experiment.
experiment (azureml.core.Experiment) (optional):
default value: None
Assigns an existing Experiment object.
compute_type (str) (optional):
default value: None
Type of compute to be created. The following compute_type are supported:
'AmlComputeCluster'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.AmlCompute'.'AmlComputeInstance'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.ComputeInstance'.
compute_args (dict) Accepted compute_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Compute or get an existing Compute.
compute (azureml.core.compute) (optional):
default value: None
Assigns an existing Compute object.
environment_type (str) (optional):
default value: None
Specifies the method of creating an environment.The following environment_type are supported:
'CondaPackageEnvironment'for creating a new Environment or obtaining an existing environment by specifying pip, conda and private wheel dependency.'CondaSpecificationEnvironment'for creating a new Environment or obtaining an existing environment by passing a conda dependency file and private wheel dependency.
environment_args (dict) Accepted environment_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Environment or get an existing Environment.
environment (azureml.core.Environment) (optional):
default value: None
Assigns an existing Environment object.
Workspace:
- Getting an existing Workspace: Specify the 'workspace_args' parameter for getting an existing Workspace. Example
workspace_args={"subscription_id": <subscription_id>,
"resource_group": <resource_group>,
"workspace_name": <workspace_name>
}
- Assigning an existing Workspace: Specify the 'workspace' parameter for assigning an existing Workspace. Example
workspace=<workspace-object>
Experiment:
- Creation of new Experiment: Specify the 'experiment_args' parameter for creating a new Experiment.
Example
experiment_args={'name':<experiment-name>}
- Getting an existing Experiment: Specify the 'experiment_args' parameter for getting an existing Experiment. Example
experiment_args={'name':<experiment-name>}
- Assigning an existing experiment: Specify the 'experiment' parameter for assigning an existing Experiment. Example
experiment=<experiment-object>
Compute:
- Creation of new Compute: Specify the 'compute_type' and 'compute_args' parameters for creating a new Compute.
Example1: Creation of a new compute with compute_type 'AmlComputeCluster'
compute_type='AmlComputeCluster',
compute_args={'vm_size':'Standard_D12_v2',
'vm_priority':'lowpriority',
'compute_name':<compute-name>,
'min_nodes':0,
'max_nodes':4,
}
Example2: Creation of a new compute with compute_type 'AmlComputeInstance'
compute_type='AmlComputeInstance',
compute_args={
'vm_size':"Standard_D3_v2",
'compute_name':<compute-name>
}
- Getting an existing Compute: Specify the 'compute_type' and 'compute_args' parameters for getting an existing Compute. Example
compute_type='AmlComputeInstance',
compute_args={
'compute_name':<compute-name>
}
- Assigning an existing Compute: Specify the 'compute' parameter for assigning an existing Compute.
Example
compute=<compute-object>
- Note: If 'compute_type', 'compute_args' and 'compute' parameters are not specified, then no compute is used for training.
Environment:
- Creation of new Environment: Specify the 'environment_type' and 'environment_args' parameters for creating a new Environment.
Example1: Creation of new Environment with environment_type 'CondaPackageEnvironment'
environment_type='CondaPackageEnvironment',
environment_args={'name':<environment-name>,
'conda_packages':['scikit-learn'],
'pip_packages':['fedml_azure']
}
Example2: Creation of new Environment with environment_type 'CondaSpecificationEnvironment'
environment_type='CondaSpecificationEnvironment',
environment_args={'name':<environment-name>,
'file_path':'conda_dependency.yml'
}
- Getting an existing Environment: Specify the 'environment_type' and 'environment_args' parameters for getting an existing Environment.
Example:
environment_type='CondaPackageEnvironment',
environment_args={'name':<environment-name>}
- Assigning an existing Environment: Specify the 'environment' parameter for assigning an existing Environment.
environment=<environment-object>
generate_run_config
Copy the SAP Datasphere connection config file 'config.json' to 'source_directory' and generates and returns the 'azureml.core.ScriptRunConfig' object for training.
submit_run
Submit an experiment with the option to download the output files and returns the active created run.
register_model
Register a model for operationalization.
download_files
Download files from a given storage prefix (folder name) or the entire container if prefix is unspecified.
copy_config_file
Copy the SAP Datasphere connection config file config.json from config_file_path to script_directory
update_compute
Updates the compute target
update_environment
Updates the evironment
update_experiment
Updates the experiment
Copy the SAP Datasphere connection config file 'config.json' to 'source_directory' and generates the 'azureml.core.ScriptRunConfig' object for training.
generate_run_config(config_args,is_dwc_connection_required=True,config_file_path=None)
config_args (dict) Accepted config_args dictionary keyworded arguments
default value: None
A dictionary of keyword args to create a ScriptRunConfig object.
is_dwc_connection_required (bool)
default value: True
When set to True, it copies the SAP Datasphere connection config file config.json from config_file_path to source_directory specified in config_args. This config file is used for connection to SAP Datasphere during the training. When SAP Datasphere connection is not required for the training run, set the parameter to False.
config_file_path (str)
default value: None
The file path of the 'config.json' file which contains the connection details of SAP Datasphere.
A ScriptRun
Example
src=train.generate_run_config(config_file_path='config.json',
config_args={
'source_directory':<source_directory>,
'script':<script>,
'arguments':['--model_file_name', <model_file_name>, '--table_name', <table_name>,'--table_size', <table_size>]
}
)
Submit an experiment with the option to download the output files and returns the active created run.
submit_run(run_config,is_download=False,download_args=None,show_output=True,tags=None, **kwargs)
run_config (object)
The config to be submitted.
is_download (bool)
default value: False
If set to True, downloads the files from prefix (default is outputs directory of the present run) to output_directory (default is outputs/experiment.name/run.id).
download_args (dict) Accepted download_args dictionary keyworded arguments for downloading the run output
A dictionary of keyword args to download files from 'prefix' to 'output_directory'.
show_output (bool)
default value: True
Boolean to provide more verbose output.
tags (dict)
default value: None
Tags to be added to the submitted run, {"tag": "value"}.
kwargs (dict) (optional)
Additional parameters used in submit function for configurations.
A run.
Example
run=train.submit_run(<ScriptRunConfig-object>,is_download=True)
Register a model for operationalization.
register_model(run,model_args,resource_config_args=None,is_sklearn_model=False)
run Run
The run object to be used to register the model.
model_args (dict) Accepted model_args dictionary keyworded arguments to register the model
A dictionary of keyword args to register the model
resource_config_args(dict) Accepted resource_config_args for registering the model
A dictionary of keyword args to specify the resouce configuration for registering the model
is_sklearn_model (bool)
default value: False
If set to True, then 'model_framework' of model_args is set to Model.Framework.SCIKITLEARN and 'model_framework_version' of model_args is set to [sklearn._version_](https://scikit-learn.org/stable/) by default.
The registered model.
Example
model=train.register_model(run=<run-object>,
model_args={'model_name':<model_name>,
'model_path':<model_path>},
resource_config_args={'cpu':1, 'memory_in_gb':0.5},
is_sklearn_model=True
)
Download files from a given storage prefix (folder name) or the entire container if prefix is unspecified.
download_files(run,prefix='outputs', output_directory=None, output_paths=None, batch_size=100, append_prefix=True)
run Run
The run object used to download the files
prefix str
default_value:'outputs'
The filepath prefix within the container from which to download all artifacts.
output_directory str
default_value:'outputs/experiment.name/run.id'
An optional directory that all artifact paths use as a prefix.
output_paths [str]
Optional filepaths in which to store the downloaded artifacts. Should be unique and match length of paths.
batch_size int
The number of files to download per batch. The default is 100 files.
append_prefix bool
default_value:True
An optional flag whether to append the specified prefix from the final output file path. If False then the prefix is removed from the output file path.
Copy the SAP Datasphere connection config file config.json from config_file_path to script_directory
copy_config_file(config_file_path,script_directory)
config_file_path (str)
The file path of the 'config.json' file which contains the connection details of SAP Datasphere.
script_directory (str)
The file path of the destination.
Updates the compute target
update_compute(compute=None,compute_args=None,compute_type=None)
compute_type (str) (optional):
default value: None
Type of compute to be created. The following compute_type are supported:
'AmlComputeCluster'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.AmlCompute'.'AmlComputeInstance'for creating a new compute target or obtaining an existing compute target of type 'azureml.core.compute.ComputeInstance'.
compute_args (dict) Accepted compute_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Compute or get an existing Compute.
compute (azureml.core.compute) (optional):
default value: None
Assigns an existing Compute object.
Updates the environment
update_environment(environment=None,environment_type=None,environment_args=None)
environment_type (str) (optional):
default value: None
Specifies the method of creating an environment.The following environment_type are supported:
'CondaPackageEnvironment'for creating a new Environment or obtaining an existing environment by specifying pip, conda and private wheel dependency.'CondaSpecificationEnvironment'for creating a new Environment or obtaining an existing environment by passing a conda dependency file and private wheel dependency.
environment_args (dict) Accepted environment_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Environment or get an existing Environment.
environment (azureml.core.Environment) (optional):
default value: None
Assigns an existing Environment object.
Updates the experiment
update_experiment(experiment=None,experiment_args=None)
experiment_args (dict Accepted experiment_args dictionary keyworded arguments (optional):
default value: None
A dictionary of keyword args to create a new Experiment or get an existing Experiment.
experiment (azureml.core.Experiment) (optional):
default value: None
Assigns an existing Experiment object.
register_model
Method to register a model with the provided workspace.
deploy
Method to deploy model/models to various compute targets.
predict
Method to inference the webservice endpoints.
Register a model with the provided workspace.
register_model(model_args,resource_config_args=None,is_sklearn_model=False)
model_args (dict) Accepted model_args dictionary keyworded arguments to register the model for deployment
A dictionary of keyword args to register the model
resource_config_args(dict) Accepted resource_config_args for registering the model
A dictionary of keyword args to specify the resouce configuration for registering the model
is_sklearn_model (bool)
default value: False
If set to True, then 'model_framework' of model_args is set to Model.Framework.SCIKITLEARN and 'model_framework_version' of model_args is set to [sklearn._version_](https://scikit-learn.org/stable/) by default.
The registered model.
Example
from fedml_azure import register_model
model=register_model(
model_args={'workspace':<workspace-object>,
'model_name':<model_name>,
'model_path':<model_path>},
resource_config_args={'cpu':<cpu-cores>, 'memory_in_gb':<memory-in-gb>},
is_sklearn_model=True
)
Method to deploy model/models to various compute targets.
deploy(compute_type=None,deploy_args=None,inference_config_args=None,deploy_config_args=None)
-
(Register an application with Azure AD and create a service principal)
-
Get the Application (client) ID by referring (get application id). The Application (client) ID is the "SERVICE_PRINCIPAL_ID".
-
Create a new application secret by referring (create new application secret). The value of the client secret displayed is the "SERVICE_PRINCIPAL_PASSWORD".
-
Store the "SERVICE_PRINCIPAL_ID" and "SERVICE_PRINCIPAL_PASSWORD" in a json file (example: sp_config.json) and provide the file path to
deploy_args['sp_config_path']. Refer (deploy_args) parameters for kyma below for more details.
-
Create a Kyma service account by referring the (tutorial).
-
In step 2.1 of the (tutorial), add the following fields:
- Add 'namespaces' under 'rules -> resources' section of yaml file.
- Add 'watch' under 'rules -> verbs' section of yaml file.
-
In step 4.1 of the (tutorial), replace the following:
- Replace the value of 'name' under 'clusters' section with the cluster name of the kyma kubernetes cluster.
- Replace the value of 'name' under 'users' section and 'user' under 'contexts'-> 'context' with 'OIDCUser' user.
- Replace the value of 'name', 'context -> cluster' under 'contexts' section with the cluster name of the kyma kubernetes cluster.
- Replace the value of 'current-context' with the cluster name of the kyma kubernetes cluster.
-
Provide the generated 'kubeconfig.yaml' file path to
deploy_args['kubeconfig_path']to connect to Kyma Kubernetes. Refer (deploy_args) parameters for kyma below for more details.
compute_type (str) (optional):
Type of compute to deploy the webservice to. The supported compute_type are 'ACI', 'AKS', 'Local' and 'Kyma':
ACI: Deploys the model/models as a webservice endpoint to Azure Container Instances.AKS: Deploys the model/models as a webservice endpoint to Azure Kubernetes Service.Local: Deploys the model/models as a webservice endpoint locally.Kyma: Deploys the model/models as a webservice endpoint to kyma kubernetes.
deploy_args (dict)
A dictionary of keyword args to deploy the model.
deploy_config_argsforACI,AKSandLocalAccepted deploy_args dictionary keyworded arguments to deploy the modeldeploy_config_argsforKymaAccepted deploy_args dictionary keyworded arguments to deploy the model to kyma
inference_config_args (dict)
A dictionary of keyword args to determine required model properties.
inference_config_argsforACI,AKSandLocalAccepted inference_config_args dictionary keyworded arguments to determine required model propertiesinference_config_argsforKymaAccepted inference_config_args dictionary keyworded to determine required model properties for kyma
deploy_config_args (dict)
Note: This needs to passed only if the compute_type is ACI,AKS and Local. It is not required in case the compute_type is Kyma.
A dictionary of keyword args to configure the webservice.
The accepted deploy_config_args for the compute types are as follows:
-
deploy_config_argsfor ACI Accepted ACI deploy_config_args dictionary keyworded arguments to configure the webservice
A dictionary of keyword args to deploy the model. -
deploy_config_argsfor AKS Accepted AKS deploy_config_args dictionary keyworded arguments to configure the webservice
A dictionary of keyword args to deploy the model. -
deploy_config_argsfor Local Accepted Local deploy_config_args dictionary keyworded arguments to configure the webservice
A dictionary of keyword args to deploy the model.
For compute types ACI,AKS and Local:
endpoint_url,api_key,service
Note The api_key is only returned if the compute_type is AKS.
For compute_type 'Kyma'
endpoint_url
endpoint_url str
api_key str
service Webservice
Example 1: Deploy a model locally
from fedml_azure import deploy
local_endpoint,_,local_service=deploy(compute_type='local',
inference_config_args={'entry_script':<entry-script-path>, 'environment':<environment-object>},
deploy_config_args={'port':<port>},
deploy_args={'workspace':<workspace-object>,'name':<service-name>,'models':<list-of-models>}
)
Example 2: Deploy a model to ACI
from fedml_azure import deploy
aci_endpoint,_,aci_service=deploy(compute_type='ACI',
inference_config_args={'entry_script':<entry-script-path>, 'environment':<environment-object>},
deploy_config_args={'cpu_cores':<no-of-cpu-cores>, 'memory_gb':<memory-in-gb>},
deploy_args={'workspace':<workspace-object>,'name':<service-name>,'models':<list-of-models>}
)
Example 3: Deploy a model to AKS
from fedml_azure import deploy
aks_endpoint,api_key,aks_service=deploy(compute_type='AKS',
inference_config_args={'entry_script':<entry-script-path>, 'environment':<environment-object>},
deploy_args={'workspace':<workspace-object>,'name':<service-name>,'models':<list-of-models>,'deployment_target':<aks-compute-object>}
)
Example 4: Deploy a model to Kyma Kubernetes
from fedml_azure import deploy
kyma_endpoint=deploy(compute_type='Kyma',
inference_config_args={'entry_script':<entry-script-path>, 'environment':<environment-object>},
deploy_args={'workspace':<workspace-object>,
'name':<service-name>,
'models':<list-of-models>,
'num_replicas':<num-replicas>,
'kubeconfig_path':<path-to-kubeconfig.yaml>,
'sp_config_path':<path-to-sp_config.json>
})
Method to inference the webservice endpoints.
predict(data,compute_type=None,api_key=None,service=None,endpoint_url=None)
endpoint_url (str):
The endpoint url used for inferencing the webserice endpoint.
compute_type (str):
The compute_type where the webservice is deployed. The supported compute types are as follows:
ACI: Webservice Endpoint in Azure Container Instances.AKS: Webservice Endpoint in Azure Kubernetes Service.Local: Webservice Endpoint present locally.Kyma: Webservice Endpoint in Kyma Kubernetes.
data (Serialized json object):
Required
The data used for inferencing.
api_key (str):
Required
The api_key obtained from the deploy method. The api_key is only returned if the compute_type is AKS.
service (Webservice).
The Webservice object to be used to invoke the endpoint. Note the Webservice object types include the following:
Note:
There are two ways to inference the data using predict function:
-
By using the endpoint_url as follows:
predict(endpoint_url=<endpoint-url>,compute_type=<compute-type>,data=<test-data>) -
By using the Webservice object as follows:
predict(service=<Webservice-object>,data=<test-data>)
The result of inferencing.
Example 1: Inferencing ACI webservice endpoint
test_data = json.dumps({
'data': <pandas-dataframe-containing-inferencing-data>.values.tolist()
})
# Option 1: Predict using the endpoint_url
from fedml_azure import predict
predict(endpoint_url='<aci-endpoint-url>',data=test_data,compute_type='ACI')
# Option 2: Predict using the Webservice object
predict(service=<aci-webservice>,data=test_data)
Example 2: Inferencing AKS webservice endpoint
test_data = json.dumps({
'data': <pandas-dataframe-containing-inferencing-data>.values.tolist()
})
# Option 1: Predict using the endpoint_url
from fedml_azure import predict
predict(endpoint_url='<aks-endpoint-url>',data=test_data,compute_type='AKS')
# Option 2: Predict using the Webservice object
predict(service=<aks-webservice>,data=test_data)
Example 3: Inferencing Local webservice endpoint
test_data = json.dumps({
'data': <pandas-dataframe-containing-inferencing-data>.values.tolist()
})
# Option 1: Predict using the endpoint_url
from fedml_azure import predict
predict(endpoint_url='<local-endpoint-url>',data=test_data,compute_type='Local')
# Option 2: Predict using the Webservice object
predict(service=<local-webservice>,data=test_data)
Example 4: Inferencing Kyma webservice endpoint
test_data = json.dumps({
'data': <pandas-dataframe-containing-inferencing-data>.values.tolist()
})
# Predict using the endpoint_url
from fedml_azure import predict
predict(endpoint_url='<kyma-endpoint-url>',data=test_data,compute_type='Kyma')