[This is an updated version of an article published by Oracle Magazine in 2019.]

One of the biggest challenges of working with machine learning (ML) projects is putting the models into production. Traditionally this has involved changing architectures; porting to other software; and, in some cases, rewriting the models in other languages, such as Java or C.

With Oracle Machine Learning, putting a model into production is no longer a challenge. With RESTful services, in-database ML models can be made available to application developers—no matter which programming language or tools they use.

This article walks you through the steps of REST-enabling an ML model created with Oracle Autonomous Database.

Let’s work through an example

This article starts with one of the sample Oracle Machine Learning notebooks, “Picking a good wine for <$20,” and will REST-enable the ML model that notebook creates. To get started, first load the sample notebook into your ML notebook and run it. This will execute the notebook code and generate the ML model.

Here is the CREATE_MODEL command used in the notebook to create the “Wine” model. This is just a subset of the code from the notebook, and Figure 1 shows more of the Wine model code.

 
-- Build a Classification Model
EXECUTE IMMEDIATE 
'CALL DBMS_DATA_MINING.CREATE_MODEL(''Wine_CLASS_MODEL'',
''CLASSIFICATION'', ''Wine_TRAIN_DATA'', ''ID'','' POINTS_BIN'',
''Wine_build_settings'')';
DBMS_OUTPUT.PUT_LINE ('Created model: Wine_CLASS_MODEL ');

Figure 1: Creating the ML model for Wine model predictions

Approximately 20 different SQL functions are available to call and interact with in-database ML models. Two of the most commonly used functions are PREDICTION and PREDICTION_PROBABILITY. These return the predicted outcome from the model and a probability score, respectively, to indicate how strong a prediction is.

One option for putting the in-database ML model into production is to enable the developers to call these PREDICTION and PREDICTION_PROBABILITY SQL functions directly. For instance, the following example uses SQL to call the Wine ML model and pass the values to use to make the prediction.

 
select prediction(Wine_CLASS_MODEL USING
                'Portugal' as country,
                   'Douro' as province,
                        30 as price,
           'Portuguese Red' as variety) pred_wine,
from dual;

An alternative approach is to use RESTful Services, which allow for easier use across a variety of development environments.

Oracle Application Express (Oracle APEX) comes with Oracle Autonomous Data Warehouse and Oracle Autonomous Transaction Processing, and APEX provides access to Oracle REST Data Services, which, in turn, exposes RESTful services to developers. Before you can expose and use the RESTful services, you first need to enable them. To do so in Autonomous Data Warehouse or Autonomous Transaction Processing, log in to APEX with the schema you used to create the ML notebook. You may need to first connect as the APEX admin user and set up your schema to use APEX. After logging in to your schema in APEX—in my example, I log in as OML_USER—from the SQL Workshop tab menu, select RESTful services, as shown in Figure 2.

Figure 2: Accessing RESTful services in APEX

If RESTful services have not been set up for your schema, you will be notified that the schema is not registered with Oracle REST Data Services. Click Register Schema with ORDS, as shown in Figure 3. In the pop-up window, click Yes for Install Sample Service to install some examples from which you can learn, as shown in Figure 4.

Figure 3: Registering the schema with Oracle REST Data Services

Figure 4: Installing sample services

With the RESTful sample services installed, you should be able to see the sample REST APIs shown in Figure 5. These examples demonstrate different types of REST APIs with GET and POST functions, returning data in CSV and JSON formats.

Figure 5: Sample REST APIs created in APEX

Now let’s create a simple REST API to display the Wine dataset. To do this, first click the Create Template button, halfway down the page on the right side. Enter the name wine in the URI Template field, as shown in Figure 6. The process will automatically generate a URL to point to the REST API and display it in the Full URL field.

Figure 6: Creating a simple REST API template

The next step is to create a handler, which can be GET, POST, or DELETE. The GET method will be used to call the in-database ML model. As shown in Figure 7, create the GET method, specifying Query for Source Type and JSON or CSV for Format. In the Source box, enter the following SQL query to retrieve all the records:

select * from winereviews130k

Figure 7: Creating the GET method

After saving the method, copy the text in the Full URL field, open a web browser, and paste the URL into the address bar. This will display the list of wines in the table, as shown in Figure 8.

Figure 8: Results from Wine REST API

Using the SQL query shown earlier (SELECT PREDICTION . . . FROM DUAL) to demonstrate how to call the in-database ML algorithm, let’s now create a RESTful API for it. Figure 9 shows the full setup for calling the in-database ML model. The first red box highlights the URI Template field, which defines the name of the API and the parameters. The second red box highlights Source Type as Query One Row, because the SQL query will return only one row. Format is set to JSON. The third red box contains the SQL query (Source), which includes the parameters referenced in the URI Template field. The parameters are identified with a colon preceding the parameter name.

Figure 9: REST API for in-database ML model

Copy the REST API, and paste it into the web browser address field. But before running it, change the values for the parameters to the actual values to pass to the REST API, for example:

…/oml_user/wine/wine_pred/Portugal/Douro/Portuguese Red/30

Figure 10 displays the results from calling the REST API with these parameter values.

Figure 10: Running the in-database ML model with the REST API and a $30 price

Figure 11 shows that changing one value—the price of the wine—

…/oml_user/wine/wine_pred/Portugal/Douro/Portuguese Red/31

and rerunning the REST API call returns different results:

Figure 11: Rerunning the in-database ML model with the REST API and $31 price

It is easy to see the benefits of using these REST APIs to call ML models. An additional benefit is that when a model is updated or modified, developers do not need to modify their applications.

The REST APIs can also be called from other languages, such as Java, C, or Python. The following example uses Python and two libraries to call a REST API. The json library is needed for printing and displaying the JSON object returned by the REST API, and the requests library is needed to make the call out to the REST API. The first call to the REST API calls the ML model and makes a prediction based on the country, province, variety, and price of the wine ($30). The second call uses a different value for the price ($31). The output shows the predicted result: Paying $1 more might make getting a better bottle of wine possible.

 
import json
import requests

rest_api = '<full REST API>'

country = 'Portugal'
province = 'Douro'
variety = 'Portuguese Red'
price = 30

resp = requests.get(rest_api+country+'/'+province+'/'+variety+'/'+str(price))
json_data = resp.json()
print('Predictions for Price = ', price)
print(json.dumps(json_data, indent=2))

#change the price to $31
price = 31

resp = requests.get(rest_api+country+'/'+province+'/'+variety+'/'+str(price))
json_data = resp.json()
print('')
print('Predictions for Price = ', price)
print(json.dumps(json_data, indent=2))


Predictions for Price =  30
{
  "pred_wine": "LT_90_POINTS",
  "prob_wine": 0.6844716987704507
}

Predictions for Price =  31
{
  "pred_wine": "GT_90_POINTS",
  "prob_wine": 0.5137163891143298
}

Conclusion

Using RESTful services is an easy and efficient way to expose in-database ML models to a wide variety of development languages and frameworks, which makes it easy for developers to add ML to their applications. The in-database ML examples shown in this article were built on Oracle Autonomous Database and used the RESTful services interface of Oracle Application Express.

Dig deeper

• Learn more about Oracle Machine Learning notebooks.
• Read more about using Oracle Machine Learning notebooks.
• Try Always Free cloud services.
• Explore Oracle Machine Learning notebooks on GitHub.

Illustration: Wes Rowell