Getting Started with Amazon SageMaker: Using Built-in Algorithms

Train and deploy a k-NN classifier on the Iris dataset using SageMaker Studio and built-in algorithms.

Takahiro Iwasa

2022-01-24

7 min read

This example uses SageMaker Studio, an integrated development environment for machine learning, to apply SageMaker’s built-in K-Nearest Neighbors (k-NN) algorithm to the Iris dataset.

Onboarding to SageMaker

SageMaker Studio requires completing the onboarding process first.

Choose either Quick Setup or Custom Setup:

Select a VPC.

Open the menu for the automatically created user and launch SageMaker Studio.

SageMaker Studio opens after it finishes launching.

Click Notebook in the center of the SageMaker Studio screen.

Preprocessing

Preparing the Dataset

Start by setting up your environment variables.

Replace the following with the actual values:

<YOUR_S3_BUCKET>
<YOUR_SAGEMAKER_ROLE>

%env S3_DATASET_BUCKET=<YOUR_S3_BUCKET>
%env S3_DATASET_TRAIN=knn/input/iris_train.csv
%env S3_DATASET_TEST=knn/input/iris_test.csv
%env S3_TRAIN_OUTPUT=knn/output
%env SAGEMAKER_ROLE=<YOUR_SAGEMAKER_ROLE>

Next, create a cell with the following Python imports. The Python3 Data Science instance comes pre-installed with these libraries.

1
import os
2
import random
3
import string
4

5
import boto3
6
import matplotlib.pyplot as plt
7
import pandas as pd
8
import sagemaker
9
from IPython.display import display
10
from sagemaker import image_uris
11
from sagemaker.deserializers import JSONDeserializer
12
from sagemaker.estimator import Estimator, Predictor
13
from sagemaker.inputs import TrainingInput
14
from sagemaker.serializers import CSVSerializer
15
from sklearn.model_selection import train_test_split

Define constants and variables.

1
# Define constants
2
CSV_PATH = './tmp/iris.csv'
3
S3_DATASET_BUCKET = os.getenv('S3_DATASET_BUCKET')
4
S3_DATASET_TRAIN = os.getenv('S3_DATASET_TRAIN')
5
S3_DATASET_TEST = os.getenv('S3_DATASET_TEST')
6
S3_TRAIN_OUTPUT = os.getenv('S3_TRAIN_OUTPUT')
7
SAGEMAKER_ROLE = os.getenv('SAGEMAKER_ROLE')
8
ESTIMATOR_INSTANCE_COUNT = 1
9
ESTIMATOR_INSTANCE_TYPE = 'ml.m5.large'
10
PREDICTOR_INSTANCE_TYPE = 'ml.t2.medium'
11
PREDICTOR_ENDPOINT_NAME = f'sagemaker-knn-{PREDICTOR_INSTANCE_TYPE}'.replace('.', '-')
12

13
# Define variables
14
bucket = boto3.resource('s3').Bucket(S3_DATASET_BUCKET)
15
train_df = None
16
test_df = None
17
train_object_path = None
18
test_object_path = None
19
knn = None
20
predictor = None

Download the Iris dataset from the Amazon SageMaker Examples repository. Its simple, well-defined structure makes it a common dataset for demonstrating classification models. See the official page for details about its attributes and uses.

!mkdir -p tmp
!curl -o "$(pwd)/tmp/iris.csv" -L https://raw.githubusercontent.com/aws/amazon-sagemaker-examples/master/hyperparameter_tuning/r_bring_your_own/iris.csv

After downloading the file, use the following code to load and preprocess the CSV for training with a SageMaker built-in algorithm.

Refer to the SageMaker documentation for more details.

1
def load_csv(path: str) -> pd.DataFrame:
2
    # Load the CSV into a Pandas DataFrame
3
    df = pd.read_csv(path)
4
    # Move the label column ('Species') to the first position
5
    df = df[['Species', 'Sepal.Length', 'Sepal.Width', 'Petal.Length', 'Petal.Width']]
6
    # Convert target labels ('Species') to integers
