Training and Deploying an ML Model on DKubeX#

This tutorial walks through the end-to-end machine learning workflow on DKubeX: training a model from the Terminal, tracking and registering it in MLflow, and deploying and testing it in Model Studio.

The example predicts insurance charges. The model takes six inputs — age, sex, BMI, number of children, smoker status, and region — and predicts the insurance charges (premium) for a policyholder.

Only three DKubeX applications are used in this tutorial: Terminal, MLflow, and Model Studio.

Prerequisites#

Access to a DKubeX workspace with the Terminal, MLflow, and Model Studio applications enabled.
An MLflow tracking token. In a DKubeX workspace this is supplied automatically as a file (see Step 2).

The Example#

The dataset predicts a policyholder’s insurance charges from six features. The categorical columns are already integer-encoded in pre_processed.csv, so no preprocessing step is needed before training.

Feature	Type	Encoding
`age`	numeric	—
`sex`	categorical	`0` = female, `1` = male
`bmi`	numeric	—
`children`	numeric	—
`smoker`	categorical	`0` = no, `1` = yes
`region`	categorical	`0` = southwest, `1` = southeast, `2` = northwest, `3` = northeast
`charges`	numeric	target (predicted value)

Step 1 — Get the example and set up the environment#

Open the Terminal application in your workspace. You start in your home directory with a prompt similar to admin@workspace-0:~$.

Clone the example from the ml-training-example branch of the docs-site repository. This gives you an insurance/ folder containing the training script and the dataset:

git clone --branch ml-training-example --single-branch https://github.com/dkubeio/docs-site.git

Create and activate a Python virtual environment:

uv venv myenv --python 3.11
source myenv/bin/activate

Creating the environment reports the Python version and location, for example:

Using CPython 3.11.15
Creating virtual environment at: myenv
Activate with: source myenv/bin/activate

Once activated, the prompt is prefixed with the environment name, for example (myenv) admin@workspace-0:~$.

Move into the example directory and list its contents:

cd docs-site/insurance
ls

deploy.py       deploy_snow.py         pre_processed.csv  predict.sh
preprocess.py   preprocessing_snow.py  train.py           training_snow.py

This tutorial uses two of these files: train.py (the training script) and pre_processed.csv (the already-encoded dataset).

Install the packages required to run the training script:

uv pip install mlflow==2.22.4 scikit-learn

MLflow is pinned to 2.22.4 for compatibility with the tracking server.

Step 2 — Configure the environment variables#

train.py reads three environment variables. Export them before running the script:

export EXPERIMENT_NAME=ins_demo_exp
export REGISTERED_MODEL_NAME=ins_model
export MLFLOW_TRACKING_TOKEN=$(cat $MLFLOW_TOKEN_PATH)

EXPERIMENT_NAME — the MLflow experiment to log to. A run is created under this experiment.
REGISTERED_MODEL_NAME — the name the trained model is registered under in the MLflow Model Registry. Each training run adds a new version to this model.
MLFLOW_TRACKING_TOKEN — authenticates the script to MLflow. In a DKubeX workspace the token is provided as a file, and its path is available in the MLFLOW_TOKEN_PATH environment variable. The command above reads that file and sets the token. You can confirm the path with:
```
echo $MLFLOW_TOKEN_PATH
```
```
/mnt/secrets/mlflow/token
```

Step 3 — Train the model#

Run the training script:

python train.py

The script loads the dataset, creates the MLflow experiment, trains the model, logs the metrics and the model artifact to MLflow, and registers a new model version. Sample output:

Loading: ./pre_processed.csv
Creating MLflow experiment: ins_demo_exp
Training started...
R2  : 0.823
MAE : 2726.50
...
Successfully registered model 'ins_model'.
Created version '1' of model 'ins_model'.
...
Model logged successfully
Registered model: ins_model
Training finished: {'r2': 0.8231588285889231, 'mae': 2726.5047352665533}

The two evaluation metrics reported are:

R2 — the coefficient of determination (higher is better).
MAE — the mean absolute error, in the same units as charges.

The model is registered automatically as version 1 of ins_model. Running the script again creates the next version.

Step 4 — Inspect the run in MLflow#

Open the MLflow application.

On the Experiments tab, select the ins_demo_exp experiment. The training run appears in the run list (with a generated run name, for example overjoyed-jay-387). Open the run to view its parameters, the logged metrics (r2, mae), and the logged model under Artifacts.
On the Models tab, under Registered Models, open ins_model. The Versions section lists Version 1, which was registered by the training run.

Step 5 — Deploy the model in Model Studio#

Open the Model Studio application.

In the top navigation bar, go to ML Registry.
Locate ins_model and expand it to see its versions.
Click Deploy on Version 1.
In the Deploy ML Model dialog (which deploys a model from the MLflow registry via KServe), review the fields:
- Storage URI — auto-filled from the selected version (for example, mlflow-artifacts:/3/<run-id>).
- Model Format — mlflow. Auto-detect reads the model to choose the serving runtime (an scikit-learn model is served with the sklearn runtime).
- Resources — the available cluster capacity is shown. Accept the defaults, or set CPU and memory if you need more.
Click Deploy.

Step 6 — Confirm the deployment#

In the top navigation bar, go to ML Models. The new deployment ins_model-v1 appears in the list. Wait until its status is Ready with 1/1 replicas.

Step 7 — Run inference#

In the top navigation bar, go to Playground.

In the Model panel, select the deployed model — [ML Infer] ins_model-v1 (shown as Running, served via kserve).
In Inference Input (JSON), provide one or more records in KServe format. Each record is the six features in order: [age, sex, bmi, children, smoker, region].
```
{
  "instances": [
    [19, 0, 27.9, 0, 1, 0]
  ]
}
```
Click Run Inference. The Response panel shows the predicted charges:
```
{
  "predictions": [
    19516.150064927057
  ]
}
```

The prediction is the estimated insurance charge for the supplied inputs — in this example, a 19-year-old female (sex=0) with a BMI of 27.9, no children, who is a smoker (smoker=1), in the southwest region (region=0).