Oracle Cloud Infrastructure Documentation

ML Application Project Setup

After creating the infrastructure for the sample ML Application, you can use the sample ML Application project as a template to start building, deploying, and operating your own ML Applications.

This project includes development best practices and provides the mlapp CLI, a tool that simplifies ML Application development. To create an ML Application, you must use the mlapp CLI, Terraform, OCI SDK, or OCI CLI. You can't create an ML Application in the Console, but you can view ML Applications and their details there.

By starting your project with the sample ML Application project, you can progress your ML Application implementation to production. The project is built using experience gained from helping organizations to successfully deploy their applications to production.

The sample ML Application project is available here: sample-project.

Clone this project to use it as the foundation for your ML Application implementation.

The project includes documentation in README.md files, where you can find detailed information about the project and its components.

Project Structure

The project consists of two main parts:

  • The infrastructure folder automates the creation of resources that the sample ML Application depends on.
  • The ML Application folder contains the sample ML Application, including its configuration, implementation, and the mlapp CLI.

Configuring Prerequisite Resources

Before you begin building and deploying the ML Application, you need to create the necessary resources that the sample ML Application depends on (for example, logs, log groups, a Data Science project, and a subnet). This process can be automated by following these steps:

  1. Prepare the environment folder.
    You can use the default dev environment folder (environments/dev) or use it as a template to create the custom environment. To create the custom environment:
    1. Make a copy of the development environment folder (environments/dev).
    2. Rename the copied folder to match the name of the environment.
  2. Configure the environment.
    1. Navigate to the environment folder (for example, environments/dev).
    2. Edit the input_variables.tfvars file to configure the environment settings.
  3. Run Terraform to create resources.
    1. Initialize Terraform in the environment folder: 
      terraform init
    2. Apply the configuration to create the resources:
      terraform apply -var- file input_variables.tfvars
    3. If needs be, destroy the created resources:
      terraform destroy -var- file input_variables.tfvars
    Note

    Don't reuse resources across different environments, as you might break environment isolation. For example, sharing a resource between development and QA environments might cause issues in development that might render the QA environment unusable, delaying deployment to production.

Configuring the ML Application Environment

  1. Prepare the environment folder.
    You can use the default dev environment folder (environments/dev) or use it as a template to create the custom environment. To create the custom environment:
    1. Make a copy of the development environment folder (environments/dev).
    2. Rename the copied folder to match the name of the environment.
  2. Configure the environment.
    In the environment configuration folder:
    1. Edit the env-config.yaml file.
    2. Edit the testdata-instance.json file (the Object Storage namespace, after the at sign ('@') needs to be updated to match the tenancy).
  3. Define resource references.
    1. Edit the arguments.yaml file in the environment configuration folder to define references to the resources the application depends on.
    2. In the infrastructure/environments/<your environment> folder, run 
      terraform output
    3. Copy the output (excluding the last line) and paste it into arguments.yaml , replacing = with :.

Configuring and Initializing the mlapp CLI

  1. Configure the ML Application Project.
    1. Navigate to the-application folder.
    2. Edit the application-def.yaml file to define the name and description of the ML Application and its implementation.
    3. Create default_env to set the environment as the default (this removes the need to specify it on the command line when using the mlapp CLI). You can copy ml-application/default_env.example to ml-application/default_env and store the environment name there.
  2. Initialize the environment.
    In the ml-application folder, run:
    source ./mlapp init

    This command adds the mlapp script to the PATH variable, letting you run the CLI with mlapp instead of ./mlapp.

Building and Deploying the Application

With everything configured, you can now start building and deploying the application.

Note

Learn about mlapp CLI commands by running: 
mlapp -h
  1. Build the application. 
    mlapp build
  2. Deploy the application. 
    mlapp deploy
  3. Instantiate the application. 
    mlapp instantiate
  4. trigger a run of the training pipeline. 
    mlapp trigger
  5. Test the predictive service. 
    mlapp predict
After running an mlapp CLI command, check the results by navigating to ML Applications under OCI Console / Analytics & AI / Machine Learning.

Use Defined and Free-Form Tags

The sample application illustrates how to use both defined and free-form tags to ensure tenant isolation and enable tracking of runtime resources, specifically models.

Defined tags are used to associate tenant-specific identifiers with resources such as model deployments, storage buckets, and models.
Add a defined tag to a bucket
resource "oci_objectstorage_bucket" "data_storage_bucket" {
  compartment_id = var.app_impl.compartment_id
  namespace      = data.oci_objectstorage_namespace.this.namespace
  name           = "ml-app-fetal-risk-bucket-${var.app_instance.id}"
  access_type    = "NoPublicAccess"
 
  # To allow Instance (tenant) isolation
  defined_tags   = {"MlApplications.MlApplicationInstanceId" = var.app_instance.id}
}
For runtime resources created dynamically from code (such as models), add both a defined tag and a free-form tag. The free-form tag links the resource to the instance, enabling automatic deletion when the instance is removed.
Add defined and free-form tags to a model
model_id = xgb_model.save(display_name='fetal_health_model',
                          # needed for tenant isolation
                          defined_tags={"MlApplications": {"MlApplicationInstanceId": instance_id}},
                          # needed for ML App to be able to track created model
                          freeform_tags={"MlApplicationInstance": instance_id})