7
    df['Species'] = df['Species'].map({'setosa': 0, 'versicolor': 1, 'virginica': 2})
8
    return df

🔥 Caution

SageMaker requires the first column in the CSV to be the target label or class, so the Species column must be moved to the first position.
The target labels (species names) must also be converted to integers for compatibility.

Visualizing the Dataset

Create a scatter plot of the dataset to understand its features and distributions.

1
def plot(df: pd.DataFrame) -> None:
2
    pd.plotting.scatter_matrix(df, figsize=(15, 15), c=df['Species'])
3
    plt.show()

The scatter plot uses the following axis mappings:

X-axis
- Represents Species, Sepal.Length, Sepal.Width, Petal.Length, and Petal.Width from left to right.
Y-axis
- Represents Petal.Width, Petal.Length, Sepal.Width, Sepal.Length, and Species from bottom to top.

The plot shows that the data points form distinct groups, suggesting that the species can be predicted from these features.

Uploading Dataset to S3

Upload the preprocessed dataset to S3:

1
def upload_csv_to_s3(df: pd.DataFrame, object_path: str) -> str:
2
    filename = ''.join([random.choice(string.digits + string.ascii_lowercase) for i in range(10)])
3
    path = os.path.abspath(os.path.join('./tmp', filename))
4
    df.to_csv(path, header=False, index=False)
5
    # Change content-type because the default is binary/octet-stream
6
    bucket.upload_file(path, object_path, ExtraArgs={'ContentType': 'text/csv'})
7
    return f's3://{bucket.name}/{object_path}'

Executing Preprocessing

To complete the preprocessing above, run the following:

1
if __name__ == '__main__':
2
    df = load_csv(CSV_PATH)
3
    display(df)
4
    plot(df)
5
    train_df, test_df = train_test_split(df, shuffle=True, random_state=0)
6
    train_object_path = upload_csv_to_s3(train_df, S3_DATASET_TRAIN)
7
    test_object_path = upload_csv_to_s3(test_df, S3_DATASET_TEST)

Training

Configure the k-NN estimator and start the training process:

1
def get_estimator(**hyperparams) -> Estimator:
2
    estimator = Estimator(
3
        image_uri=image_uris.retrieve('knn', boto3.Session().region_name),
4
        role=SAGEMAKER_ROLE,
5
        instance_count=ESTIMATOR_INSTANCE_COUNT,
6
        instance_type=ESTIMATOR_INSTANCE_TYPE,
7
        input_mode='Pipe',
8
        output_path=f's3://{S3_DATASET_BUCKET}/{S3_TRAIN_OUTPUT}',
9
        sagemaker_session=sagemaker.Session(),
10
    )
11
    hyperparams.update({'predictor_type': 'classifier'})
12
    estimator.set_hyperparameters(**hyperparams)
13
    return estimator
14

15

16
def train(estimator: Estimator, train_object_path: str, test_object_path: str) -> None:
17
    train_input = TrainingInput(train_object_path, content_type='text/csv', input_mode='Pipe')
18
    test_input = TrainingInput(test_object_path, content_type='text/csv', input_mode='Pipe')
19
    estimator.fit({'train': train_input, 'test': test_input})
20

21

22
if __name__ == '__main__':
23
    knn = get_estimator(k=1, sample_size=1000)
24
    train(knn, train_object_path, test_object_path)

After starting the training job, you will observe logs similar to the following:

1
2022-01-08 13:38:34 Starting - Starting the training job...
2
2022-01-08 13:38:57 Starting - Launching requested ML instancesProfilerReport-1641649113: InProgress
3
......
4
[01/08/2022 13:43:00 INFO 140667182901056] #test_score (algo-1) : ('accuracy', 0.9736842105263158)
5
[01/08/2022 13:43:00 INFO 140667182901056] #test_score (algo-1) : ('macro_f_1.000', 0.97170347)

The log provides metrics like accuracy and macro F1 score, offering insights into the model’s performance on the test dataset.
Leveraging both the train and test channels during training ensures the built-in algorithm evaluates the model’s generalization ability automatically.

