6 Deploying and Configuring the Prediction Service

Learn how to deploy and configure the prediction service for Oracle Monetization Suite in both Oracle Cloud Infrastructure (OCI) and non-OCI environments.

Topics in this document:

Deploying the Prediction Service

You can connect to a model on Oracle Cloud Infrastructure or in a non-OCI environment and deploy the prediction service independently, depending on your requirements. For this, you need to perform the installation steps described in "Overview of Installation Tasks", and then install the prediction service Helm charts by following the instructions below.

To install and deploy the prediction service using Helm charts:

  1. Download the prediction service Helm charts from the deployment package.

    For more information, see "Downloading Packages for the Cloud Native Helm Charts and Docker Files" and "Setting Up Prerequisite Software and Tools".

  2. Create a new key and generate an SSL certificate to run the data service over HTTPS.

  3. (Optional) Install the Ingress NGINX controller:

    • Create a Kubernetes TLS Secret using the certificate you generated and your private key:

      kubectl create secret tls secretName --cert=certificateName.crt --key=privateKeyName.key

    • Add the ingress-nginx Helm repository:

      helm repo add ingress-nginx

    • Update the Helm repository:

      helm repo update

    • Install the Ingress Controller:

      helm install ingress-nginx ingress-nginx/ingress-nginx --namespace nginxNamespace --create-namespace

    • Attach the service to the NGINX Controller:

      helm install ingress-nginx ingress-nginx/ingress-nginx --namespace nginxNamespace \ 
  --set controller.service.enableHttp=false \
  --set controller.service.enableHttps=true \ 
  --set controller.service.ports.https=443 \ 
  --set controller.service.nodePorts.https=31231 nodePort \ 
  --set controller.config.ssl-redirect=true \ 
  --set controller.config.force-ssl-redirect=true \ 
  --set controller.ingressClassResource.name=ingressClassName \ 
  --set controller.ingressClass=ingressClassName \ 
  --create-namespace

  4. Update the values.yaml file for your deployment:

    1. Set mount paths:

      • mountPath.modelFilesHostPath: Specify the path where model files are stored. For a single worker node, specify a path on that node. For multiple worker nodes, specify the NFS or OCI File Storage export path. Set this value even if the models are stored in OCI.

      • mountPath.logFilesHostPath: Specify the path where log files are stored. For multiple worker nodes, specify the NFS or OCI File Storage export path. If this value is not set, log files are stored in the directory specified by mountPath.modelFilesHostPath.

      • Set folder permissions:

        groupadd -g 10001 oracle
