Red Hat SummitDesigning a decision service using PMML models
Abstract
Preface
As a business rules developer, you can use Predictive Model Markup Language (PMML) to define statistical or data-mining models that you can integrate with your decision services in Red Hat Decision Manager. Red Hat Decision Manager includes consumer conformance support of PMML 4.2.1 for Regression, Scorecard, Tree, and Mining models. Red Hat Decision Manager does not include a built-in PMML model editor, but you can use an XML or PMML-specific authoring tool to create PMML models and then integrate them with your Red Hat Decision Manager projects.
For more information about PMML, see the DMG PMML specification.
Chapter 1. Predictive Model Markup Language (PMML)
Predictive Model Markup Language (PMML) is an XML-based standard established by the Data Mining Group (DMG) for defining statistical and data-mining models. PMML models can be shared between PMML-compliant platforms and across organizations so that business analysts and developers are unified in designing, analyzing, and implementing PMML-based assets and services.
For more information about the background and applications of PMML, see the DMG PMML specification.
1.1. PMML conformance levels
The PMML specification defines producer and consumer conformance levels in a software implementation to ensure that PMML models are created and integrated reliably. For the formal definitions of each conformance level, see the DMG PMML conformance page.
The following are summaries of the PMML conformance levels:
- Producer conformance
- A tool or application is producer conforming if it generates valid PMML documents for at least one type of model. Satisfying PMML producer conformance requirements ensures that a model definition document is syntactically correct and defines a model instance that is consistent with semantic criteria that are defined in model specifications.
- Consumer conformance
- An application is consumer conforming if it accepts valid PMML documents for at least one type of model. Satisfying consumer conformance requirements ensures that a PMML model created according to producer conformance can be integrated and used as defined. For example, if an application is consumer conforming for Regression model types, then valid PMML documents defining models of this type produced by different conforming producers would be interchangeable in the application.
Red Hat Decision Manager includes consumer conformance support for the following PMML 4.2.1 model types:
- Regression models
- Scorecard models
- Tree models
-
Mining models (with sub-types
modelChain,selectAll, andselectFirst)
For a list of all PMML model types, including those not supported in Red Hat Decision Manager, see the DMG PMML specification.
Chapter 2. PMML model examples
PMML defines an XML schema that enables PMML models to be used between different PMML-compliant platforms. The PMML specification enables multiple software platforms to work with the same file for authoring, testing, and production execution, assuming producer and consumer conformance are met.
The following are examples of PMML Regression, Scorecard, Tree, and Mining models. These examples illustrate the supported types of models that you can integrate with your decision services in Red Hat Decision Manager.
For more PMML examples, see the DMG PMML Sample Files page.
Example PMML Regression model
Example PMML Scorecard model
Example PMML Tree model
Example PMML Mining model (modelChain)
Chapter 3. PMML support in Red Hat Decision Manager
Red Hat Decision Manager includes consumer conformance support for the following PMML 4.2.1 model types:
- Regression models
- Scorecard models
- Tree models
-
Mining models (with sub-types
modelChain,selectAll, andselectFirst)
For a list of all PMML model types, including those not supported in Red Hat Decision Manager, see the DMG PMML specification.
Red Hat Decision Manager does not include a built-in PMML model editor, but you can use an XML or PMML-specific authoring tool to create PMML models and then integrate the PMML models in your decision services in Red Hat Decision Manager. You can import PMML files into your project in Business Central (Menu → Design → Projects → Import Asset) or package the PMML files as part of your project knowledge JAR (KJAR) file without Business Central.
When you add a PMML file to a project in Red Hat Decision Manager, multiple assets are generated. Each type of PMML model generates a different set of assets, but all PMML model types generate at least the following set of assets:
- A DRL file that contains all of the rules associated with your PMML model
At least two Java classes:
- A data class that is used as the default object type for the model type
-
A
RuleUnitclass that is used to manage data sources and rule execution
If a PMML file has MiningModel as the root model, multiple instances of each of these files are generated.
For more information about including assets such as PMML files with your project packaging and deployment method, see Packaging and deploying a Red Hat Decision Manager project.
3.1. PMML naming conventions in Red Hat Decision Manager
The following are naming conventions for generated PMML packages, classes, and rules:
-
If no package name is given in a PMML model file, then the default package name
org.kie.pmml.pmml_4_2is prefixed to the model name for the generated rules in the format"org.kie.pmml.pmml_4_2"+modelName. -
The package name for the generated
RuleUnitJava class is the same as the package name for the generated rules. -
The name of the generated
RuleUnitJava class is the model name withRuleUnitadded to it in the formatmodelName+"RuleUnit". -
Each PMML model has at least one data class that is generated. The package name for these classes is
org.kie.pmml.pmml_4_2.model. The names of generated data classes are determined by the model type, prefixed with the model name:
-
Regression models: One data class named
modelName+"RegressionData" -
Scorecard models: One data class named
modelName+"ScoreCardData" -
Tree models: Two data classes, the first named
modelName+"TreeNode"and the second namedmodelName+"TreeToken" -
Mining models: One data class named
modelName+"MiningModelData"
-
Regression models: One data class named
The mining model also generates all of the rules and classes that are within each of its segments.
3.2. PMML extensions in Red Hat Decision Manager
The PMML specification supports Extension elements that extend the content of a PMML model. You can use extensions at almost every level of a PMML model definition, and as the first and last child in the main element of a model for maximum flexibility. For more information about PMML extensions, see the DMG PMML Extension Mechanism.
To optimize PMML integration, Red Hat Decision Manager supports the following additional PMML extensions:
-
modelPackage: Designates a package name for the generated rules and Java classes. Include this extension in theHeadersection of the PMML model file. -
adapter: Designates the type of construct (beanortrait) that is used to contain input and output data for rules. Insert this extension in theMiningSchemaorOutputsection (or both) of the PMML model file. -
externalClass: Used in conjunction with theadapterextension in defining aMiningFieldorOutputField. This extension contains a class with an attribute name that matches the name of theMiningFieldorOutputFieldelement.
Chapter 4. PMML model execution
You can import PMML files into your Red Hat Decision Manager project using Business Central (Menu → Design → Projects → Import Asset) or package the PMML files as part of your project knowledge JAR (KJAR) file without Business Central. After you implement your PMML files in your Red Hat Decision Manager project, you can execute the PMML-based decision service by embedding PMML calls directly in your Java application or by sending an ApplyPmmlModelCommand command to a configured Decision Server.
For more information about including PMML assets with your project packaging and deployment method, see Packaging and deploying a Red Hat Decision Manager project.
4.1. Embedding a PMML call directly in a Java application
A KIE container is local when the knowledge assets are either embedded directly into the calling program or are physically pulled in using Maven dependencies for the KJAR. You typically embed knowledge assets directly into a project if there is a tight relationship between the version of the code and the version of the PMML definition. Any changes to the decision take effect after you have intentionally updated and redeployed the application. A benefit of this approach is that proper operation does not rely on any external dependencies to the run time, which can be a limitation of locked-down environments.
Using Maven dependencies enables further flexibility because the specific version of the decision can dynamically change (for example, by using a system property), and it can be periodically scanned for updates and automatically updated. This introduces an external dependency on the deploy time of the service, but executes the decision locally, reducing reliance on an external service being available during run time.
Prerequisites
- A KJAR containing the PMML model to execute has been created. For more information about project packaging, see Packaging and deploying a Red Hat Decision Manager project.
Procedure
In your client application, add the following dependencies to the relevant classpath of your Java project:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow The
<version>is the Maven artifact version for Red Hat Decision Manager currently used in your project (for example, 7.18.0.Final-redhat-00002).NoteInstead of specifying a Red Hat Decision Manager
<version>for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your projectpom.xmlfile. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.Example BOM dependency:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For more information about the Red Hat Business Automation BOM, see What is the mapping between RHDM product and maven library version?.
Create a KIE container from
classpathorReleaseId:KieServices kieServices = KieServices.Factory.get(); ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" ); KieContainer kieContainer = kieServices.newKieContainer( releaseId );
KieServices kieServices = KieServices.Factory.get(); ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" ); KieContainer kieContainer = kieServices.newKieContainer( releaseId );Copy to Clipboard Copied! Toggle word wrap Toggle overflow Alternative option:
KieServices kieServices = KieServices.Factory.get(); KieContainer kieContainer = kieServices.getKieClasspathContainer();
KieServices kieServices = KieServices.Factory.get(); KieContainer kieContainer = kieServices.getKieClasspathContainer();Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create an instance of the
PMMLRequestDataclass, which applies your PMML model to a set of data:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create an instance of the
PMML4Resultclass, which holds the output information that is the result of applying the PMML-based rules to the input data:Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- Used when the model type is
MiningModel. ThesegmentationIdis used to differentiate between multiple segmentations. - 2
- Used in conjunction with the
segmentationIdto identify which segment generated the results. - 3
- Used to maintain the order of segments.
- 4
- Used to determine whether the model was successfully applied, where
OKindicates success. - 5
- Contains the name of a resultant variable and its associated value.
In addition to the normal getter methods, the
PMML4Resultclass also supports the following methods for directly retrieving the values for result variables:public <T> Optional<T> getResultValue(String objName, String objField, Class<T> clazz, Object...params) public Object getResultValue(String objName, String objField, Object...params)
public <T> Optional<T> getResultValue(String objName, String objField, Class<T> clazz, Object...params) public Object getResultValue(String objName, String objField, Object...params)Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create an instance of the
ParameterInfoclass, which serves as a wrapper for basic data type objects used as part of thePMMLRequestDataclass:Copy to Clipboard Copied! Toggle word wrap Toggle overflow Execute the PMML model based on the required PMML class instances that you have created:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Rules are executed by the
RuleUnitExecutorclass. TheRuleUnitExecutorclass creates KIE sessions and adds the requiredDataSourceobjects to those sessions, and then executes the rules based on theRuleUnitthat is passed as a parameter to therun()method. ThecalculatePossiblePackageNamesand thegetStartingRuleUnitmethods determine the fully qualified name of theRuleUnitclass that is passed to therun()method.
To facilitate your PMML model execution, you can also use a PMML4ExecutionHelper class supported in Red Hat Decision Manager. For more information about the PMML helper class, see Section 4.1.1, “PMML execution helper class”.
4.1.1. PMML execution helper class
Red Hat Decision Manager provides a PMML4ExecutionHelper class that helps create the PMMLRequestData class required for PMML model execution and that helps execute rules using the RuleUnitExecutor class.
The following are examples of a PMML model execution without and with the PMML4ExecutionHelper class, as a comparison:
Example PMML model execution without using PMML4ExecutionHelper
Example PMML model execution using PMML4ExecutionHelper
When you use the PMML4ExecutionHelper, you do not need to specify the possible package names nor the RuleUnit class as you would in a typical PMML model execution.
To construct a PMML4ExecutionHelper class, you use the PMML4ExecutionHelperFactory class to determine how instances of PMML4ExecutionHelper are retrieved.
The following are the available PMML4ExecutionHelperFactory class methods for constructing a PMML4ExecutionHelper class:
- PMML4ExecutionHelperFactory methods for PMML assets in a KIE base
Use these methods when PMML assets have already been compiled and are being used from an existing KIE base:
public static PMML4ExecutionHelper getExecutionHelper(String modelName, KieBase kbase) public static PMML4ExecutionHelper getExecutionHelper(String modelName, KieBase kbase, boolean includeMiningDataSources)
public static PMML4ExecutionHelper getExecutionHelper(String modelName, KieBase kbase) public static PMML4ExecutionHelper getExecutionHelper(String modelName, KieBase kbase, boolean includeMiningDataSources)Copy to Clipboard Copied! Toggle word wrap Toggle overflow - PMML4ExecutionHelperFactory methods for PMML assets on the project classpath
Use these methods when PMML assets are on the project classpath. The
classPathargument is the project classpath location of the PMML file:public static PMML4ExecutionHelper getExecutionHelper(String modelName, String classPath, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName,String classPath, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)
public static PMML4ExecutionHelper getExecutionHelper(String modelName, String classPath, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName,String classPath, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)Copy to Clipboard Copied! Toggle word wrap Toggle overflow - PMML4ExecutionHelperFactory methods for PMML assets in a byte array
Use these methods when PMML assets are in the form of a byte array:
public static PMML4ExecutionHelper getExecutionHelper(String modelName, byte[] content, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName, byte[] content, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)
public static PMML4ExecutionHelper getExecutionHelper(String modelName, byte[] content, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName, byte[] content, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)Copy to Clipboard Copied! Toggle word wrap Toggle overflow - PMML4ExecutionHelperFactory methods for PMML assets in a
Resource Use these methods when PMML assets are in the form of an
org.kie.api.io.Resourceobject:public static PMML4ExecutionHelper getExecutionHelper(String modelName, Resource resource, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName, Resource resource, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)
public static PMML4ExecutionHelper getExecutionHelper(String modelName, Resource resource, KieBaseConfiguration kieBaseConf) public static PMML4ExecutionHelper getExecutionHelper(String modelName, Resource resource, KieBaseConfiguration kieBaseConf, boolean includeMiningDataSources)Copy to Clipboard Copied! Toggle word wrap Toggle overflow
The classpath, byte array, and resource PMML4ExecutionHelperFactory methods create a KIE container for the generated rules and Java classes. The container is used as the source of the KIE base that the RuleUnitExecutor uses. The container is not persisted. The PMML4ExecutionHelperFactory method for PMML assets that are already in a KIE base does not create a KIE container in this way.
4.2. Executing a PMML model using Decision Server
You can execute PMML models that have been deployed to Decision Server by sending the ApplyPmmlModelCommand command to the configured Decision Server. When you use this command, a PMMLRequestData object is sent to the Decision Server and a PMML4Result result object is received as a reply. You can send PMML requests to Decision Server through the Decision Server REST API from a configured Java class or directly from a REST client.
Prerequisites
-
Decision Server is installed and configured, including a known user name and credentials for a user with the
kie-serverrole. For installation options, see Planning a Red Hat Decision Manager installation. - A KIE container is deployed in Decision Server in the form of a KJAR that includes the PMML model. For more information about project packaging, see Packaging and deploying a Red Hat Decision Manager project.
- You have the container ID of the KIE container containing the PMML model.
Procedure
In your client application, add the following dependencies to the relevant classpath of your Java project:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow The
<version>is the Maven artifact version for Red Hat Decision Manager currently used in your project (for example, 7.18.0.Final-redhat-00002).NoteInstead of specifying a Red Hat Decision Manager
<version>for individual dependencies, consider adding the Red Hat Business Automation bill of materials (BOM) dependency to your projectpom.xmlfile. The Red Hat Business Automation BOM applies to both Red Hat Decision Manager and Red Hat Process Automation Manager. When you add the BOM files, the correct versions of transitive dependencies from the provided Maven repositories are included in the project.Example BOM dependency:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow For more information about the Red Hat Business Automation BOM, see What is the mapping between RHDM product and maven library version?.
Create a KIE container from
classpathorReleaseId:KieServices kieServices = KieServices.Factory.get(); ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" ); KieContainer kieContainer = kieServices.newKieContainer( releaseId );
KieServices kieServices = KieServices.Factory.get(); ReleaseId releaseId = kieServices.newReleaseId( "org.acme", "my-kjar", "1.0.0" ); KieContainer kieContainer = kieServices.newKieContainer( releaseId );Copy to Clipboard Copied! Toggle word wrap Toggle overflow Alternative option:
KieServices kieServices = KieServices.Factory.get(); KieContainer kieContainer = kieServices.getKieClasspathContainer();
KieServices kieServices = KieServices.Factory.get(); KieContainer kieContainer = kieServices.getKieClasspathContainer();Copy to Clipboard Copied! Toggle word wrap Toggle overflow Create a class for sending requests to Decision Server and receiving responses:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- Defines the class loader if you did not include the KJAR in your client project dependencies
- 2
- Identifies the service client as defined in the configuration settings, including Decision Server REST API access credentials
- 3
- Initializes a
PMMLRequestDataobject - 4
- Creates an instance of the
ApplyPmmlModelCommand - 5
- Sends the command using the service client
- 6
- Retrieves the results of the executed PMML model
Execute the class instance to send the PMML invocation request to Decision Server.
Alternatively, you can use JMS and REST interfaces to send the
ApplyPmmlModelCommandcommand to Decision Server. For REST requests, you use theApplyPmmlModelCommandcommand as aPOSTrequest tohttp://SERVER:PORT/kie-server/services/rest/server/containers/instances/{containerId}in JAXB or JSON request format.NoteXStream request format is currently not supported for PMML model execution in Decision Server, but will be supported in a future release.
Example POST endpoint
http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainer
http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainerCopy to Clipboard Copied! Toggle word wrap Toggle overflow Example JSON request body
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example curl request with endpoint and body
curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainer" -H "accept: application/json" -H "content-type: application/json" -d "{ \"commands\": [ { \"apply-pmml-model-command\": { \"outIdentifier\": null, \"packageName\": null, \"hasMining\": false, \"requestData\": { \"correlationId\": \"123\", \"modelName\": \"SimpleScorecard\", \"source\": null, \"requestParams\": [ { \"correlationId\": \"123\", \"name\": \"param1\", \"type\": \"java.lang.Double\", \"value\": \"10.0\" }, { \"correlationId\": \"123\", \"name\": \"param2\", \"type\": \"java.lang.Double\", \"value\": \"15.0\" } ] } } } ]}"curl -X POST "http://localhost:8080/kie-server/services/rest/server/containers/instances/SampleModelContainer" -H "accept: application/json" -H "content-type: application/json" -d "{ \"commands\": [ { \"apply-pmml-model-command\": { \"outIdentifier\": null, \"packageName\": null, \"hasMining\": false, \"requestData\": { \"correlationId\": \"123\", \"modelName\": \"SimpleScorecard\", \"source\": null, \"requestParams\": [ { \"correlationId\": \"123\", \"name\": \"param1\", \"type\": \"java.lang.Double\", \"value\": \"10.0\" }, { \"correlationId\": \"123\", \"name\": \"param2\", \"type\": \"java.lang.Double\", \"value\": \"15.0\" } ] } } } ]}"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Example JSON response
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 5. Additional resources
Appendix A. Versioning information
Documentation last updated on Wednesday, May 8, 2019.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}