Packaging an R model for Seldon Core using s2i (incubating)

In this guide, we illustrate the steps needed to wrap your own R model in a docker image ready for deployment with Seldon Core using source-to-image app s2i. If you prefer to use plain Docker, see the Docker instructions.

If you are not familiar with s2i you can read general instructions on using s2i and then follow the steps below.

Step 1 - Install s2i

Download and install s2i

  • Prerequisites for using s2i are:
    • Docker
    • Git (if building from a remote git repo)

To check everything is working you can run

s2i usage seldonio/seldon-core-s2i-r:0.1

Step 2 - Create your source code

To use our s2i builder image to package your R model you will need:

  • An R file which provides an S3 class for your model via an initialise_seldon function and that has appropriate generics for your component, e.g. predict for a model.
  • An optional install.R to be run to install any libraries needed
  • .s2i/environment - model definitions used by the s2i builder to correctly wrap your model

We will go into detail for each of these steps:

R Runtime Model file

Your source code should contain an R file which defines an S3 class for your model. For example, looking at our skeleton R model file at incubating/wrappers/s2i/R/test/model-template-app/MyModel.R:

library(methods)

predict.mymodel <- function(mymodel,newdata=list()) {
  write("MyModel predict called", stdout())
  newdata
}


new_mymodel <- function() {
  structure(list(), class = "mymodel")
}


initialise_seldon <- function(params) {
  new_mymodel()
}
  • A seldon_initialise function creates an S3 class for my model via a constructor new_mymodel. This will be called on startup and you can use this to load any parameters your model needs.
  • A generic predict function is created for my model class. This will be called with a newdata field with the data.frame to be predicted.

There are similar templates for ROUTERS and TRANSFORMERS.

install.R

Populate an install.R with any software dependencies your code requires. For example:

install.packages('rpart')

.s2i/environment

Define the core parameters needed by our R builder image to wrap your model. An example is:

MODEL_NAME=MyModel.R
API_TYPE=REST
SERVICE_TYPE=MODEL
PERSISTENCE=0

These values can also be provided or overridden on the command line when building the image.

Step 3 - Build your image

Use s2i build to create your Docker image from source code. You will need Docker installed on the machine and optionally git if your source code is in a public git repo.

Using s2i you can build directly from a git repo or from a local source folder. See the s2i docs for further details. The general format is:

s2i build <git-repo> seldonio/seldon-core-s2i-r:0.1 <my-image-name>
s2i build <src-folder> seldonio/seldon-core-s2i-r:0.1 <my-image-name>

An example invocation using the test template model inside seldon-core:

s2i build https://github.com/seldonio/seldon-core.git --context-dir=incubating/wrappers/s2i/R/test/model-template-app seldonio/seldon-core-s2i-r:0.1 seldon-core-template-model

The above s2i build invocation:

  • uses the GitHub repo: https://github.com/seldonio/seldon-core.git and the directory incubating/wrappers/s2i/R/test/model-template-app inside that repo.
  • uses the builder image seldonio/seldon-core-s2i-r
  • creates a docker image seldon-core-template-model

For building from a local source folder, an example where we clone the seldon-core repo:

git clone https://github.com/seldonio/seldon-core.git
cd seldon-core
s2i build incubating/wrappers/s2i/R/test/model-template-app seldonio/seldon-core-s2i-r:0.1 seldon-core-template-model

For more help see:

s2i usage seldonio/seldon-core-s2i-r:0.1
s2i build --help

Reference

Environment Variables

The required environment variables understood by the builder image are explained below. You can provide them in the .s2i/environment file or on the s2i build command line.

MODEL_NAME

The name of the R file containing the model.

API_TYPE

API type to create. Can be REST only at present.

SERVICE_TYPE

The service type being created. Available options are:

  • MODEL
  • ROUTER
  • TRANSFORMER

PERSISTENCE

Can only by 0 at present. In future, will allow the state of the component to be saved periodically.