Model Management and Execution¶
This section describes the models available in Predictive Learning and the steps required to develop a model.
This also includes descriptions and step-by-step instructions for the following:
- Validating a New Model
- Importing a Model
- Actions You can Take with Models
- Executing a Model
- Advanced Docker Model Settings
- Executing Models on a Schedule
About Models and Model Types¶
Model is a analytical script written in form of Jupyter notebook, Zeppelin Notebook or bundled into a docker image.
Model Types¶
The following types of models can be created in PrL:
- Jupyter Notebook
- Docker Image
Viewing Models¶
The "Models" page displays a table that lists information about the models you have access to. Each model's details as well as icons that allow you to perform various actions with models are displayed.
Note
Maximum file size for the model uploads is limited to 50 MB.
Possible actions on models¶
Action icons appear on the right side of the models table. The following actions are possible on the available models:
- Launch icon: click on the launch icon to open a model.
- Ellipses icon: click the ellipses icon to view actions you can take, that include:
- Deleting a model: displays a pop-up window to prevent unintended deletions.
- Editing a model: displays a pop-up dialog in which the name and description can be updated. However, it is not possible to change the model type.
- Creating a version: select whether to create a minor or major version (major = 2.0; minor=1.1), set an expiration date and model type, and browse for a model to upload, up to 50MB.
- Downloading a model: downloads the model on your local system.
Importing a Model¶
When importing an existing model, follow the below steps:
- Click "Import/Validate Model" on the "Models" page. The "Import/Validate Model" pop-up window is displayed.
- Click the "Import Model" tab.
- Enter a name and description.
- Select an expiration date from the built-in calendar.
- Select a model type from the Type drop-down list, or select "Browse" to locate and select a model file.
- Click "Save".
Your imported model is displayed in the Models list.
Importing Docker Images¶
If "Docker Image" is selected as the model Type, then the "Browse for Model File" button will be replaced with the "Generate Token" button. This is necessary because of the way Docker images are imported into the application. In general, Docker images are developed locally or, it can be imported from an external source.
Clicking the "Generate Token" will provide you with a temporary session credentials that will allow you to upload the Docker image to our Docker registry. This is required in order to allow secure and high-performance on any usages of your Docker image. Once your Docker image is uploaded, we will store a secure and private copy that can only be accessed by your tenant. In addition, we attach the necessary metadata to the image for execution, map its inputs and outputs, and enable the display of logs generated during its execution. Click "Generate Token":
Already built Docker images tend to be large files as they contain complete setups of operating systems with your own additions. This allows replicating environments that you have built and prepared, as well as their execution in most of the other external environments, such as public or private cloud environments. Docker images pack everything into an hierarchical structure (layers) and contain the metadata needed to interact with the exterior and with its own container engine. These images are built with a Docker compliant engine following a set of instructions that are described in a file named Dockerfile. A Docker engine compiles these instructions into a Docker image that can be distributed and instantiated as a Docker container by any container compliant engine. Building the image is often done with the help of a command line interface, and we are requiring the same Docker compliant command line to upload the image into our system. Therefore, the instructions in the pop-up are meant to be used with such a command line, but they target the Docker CLI.
- This is meant for reference only, our system designates an URI that will indicate where your Docker image will be uploaded. This is immutable and attempting to change it, will make our system unaware of where you have uploaded your Docker image.
- Tag your local image with the instructions from this step. You need to replace
<local_image_ID>
with your local IMAGE_ID, that you find by using "docker images" command. The<local_image_ID>
can be found under the "IMAGE_ID" column. - Login to our Docker registry using the command provided at this step. You can expand the textbox containing the long session string to reveal the registry where your Docker image will be uploaded.
- After you get a successful login at the above step, you can start "pushing" (uploading) your local Docker image to our registry using the command from this step.
Now you can close the pop-up.
Note that your local image might have a "tag" that is usually the string that follows after the URL and is separated by a colon, like in "URL:tag". The tag is helpful to denote versions for example, like "v1.0.1" or "final-v1.0". If your tagged image at step 2 above includes this tag, then after closing the pop-up, you need to paste the URL stated at step 1 above in the "Image Repository URI (with tag)" field, including the tag as in the image below.
Click "Save" only after the upload your Docker image is complete.
Clicking "Save" will instruct the system to verify the Docker's image existence in our registry and its validity.
Downloading a Docker Image¶
You can download a previously uploaded Docker image by using similar steps as the ones above. Instead of pushing, you will be able to download (pull) a Docker image once you have a valid temporary session with our Docker registry. From the Models list, click the "..." button and use the "Download model" action menu. This will not download the actual image, but the access session in the form of a JSON file. From the JSON file, you can depict the keys needed to login to our registry.
Using Docker CLI, you can proceed using a similar "docker login -u AWS -p <password> <registry>
" where <password>
and <registry>
are provided in the downloaded file. Once you logged in, you can use "docker pull <uri>
" where <uri>
is also provided in the downloaded JSON file.
Provided JSON file contains two types of authentication:
- First part for Docker compliant CLIs under the "credentials" key, contains "user", "password". These can be used with Docker CLI to connect to our registry.
- Second part, "providerCredentials" containing "accessKey", "secret" and "sessionToken" for AWS CLI. For the second option, you can use the AWS CLI tools to interact with your image. It provides additional but limited to AWS ECR functionality than Docker CLI (e.g. docker image scanning). The list of capabilities can be explored directly from the AWS CLI once you logged in the registry.
Validating a New Model¶
When validating a model, the process begins with the "Import/Validate Model" pop-up Window.
To develop a new model, follow these steps:
- Click "Add/Develop Model" on the Landing or Models page. The Import/Develop a Model pop-up window displays.
- Make sure you are on the "Develop a New Model" tab.
- Select an environment from the drop-down list and click "Start".
- When the environment configuration displays a "Running' status, click the arrow icon. Your environment configuration opens in Jupyter Notebook.
Executing a Model¶
Executing a model involves running an analytical model against source data in a specific environment. Sometimes, this is called "running a job" in Predictive Learning.
To run a basic PrL job, you need to configure the following:
- Input: source (location) from which PrL reads the data for the job
- Output: location to which PrL writes the job results data
- Model: the mathematical model that runs against the input data
- Environment: start and stop environments for running jobs
Model Validation and Job execution environments file system¶
- Users cannot create new files or folders in their Jupyter notebook and Docker container, except in a specific directory during model validation and job execution.
- The file system is locked to read-only during model validation and job execution, except for the
/tmp
directory. - Any new files or folders created during model validation and job execution should be placed in the
/tmp
directory only.
Executing a PrL Model¶
To execute your model, follow these steps:
- Click "Add Job" in "Quick Actions".
- Enter a name and an optional description.
- Select a model from the drop-down list.
- Select an environment configuration from the drop-down list.
- Select a data source for input and output.
- Before clicking the "Add Job" button, if you want to schedule the job to run, refer Adding a Schedule to a Job.
- Click "Add Job".
Note
In case of LPC, each model will run in its own pod, and there is no maximum limit based on resource availability within the kubernetes cluster nodes.
It is a known limitation if a pod cannot start due to node unavailability, it remains in a "Pending" state, impacting operational efficiency and slowing down the application performance.
Executing Models on a Schedule¶
PrL jobs can be run ad-hoc or you can schedule them to run for a specific amount of time. If you want to run your job on a schedule, you have to set it up while you are creating the job.
Adding a Schedule to a Model Job¶
The "Enable Scheduling" toggle is located at the bottom of the "Add a Job" page.
To add a schedule to a job that you create, follow these steps:
- Slide the "Enable Scheduling" toggle to the right.
- Enter a number in the "Days" to run field.
- Select a time increment from the drop-down list.
- Click "Add Schedule".
Note
- Quick boot-up environments allow for a minimum scheduling interval of 5 minutes, whereas moderate boot-up environments permit a minimum scheduling interval of one hour.
- The Scheduling feature is available on the AWS platform only.
Advanced Docker Model Settings¶
When using Docker models, you can also customize the model using these additional settings:
- External reference IDs
- Start Command
- Maximum Run Hours
- Environment Variables (key/value pairs)
- Entry Point
- Scheduling
Adding Advanced Settings to a Docker Job¶
With the exception of the Maximum Run Hours field, all of the advanced option fields are optional. To add advanced options to a job, follow these steps:
- Click "Advanced Details".
- Enter an optional external reference ID.
- Click the icon in the "Environment Variables" field to add Key / Value pairs in the pop-up window.
- Click "OK".
- Enter a Start Command and Entry point.
- Enter a number in the "Maximum Run Hours" field.
- Click "Add Job".
Except where otherwise noted, content on this site is licensed under the Development License Agreement.