Package com.codedstream.otterstream.pmml

Class PmmlInferenceEngine

  • All Implemented Interfaces:
    InferenceEngine<org.jpmml.evaluator.Evaluator>
    public class PmmlInferenceEngine
extends LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
    PMML (Predictive Model Markup Language) implementation of LocalInferenceEngine.

    This engine provides inference capabilities for PMML models using the JPMML (Java PMML) library. PMML is an XML-based standard for representing predictive models, supporting various model types including regression, decision trees, neural networks, and ensemble models.

    Supported PMML Features:

    • Model Types: Regression, decision trees, neural networks, ensemble models
    • Data Preparation: Automatic type conversion and value preparation
    • Output Types: Target fields, output fields, computed results
    • Batch Processing: Sequential batch inference (non-optimized)

    Model Loading:

    
 ModelConfig config = ModelConfig.builder()
     .modelPath("model.pmml")
     .modelId("credit-scoring")
     .build();

 PmmlInferenceEngine engine = new PmmlInferenceEngine();
 engine.initialize(config);

    Inference Example:

    
 Map<String, Object> inputs = new HashMap<>();
 inputs.put("age", 35);
 inputs.put("income", 75000.0);
 inputs.put("credit_score", 720);
 inputs.put("loan_amount", 25000.0);

 InferenceResult result = engine.infer(inputs);
 double riskScore = (double) result.getOutput("risk_score");
 String prediction = (String) result.getOutput("prediction");

    Input Field Preparation:

    The engine automatically prepares input values using PMML field definitions:

    • Type conversion according to PMML field data types
    • Missing value handling
    • Outlier treatment
    • Discretization and normalization (if defined in PMML)

    Output Structure:

    Results include both target fields (primary predictions) and output fields (derived metrics). Computable results are automatically resolved:

    • Target Fields: Primary model predictions
    • Output Fields: Derived metrics, probabilities, scores
    • Computed Values: Automatically resolved from Computable objects

    Batch Inference:

    Batch inference is implemented as sequential single inferences, as PMML/JMML doesn't natively support batch processing. Outputs are aggregated with index suffixes (e.g., "risk_score_0", "risk_score_1").

    Capabilities:

    FeatureSupportedNotes
    Batch InferenceNoSequential processing only
    Native BatchingNoNo native batch optimization
    Max Batch Size1Single inference at a time
    GPU SupportYesDepends on underlying hardware

    Dependencies:

     Requires JPMML (Java PMML) library:
 - org.jpmml:pmml-evaluator (runtime)
 - org.jpmml:pmml-model (runtime)

    Thread Safety:

    JPMML Evaluator instances are not thread-safe. For concurrent inference, create separate engine instances or synchronize access to infer(java.util.Map<java.lang.String, java.lang.Object>) and inferBatch(java.util.Map<java.lang.String, java.lang.Object>[]) methods.

    Performance Considerations:

    • PMML inference is generally slower than native formats (ONNX, TensorFlow)
    • Batch processing is sequential - consider parallel execution for throughput
    • Complex data transformations in PMML can add overhead
    Since:
    1.0.0
    Author:
    Nestor Martourez, Sr Software and Data Streaming Engineer @ CodedStreams
    See Also:
    LocalInferenceEngine, Evaluator, ModelEvaluatorFactory

    • Constructor Detail

      • PmmlInferenceEngine

        public PmmlInferenceEngine()

    • Method Detail

      • initialize

        public void initialize​(ModelConfig config)
                throws InferenceException
        Initializes the PMML inference engine by loading and parsing a PMML model file.

        The initialization process:

        1. Loads PMML file from the configured path
        2. Parses XML into PMML object
        3. Creates Evaluator instance using ModelEvaluatorFactory
        4. Verifies model integrity

        Dependency Note:

        Requires pmml-evaluator library. Ensure the following dependency: 

        
 <dependency>
     <groupId>org.jpmml</groupId>
     <artifactId>pmml-evaluator</artifactId>
     <version>1.6.3</version>
 </dependency>
        Specified by:
        initialize in interface InferenceEngine<org.jpmml.evaluator.Evaluator>
        Overrides:
        initialize in class LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
        Parameters:
        config - model configuration containing the PMML file path
        Throws:
        InferenceException - if model loading or initialization fails
        IllegalStateException - if required JPMML libraries are missing

      • infer

        public InferenceResult infer​(Map<String,​Object> inputs)
                      throws InferenceException
        Performs single inference on the provided inputs using the PMML model.

        The inference process:

        1. Prepares input values using PMML field definitions
        2. Executes model evaluation
        3. Extracts target and output fields
        4. Resolves Computable results if present
        5. Returns structured inference results

        Input Preparation:

        Input values are automatically prepared using InputField.prepare(Object), which handles:

        • Data type conversion
        • Missing value substitution
        • Value transformations defined in PMML
        • Validation against field constraints

        Output Extraction:

        Extracts both target fields (primary predictions) and output fields (additional metrics). Computable results are automatically resolved to their final values.

        Specified by:
        infer in interface InferenceEngine<org.jpmml.evaluator.Evaluator>
        Specified by:
        infer in class LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
        Parameters:
        inputs - map of input field names to values
        Returns:
        inference result containing predictions and timing information
        Throws:
        InferenceException - if inference fails or inputs are invalid

      • inferBatch

        public InferenceResult inferBatch​(Map<String,​Object>[] batchInputs)
                           throws InferenceException
        Performs batch inference by sequentially processing multiple input sets.

        Note: PMML/JMML doesn't support native batch processing, so this method processes inputs sequentially. Outputs are aggregated with index suffixes to maintain per-sample traceability.

        Output Format:

        Outputs are aggregated into a single map with indexed keys: 

         {
   "risk_score_0": 0.75,
   "prediction_0": "APPROVED",
   "risk_score_1": 0.92,
   "prediction_1": "REJECTED"
 }

        Performance Warning:

        This implementation doesn't provide batch optimization. For high-throughput scenarios, consider:

        • Parallel execution across multiple engine instances
        • Using a different model format with native batch support
        • Implementing custom batching logic
        Specified by:
        inferBatch in interface InferenceEngine<org.jpmml.evaluator.Evaluator>
        Specified by:
        inferBatch in class LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
        Parameters:
        batchInputs - array of input maps, each representing one sample
        Returns:
        aggregated inference result containing all batch outputs
        Throws:
        InferenceException - if any inference in the batch fails

      • getCapabilities

        public InferenceEngine.EngineCapabilities getCapabilities()
        Gets the engine's capabilities for PMML inference.

        Note: PMML engines have limited capabilities compared to other formats like ONNX:

        • Batch Inference: Not supported natively
        • Native Batching: No batch optimization
        • Max Batch Size: Limited to 1 (sequential processing)
        • GPU Support: Available but depends on hardware
        Specified by:
        getCapabilities in interface InferenceEngine<org.jpmml.evaluator.Evaluator>
        Specified by:
        getCapabilities in class LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
        Returns:
        engine capabilities indicating limited batch support

      • close

        public void close()
           throws InferenceException
        Closes the PMML inference engine and releases resources.

        Note: JPMML Evaluator doesn't implement AutoCloseable, so resources are released by nullifying references and relying on garbage collection. No native resources need explicit cleanup.

        Specified by:
        close in interface InferenceEngine<org.jpmml.evaluator.Evaluator>
        Overrides:
        close in class LocalInferenceEngine<org.jpmml.evaluator.Evaluator>
        Throws:
        InferenceException - if cleanup fails (unlikely for PMML)

      • getMetadata

        public ModelMetadata getMetadata()
        Gets metadata about the loaded PMML model.

        TODO: Implement PMML metadata extraction. Potential metadata includes:

        • Model type (regression, decision tree, neural network, etc.)
        • Input field definitions and data types
        • Output/target field information
        • Model version and creation timestamp
        • Training data characteristics
        Returns:
        model metadata (currently returns null, override for implementation)