Deploying your first model with Matcha
In this guide, we'll walk you through how to provision your first machine learning infrastructure to Azure, and then use that infrastructure to train and deploy a model. The model we're using is a movie recommender, and we picked this because it's one that beginners can get up and running with quickly.
There are five things we'll cover:
- Pre-requisites: everything you need to set up before starting.
- The movie recommender: downloading the example code and setting up your Python environment
- Provisioning: Using Matcha to provision your infrastructure
- Training and deploying: training a model on your provisioned infrastructure, deploying, and testing it
- Destroying: tearing down provisioned infrastructure
The movie recommender is one among several of example workflows that we've made available on Github; you can view all our examples here.
Note: Matcha is still in alpha release. While we've worked hard to ensure there are no defects, there's a small chance that you'll find a bug or something that hasn't been documented as well as it could be. If that happens, we'd really value your feedback, which you can send by submitting an issue to Matcha on Github.
Pre-requisites
An Azure cloud environment
Matcha uses Azure to provision your infrastructure, so first you'll need to set up a Microsoft® Azure account.
Tools you'll need
Next, you'll need to install a couple of things.
- Python 3.8 or newer, along with Virtual Env and PIP.
- The Azure command line tool. Instructions on installing this can be found here.
- Terraform. We use this to provision services inside Azure. You'll find installation instructions for your platform here. We recommend version 1.4 or newer.
The movie recommender
Matcha has an examples repository on Github, and that's what we'll be working from in this guide. There are a number of different examples in that repository, but we'll focus on the movie recommender. Note, however, that all the examples have been designed to work in much the same way as this one.
Start by cloning the examples repository:
git clone https://github.com/fuzzylabs/matcha-examples.git
Then, enter the recommendation
directory and set up your Python environment:
cd recommendation
python3 -m venv venv
source venv/bin/activate
Now, let's install Matcha:
pip install matcha-ml
You can test that your installation is working by running
matcha --version
Which should reply with something like Matcha version: <version number>
.
Now you're ready to provision your infrastructure.
Provisioning
Using the Azure CLI, you will need to authenticate:
az login
When you run this command, you'll be taken to the Azure login screen in a web browser window, and you'll be asked if you want to allow the Azure CLI to access your Azure account. You'll need to grant this permission in order for Matcha to gain access to your Azure account when it provisions infrastructure.
Note: you'll need certain permissions in order for Matcha to work. If you're unsure, you can just run
matcha
and it will tell you if you're missing any permissions. For specifics around permissions, please see our explainer on Azure Permissions.
Next, let's provision:
matcha provision
Initially, Matcha will ask you a few questions about how you'd like your infrastructure to be set up. Specifically, it will ask for a name for your infrastructure, a region to deploy it to. Once these details are provided, Matcha will proceed to initialize a remote state manager and ask for a password. After that, it will go ahead of provision infrastructure.
Note: provisioning can take up to 20 minutes.
Once provisioning is completed, you can query Matcha, using the get
command:
matcha get
You should have something similar to the following output:
Cloud
- flavor: azure
- resource-group-name: example-resources
Container registry
- flavor: azure
- registry-name: crexample
- registry-url: <url>
Experiment tracker
- flavor: mlflow
- tracking-url: <url>
Model deployer
- flavor: seldon
- base-url: <url>
- workloads-namespace: matcha-seldon-workloads
Orchestrator
- flavor: aks
- k8s-context: terraform-example-k8s
Pipeline
- flavor: zenml
- connection-string: ********
- server-password: ********
- server-url: <url>
- server-username: ********
- storage-path: az://<path>
You can also use get
to inspect specific resources, for example:
matcha get experiment-tracker
With the following output:
Below are the resources provisioned.
Experiment tracker
- flavor: mlflow
- tracking-url: <url>
Note: You can also get these outputs in either json or YAML format using the following:
matcha get --output json
By default, Matcha will hide sensitive resource properties. If you need one of these properties, then you can add the --show-sensitive
flag to your get
command.
Training and deploying
Now that you've reached this point, you'll have provisioned the following infrastructure into Azure:
- The MLFlow experiment tracker and model registry.
- Seldon for model deployment and serving.
- A ZenML server. This example uses ZenML for defining and orchestrating the training and deployment pipelines.
- Kubernetes. This has two roles: firstly, it's where the training workload actually runs, and secondly it's the deployment environment for all of the above components.
Setup
Setting up
Before you can train the model, there's a little setup to do. We've provided a convenient script that does this for you:
./setup.sh
You might wonder why this setup step is necessary, and what it's doing. While you've already set Matcha up, the code that will train the model needs to know a few things about your infrastructure before it can run. As you've seen, matcha get
is what's used to query information about your infrastructure. Under the hood, the setup script for the movie recommender model actually invokes matcha get
to find out everything it needs to know. Additionally, this script installs some Python dependencies that are specific to the machine learning task that we're working with; crucially, the Surprise library, which is part of Scikit-learn, which we're using to do the recommendation bit itself.
Training
Once the setup script completes, you're ready to train the model:
python run.py --train
Experiment tracking
Training won't take too long. After it finishes, you'll be able to view the details of this training run in MLFlow. First, look up the URL to MLFlow:
matcha get experiment-tracker
Copy the tracking URL into a web browser. Then, from the experiments
pane on the left-hand side of the MLFlow interface, you'll be able to select recommendation_pipeline
. Each time the training pipeline runs, it will be logged here, so you can view historical runs alongside important details such as the training parameters or the model performance.
Deploying
Your model has been trained, but we can't interact with it until it has been deployed. Alongside the training pipeline, the movie recommender example includes a deployment pipeline, which will result in the model being deployed to Seldon, and made accessible as a web service.
Run
python run.py --deploy
Once this has completed, you can test the model out. We've included a convenience script to help with this, called inference.py
:
python inference.py --user 100 --movie 100
This will result in a score, which represents how strongly we recommend movie ID 100
to user ID 100
.
Destroying
The final thing you'll want to do is decommission the infrastructure that Matcha has set up during this guide. Matcha includes a destroy
command which will remove everything that has been provisioned, which avoids running up an Azure bill!
To destroy the provisioned resources only, run:
matcha destroy
To destroy both the provisioned resources and remote state management, run:
matcha destroy full