![](../logo.png)
Deployment
deployment.Rmd
The “Build a Scorecard” vignette
demonstrates how to use the scorecard()
function to create
a model object against which predict()
can be called. This
article provides a roadmap for deploying the model as a REST API service
via {plumber}, allowing your
model to be called from any other application that can make API
requests.
Saving the Model Object
The API will need access to the model object generated by the
scorecard()
function. The best way to do this is by saving
the model object to an .RDS file:
saveRDS(scorecard_fit, "scorecard_fit.rds")
Creating the API
The following plumber.R
file sets up an API endpoint
(/predict
) that accepts parameters as inputs to the
scorecard model (in our example, these represent the loan applicant’s
values for industry
and housing_status
), uses
the pre-trained scorecard model to generate predictions and returns
either points or probabilities, depending on how the
type
argument is specified.
# plumber.R
# Make `predict()` method available for object of class "scorecard"
library(KAscore)
# Read model object
scorecard_fit <- readRDS("scorecard_fit.rds")
#* @apiTitle Scorecard Prediction
#* @apiDescription API Service for Scorecard Prediction
#* @apiVersion 1.0
#* Predict points or prob for new loans
#* @param industry (String) The class within the industry independent variable
#* @param housing_status (String) The class within the housing_status independent variable
#* @param type (String) One of "points" or "prob", indicating the type of prediction to return
#* @post /predict
function(industry, housing_status, type) {
new_data <- tibble::tribble(
~industry, ~housing_status,
industry, housing_status
)
predict(
object = scorecard_fit,
newdata = new_data,
type = type
)
}
Testing the API Locally
To launch the API locally, run the following command from the R
console. You can specify the port on the server to launch the API at by
using the port
argument from the
plumber::pr_run()
function. For example:
plumber::pr("plumber.R") |>
plumber::pr_run(port = 8080)
Calling the API
Terminal / Command Prompt
You can use the curl
command to call the API using the
terminal, command prompt, shell, etc.
curl -X POST "http://127.0.0.1:8080/predict?industry=poultry&housing_status=own&type=points
R
As long as the API is running, you can even call it from another R session (using {httr}, for example).
call_api <- function(industry, housing_status, type, port = 8080) {
res <- httr::POST(
glue::glue("http://127.0.0.1:{ port }/predict"),
query = list(
industry = industry,
housing_status = housing_status,
type = type
)
)
res$content |>
rawToChar() |>
jsonlite::fromJSON()
}
# Get points
call_api(
industry = "poultry",
housing_status = "own",
type = "points"
)
## 254
# Get prob
call_api(
industry = "poultry",
housing_status = "own",
type = "prob"
)
## 0.141
Containerizing the API with Docker
In order to safely ship the REST API service we created locally to another machine (e.g., a cloud-based server), we can containerize it using Docker.
Docker is a virtualization software that allows you to package your code, files, and operating system into a fully reproducible environment called a “container”. This ensures that the behavior your software produces on your local computer will be identical to the behavior your software produces on any other server.
The following steps demonstrate how to create a Docker container image that serves our scorecard REST API in a way that can be easily deployed on any server.
Step 1: Create a Dockerfile
A Dockerfile is a set of instructions on how to create the Docker image. For the purposes of deploying your scorecard model, we recommend creating a Dockerfile similar to this one:
# Dockerfile
# Base image
FROM eddelbuettel/r2u:22.04
# Define an argument for the version of KAscore
ARG KASCORE_VERSION=1.2.0
# Set an environment variable for the KAscore path
ENV KASCORE_PATH=KAscore_${KASCORE_VERSION}.tar.gz
# Copy necessary files into the container
COPY scorecard_fit.rds plumber.R ${KASCORE_PATH} .
# Install required R packages
RUN install2.r remotes plumber
# Install KAscore package from tarball provided by Ketchbrook
RUN R -e 'remotes::install_local(Sys.getenv("KASCORE_PATH"))'
# Expose port 3838
EXPOSE 3838
# Define the command to run the R script that launches the API
CMD ["R", "-e", "plumber::pr('plumber.R') |> plumber::pr_run(host = '0.0.0.0', port = 3838)"]
Step 2: Build the Docker image
In your terminal, navigate to the directory containing your
Dockerfile, scorecard_fit.rds
object,
plumber.R
script and KAscore_1.2.0.tar.gz
file
and execute the following command to build the Docker image:
docker build -t scorecard-api .
Step 3: Run the Docker container
After building the Docker image, you can run it using the following command:
docker run -d --rm -p 3838:3838 --name scorecard-api-container scorecard-api
Step 4: Access the API
You can navigate to http://127.0.0.1:3838/__docs__/ in your local web browser to access the interactive API documentation generated by Plumber. This is a convenient way to verify that the API is working as expected.
We can now send requests to http://127.0.0.1:3838/predict:
call_api(
industry = "poultry",
housing_status = "own",
type = "prob",
port = 3838
)
Deployment
There are a multitude of hosting options for deploying a REST API as a service that can be consumed by others. In decades past, organizations may have deployed on their own physical infrastructure. Nowadays most organizations turn to cloud-based services for deploying REST APIs. Such cloud providers include Microsoft Azure, Amazon Web Services, Google Cloud Platform, DigitalOcean, and many more.
Microsoft Azure
Currently, Azure Container Instances is one of the most popular options for deploying API services on the Azure cloud. This tutorial walks you through setting up a containerized REST API service using the Azure portal.
Prior to doing this, however, you will need to push the Docker image you created in Part 2, above, to a container registry. There are multiple container registries where you can push your Docker image to, but perhaps the two most popular for this setup would be Azure Container Registry or Docker Hub.
More Information
For more information on deploying your scorecard as a REST API service on Azure, AWS, GCP, DigitalOcean, or other cloud providers, please reach out to info@ketchbrookanalytics.com. Our team has extensive experience deploying R and Python models as REST API services that can be consumed by others inside and/or outside your organization.