Deploying PMML Model to Openscoring REST Evaluation Service

This article will guide you through the steps of deploying a PMML predictive model on our REST API based scoring service. It follows the guidelines provided in the project README file and tries to simplify some aspects for non-Java non-programmers :-) This is seriously entry level, so feel free to skip the parts you've gone through or done before (like GitHub or Java environment setup).


Why Care?

During many conversations with our licensees, we've found out that it's unnecessarily complex to deploy and execute a PMML model. Providing a REST API is a step towards simplifying the usage of PMML models. We also provide a range of converters which let you first convert your Scikit-learn, R or Apache Spark proprietary model formats to standard PMML.

We strongly believe that using standardized PMML model format is the future of machine learning models. Having a text-based representation gives you the following advantages:

  • The models are human readable (and although not suggested - can be modified if necessary)
  • The models can be properly versioned - you can use version control tools (even GitHub) to manage your models, see the differences of versions, etc
  • You're not married to some proprietary software that costs six-figure numbers :-)
  • And so on - probably we'll do a whole article about them in the future.


Necessary software

This guide is written for Windows 10. GitHub Desktop seems to be the only piece not available on Linux, but there sure are differences when it comes to setting environment variables and so on.

You will need the following software present to conveniently go through the below steps:

  1. GitHub Desktop
  2. Java JDK version 8.x (we're moving to JDK 9 soon)
  3. Maven
  4. Postman


Pulling the Sources

Run GitHub desktop - you should get to the following screen:

From there you need to choose Clone a repository, locate the URL tab and enter '':


Now you've got the source code on your machine and next step is building the application.


Building and Running the Application

For building you need to have both JDK and Maven installed.

Make sure you have both maven\bin and java\bin on your path. You can execute the following commands from your command prompt, just make sure you change the actual path according to your installation:

setx path "%path%;C:\apache-maven-3.5.2\bin"
setx path "%path%;C:\Program Files\Java\jdk1.8.0_161\bin"

Read this guide how to set JAVA_HOME (it's a system variable and cannot be set from command line unless you're admin).

Now open command prompt and navigate to where your Openscoring sources are and start the build: 

cd c:\github\openscoring
c:\github\openscoring> mvn clean install

This will take a few minutes as all the dependencies are downloaded, code is compiled and tests are run. It should end with the following messages:

Now navigate to openscoring-server directory from command line and run the following command:

C:\github\openscoring>cd openscoring-server
C:\github\openscoring\openscoring-server>java -jar target/server-executable-1.4-SNAPSHOT.jar

This should result the Openscoring server running:

Now Openscoring service is listening at http://localhost:8080/openscoring/. You can navigate there using your browser, but as there're no models deployed, it will result with an error message for now.


Deploying the Model Using Postman

Postman is a very simple and intuitive tool for sending HTTP requests. It requires registration, but this is worth the two minutes.

Now we're finally ready to deploy the model. Example PMML file and requests are located in openscoring\openscoring-service\src\etc directory. You need to pay attention to a few things:

  • Method must be PUT
  • URL must be http://localhost:8080//openscoring/model/<model name> (model name is something you should choose)
  • Content-Type header must be set to application/xml
  • In Body tab, you should choose binary and also locate the model PMML file (again, the examples are in openscoring\openscoring-service\src\etc directory, choose DecisionTreeIris.pmml from there)

And then you can click SEND. This is what should appear in a moment:

In the response body, you see the deployed model in JSON format. This means that the model is deployed and accessible at the endpoint you specified, in my example http://localhost:8080/openscoring/model/DecisionTreeIris.


Executing the Deployed PMML Model

When making the scoring request, you need to keep an eye on the following items:

  • HTTP method must be POST
  • URL will remain the same
  • On Body tab, choose raw and set the content type application/json (this will also change the Content-Type header on Headers tab)
  • The following request can be pasted to Body window:
    "id" : "record-001",
    "arguments" : {
        "Sepal_Length" : 5.1,
        "Sepal_Width" : 3.5,
        "Petal_Length" : 1.4,
        "Petal_Width" : 0.2

And there you go - based on the DecisionTreeIris model, your iris is of 'setosa' type with the probability score of 1.

You can check out the other methods in Openscoring REST API from the documentation.