useradd -mr -u 10001 -g oracle oracle
chown 10001:10001 -R mountPath

    2. Set storage configuration:

      • modelFilesStorage.storageType: Set to hostPath for files on a single worker node, nfs for an NFS export shared across worker nodes, or ociFss for an OCI File Storage export shared across worker nodes. The default is nfs.

      • modelFilesStorage.nfs.server: For NFS storage, specify the DNS name or IP address of the NFS server. The server must export the path specified in mountPath.modelFilesHostPath and be reachable from the worker nodes.

      • modelFilesStorage.nfs.existingClaim: When upgrading a deployment that uses an existing model-files PVC, specify its current claim name.

      • logFilesStorage.existingClaim: When upgrading a deployment that uses an existing log-files PVC, specify its current claim name.

      • modelFilesStorage.ociFss.fileSystemOcid: For OCI File Storage, specify the OCID of the existing file system.

      • modelFilesStorage.ociFss.mountTargetIp: For OCI File Storage, specify the mount target IP address.

    3. If you are not using NGINX Ingress, configure HTTPS:

      • https.enabled: Set to true.

      • https.source: Set to hostPath when Kubernetes Secrets are used for certificate ingestion, or to chartFiles to read the certificate and key from chart files.

      • https.orchestratorServicePort: Specify the port on which the service is exposed.

      • https.path: If https.source is hostPath, specify the host system path containing the certificate and key.

      • https.certFile and https.keyFile: If https.source is hostPath, specify the certificate and key file names in that path.

      • https.certPath and https.keyPath: If https.source is chartFiles, specify the certificate and key files in the helm/predict-service/files/certs/ directory.

    4. Add imageRepository and image tags for predictionOrchestrator.image and predictionPredictor.image.

    5. Under predictionPredictor.configurableFiles, specify the following values.

      • modelPath: Specify the path for the base folder where models are stored. Supported: PVC, OCI bucket (must include oci://), or Data Science URI (must include https://).

      • modelNames: Specify the file path for the list of models to be loaded when the service starts. Update and restart the service if new models are added.

        • For the PVC path, follow the {Stage}@{Model_Name} format. The files with '@' are stored in MLFlow. The remaining files are required supporting files.

        • For the models in OCI object storage, follow the {Name}@{OCI_Path} format. For KNN or Cosine models, also include the required mapper file paths from Object Storage.

        • For OCI Data Science model deployments, follow the {model_name}|{algorithm_name}@{Predict_URI} format. The model_name must match the name used during training. For example, if the trained models are named recommend_knn and recommend_dnn, entries can follow this pattern:

          ["recommend_knn|knn@{Predict_URI}", "recommend_dnn|dnn@{Predict_URI}"]

        • For an XGBoost model stored in OCI Object Storage, include its metadata file in modelNames.

      • preprocessScript: Specify the path to the preprocessing script used for prediction. Place it in helm/prediction/files/scripts/.

      • logConfigFile: Specify the path to the logging configuration file if you need to change the log level or format. Place it in helm/prediction/files/config/.

      • mcpPluginManifest: Specify the manifest for additional MCP server tools. Place it in helm/prediction/files/plugin/, along with the custom_tools.py script.

      Note:

      Configurable sample files are available for each of the files mentioned above in the artifacts provided with the package: oci_config (for ociConfigFile), sample_predict_preprocess.py (for preprocessScript), logging_config.py (for logConfigFile), example-tools.json (for mcpPluginManifest), and sample_echo_context.py (for the custom_tools.py script). You can configure these files as per your requirements.

    6. If your deployment uses OCI services, configure OCI access:

      • ociConfig.enabled: Set to true if the prediction service uses OCI Data Flow, Data Science, or Object Storage.

      • ociConfig.configPath and ociConfig.privateKeyPath: Specify the relative paths of the OCI configuration file and private key, such as paths under files/secrets/oci/.

    7. If you are using NGINX, set the NGINX Ingress values:

      • host: Set to the host name where the service is deployed.

      • tlsSecretName: Set to the name of the Kubernetes TLS secret created in step 3.

      • ingressClassName: Set to your ingress class name.

    8. Set identityURI, issuer, and audience to your IDCS configuration. Do one of the following:

      • To use IDCS, set predictionOrchestrator.idcs.enabled to true.

      • To disable IDCS, set predictionOrchestrator.idcs.enabled to false.

    9. Configure the MCP server, if required:

      • predictionOrchestrator.mcp.enabled: Set to true to start the MCP server.

      • predictionOrchestrator.mcp.endpointPath: Set to the required MCP endpoint pattern.

  5. Install the Helm charts:

    helm upgrade --install predict-services helm/prediction/ --namespace=predict-service

Configuring and Using the Prediction Service

You can use and configure the prediction service using its REST API. The prediction service accepts API calls from other systems for inference and recommendation.

For the prediction service, you use the following REST service:

  • Get Predictions (/utility/predict)

    Use this API to generate predictions or recommendations for specific input data after models are trained and deployed.

The prediction service also provides a Model Context Protocol (MCP) endpoint at /monetization/nbo/v1/mcp. This endpoint is configurable. MCP clients can use this endpoint to run predictions, validate prediction requests, and list supported prediction algorithms. Send MCP requests to this endpoint using HTTP POST and the JSON-RPC 2.0 format.

Note:

Interactive REST API documentation is available through the Swagger UI at the /openapi/ui endpoint.

Configuring the MCP Interface

The prediction service supports a Model Context Protocol (MCP) interface for AI agents and MCP clients. The MCP interface enables AI agents and MCP clients to request predictions from the prediction service by using a standard tool-based interface.

Use the MCP interface when you want an AI agent to request predictions without directly accessing the prediction service implementation, model artifacts, or underlying data sources. The MCP interface provides a controlled integration point for validating requests, routing them to the prediction service, and returning structured prediction results.

To configure the MCP interface:

  1. In the prediction service helm chart, specify the model path and the list of approved model artifacts to load when the prediction service starts.

  2. Do the following to configure the settings for MCP:

    • Enable the MCP server.

      Set predictionOrchestrator.mcp.enabled to true in the Helm values file.

    • Specify the public MCP endpoint path.

      Set the required public endpoint path for the MCP server. For example, set predictionOrchestrator.mcp.endpointPath to the required path in the Helm values file. Ensure that the path does not conflict with existing Prediction Service REST API paths.

    • Specify the prediction preprocessing script.

      Add the prediction preprocessing script to the Prediction Service artifacts directory. Set the script path in predictionPredictor.configurableFiles.preprocessScript in the Helm values file.

    • Specify the logging configuration.

      Add the logging configuration file to the Prediction Service artifacts directory. Set the configuration-file path in predictionPredictor.configurableFiles.logConfigFile in the Helm values file.

    • (Optional) Configure an MCP plugin manifest and custom tool implementation.

      Add the MCP plugin manifest and custom tool implementation files to the Prediction Service artifacts directory. Set the plugin manifest path in predictionPredictor.configurableFiles.mcpPluginManifest in the Helm values file.

    • Configure ingress, TLS, authentication, and service-routing settings.

      Configure the ingress host, TLS secret, and ingress class in the Helm values file. Configure the required authentication settings, such as IDCS settings, and route requests from the MCP endpoint to the Prediction Service orchestrator.

  3. Deploy or restart the prediction service after making the updates.

    The prediction service loads the configured model artifacts when it starts.

  4. Verify that the public MCP endpoint is available.

    The Helidon orchestrator exposes the public MCP interface.

  5. Verify that external clients use the public MCP endpoint.

    The internal Python prediction runtime can provide internal MCP capabilities. External clients must not access the internal Python MCP endpoint directly.

  6. Use the configured health checks, logs, metrics, and tracing information to monitor service availability, request processing, and errors.

Implementing Siebel Next Best Offer Recommendations

After you configure the MCP interface, you can use it to request predictions or recommendations from an AI Agent or other MCP client. In this case, you can use it to request next best offer recommendations from a Siebel AI Agent.

Before sending a request, ensure that the prediction service is running, has loaded the approved multi-head model, and can access the required cached customer data.

To request an offer recommendation:

  1. Send an MCP request from the AI Agent to the public MCP endpoint.

  2. Specify the supported customer identifier in the request.

  3. The MCP interface validates the request and sends it to the prediction service.

  4. The prediction service retrieves the required customer data, runs the configured model, and returns the recommendation results to the MCP interface.

  5. Verify that the MCP response contains the expected recommendation outputs.

  6. Review the configured logs, metrics, and tracing information to monitor the request and troubleshoot errors.

Predicting Time-Series Anomalies

Prediction services can help you identify any anomalies in the regular pattern or behavior. You can use an anomaly detection model to classify current operational metrics as normal or anomalous. The supplied sample use case uses an XGBoost model.

Before you request an anomaly detection prediction, ensure that the prediction service is configured with the trained model, model metadata, and Prometheus connection details.

To request an anomaly detection prediction:

  1. In the prediction request, specify the input fields as required.

    The sample implementation uses the start time, end time, and time step to specify the period and interval for retrieving metrics. You can customize the JSON input fields to meet your use case requirements.

  2. Submit the prediction request through the configured prediction service or MCP interface.

    The prediction service retrieves the required metrics from Prometheus and prepares the input data by using the feature definitions in the model metadata.

  3. Review the classification returned for the latest timestamp in the requested time window.

    The supplied sample use case returns 0 for normal metrics and 1 for anomalous metrics.

You can interpret the returned value according to the labels defined for the deployed model. If the model uses additional labels, use the label definitions configured for that model to identify the anomaly type. Verify that all required metrics are available in Prometheus and that they match the feature definitions in the model metadata.

Note:

If a required metric is unavailable or its feature definition differs from the training data, the prediction service might be unable to prepare valid input for the model.

You can also submit an anomaly detection prediction request through the configured MCP interface. For information about configuring the MCP interface, see "Configuring the MCP Interface".