ECR URI

The image_uri (line 3) specifies the ECR container URI of the k-NN training algorithm provided by AWS.

For detailed information about the container URIs for built-in algorithms, refer to the official documentation.

Channel Names

The channel name (line 18) for built-in algorithms in SageMaker is fixed to train. If you include a test channel during the training job creation, your ML model will automatically be evaluated on the test data after training.

Using Pipe Mode

To enhance data streaming efficiency, you can enable Pipe mode by setting the input_mode (line 7) parameter to "Pipe" in the TrainingInput definition. Pipe mode streams data directly from S3 to the SageMaker instance, reducing the latency and memory requirements associated with downloading the entire dataset.

k-NN Hyperparameters

The k-NN algorithm includes several configurable hyperparameters. For complete details on their usage and effects, consult the official documentation.

Inference

Deploy the trained model to an endpoint and validate predictions.

The serializer and deserializer in SageMaker are used to specify the formats for input and output data when interacting with a deployed inference endpoint.

Serializer
- CSVSerializer: Converts data into CSV format.
- JSONSerializer: Converts data into JSON format.
- NumpySerializer: Converts NumPy arrays into binary format.
Deserializer
- JSONDeserializer: Converts JSON responses into Python dictionaries or lists.
- BytesDeserializer: Returns raw bytes.

1
def deploy(estimator: Estimator) -> Predictor:
2
    return estimator.deploy(
3
        initial_instance_count=1,
4
        instance_type=PREDICTOR_INSTANCE_TYPE,
5
        serializer=CSVSerializer(),
6
        deserializer=JSONDeserializer(),
7
        endpoint_name=PREDICTOR_ENDPOINT_NAME,
8
    )
9

10

11
def validate(predictor: Predictor, test_df: pd.DataFrame) -> pd.DataFrame:
12
    rows = []
13
    for _, data in test_df.iterrows():
14
        predict = predictor.predict(
15
            pd.DataFrame([data.drop('Species')]).to_csv(header=False, index=False),
16
            initial_args={'ContentType': 'text/csv'},
17
        )
18
        predicted_label = predict['predictions'][0]['predicted_label']
19
        row = data.tolist()
20
        row.append(predicted_label)
21
        row.append(data['Species'] == predicted_label)
22
        rows.append(row)
23
    return pd.DataFrame(rows, columns=('Species', 'Sepal.Length', 'Sepal.Width', 'Petal.Length', 'Petal.Width', 'Prediction', 'Result'))
24

25

26
if __name__ == '__main__':
27
    predictor = deploy(knn)
28
    predictions = validate(predictor, test_df)
29
    display(predictions)

The inference results will include the Prediction and Result columns.

Prediction: The predicted label for each sample provided to the model.
Result: A boolean value (True or False) indicating whether the prediction matches the actual label.

Cleaning Up

The trained model and its endpoint can be removed with:

1
def delete_model(predictor: Predictor) -> None:
2
    predictor.delete_model()
3

4

5
def delete_endpoint(predictor: Predictor) -> None:
6
    predictor.delete_endpoint(delete_endpoint_config=True)
7

8

9
if __name__ == '__main__':
10
    delete_model(predictor)
11
    delete_endpoint(predictor)

Conclusion

Training and deploying a k-NN classifier on the Iris dataset in SageMaker Studio produced a working inference endpoint without writing a training script or building a container.

Retrieving the training image with image_uris.retrieve('knn', ...) and setting input_mode='Pipe' are what make the built-in algorithm practical here — Pipe mode streams the CSV data from S3 directly into the instance instead of downloading the full dataset first. Passing both a train and test channel to estimator.fit() is what triggers SageMaker’s automatic evaluation, producing the accuracy and macro_f_1.000 metrics seen in the training logs without any extra validation code.

The 97% accuracy achieved here reflects how cleanly separated the Iris species already are in feature space, so it’s worth remembering to actually delete the deployed endpoint afterward — it keeps billing by the hour for as long as it stays up, dataset difficulty aside.