Predictions

Retrieve real-time scores prediction for a machine learning use case.

Components of AI Accelerator Predictions API

The components that make up the AI Accelerator real-time scoring API are:

Configuration Resolution
Feature Extractor
Scorer
DB Writer

Configuration Resolution

For each API request, the API resolves the configuration values at run time in the following order:

API request (highest priority)
Admin configurations in setup BPOs. See AI Accelerator.
Use case configuration file setting

Feature Extractor

This component is applicable to only those use cases where it’s necessary to derive or calculate some features during run time. Just to clarify, features are the inputs to an ML model.

As an example, let’s consider an ML use case that predicts the price of a real estate property. To do so, the ML model requires features, such as the property’s square feet area, carpet area, location, number of bedrooms, construction year, and construction age.

Say all these features are available in the property’s record except the construction age feature. In this case, the API invokes Feature Extractor to calculate the construction age in runtime by subtracting the construction year feature from the current year.

Scorer

Scorer accepts features and uses the Einstein Discovery Predict API to interact with the ED platform for scoring the records.

DB Writer

If you configure an ML use case for persistence, DB Writer persists the features, scores, and insights in the specified object and as per the specified field mapping in the AIUsecaseFieldMapping object.

The AI Accelerator Predictions API returns the following output components:

A single prediction score per record, rawdata, recordoverrides, extractedrawdata, or extractedrecordoverrides.
Details on how the score was arrived at through a maximum of three prediction insights, which helps end users understand the impact of various features on the scores.
Prediction improvements to improve the score.

Resource

1/connect/aiaccelerator/predictions

Resource example

1https://yourInstance.salesforce.com/services/data/vXX.X/connect/aiaccelerator/predictions

Available version

55.0

Requires Chatter

HTTP methods

POST

Request body for POST

Properties

Name	Type	Description	Required or Optional	Available Version
`async`	Boolean	Indicates whether the execution mode is async (`true`) or not (`false`).	Optional	55.0
`columnNames`	String[]	Comma-separated list of column names representing the columns that the model analyzes. These are features that are inputs to the model for predicting the scores.	Optional This field is required when type is `rawdata` or `recordOverrides`. Note	55.0
`enableFeaturePersistence`	Boolean	Indicates whether you want to persist the features (`true`) or not (`false`).	Optional This field is required only if raw data or when features are extracted. Note	55.0
`enableInsightPersistence`	Boolean	Indicates whether you want to persist the insights (`true`) or not (`false`). The `enableScorePersistence` field must be enabled to persist insights. Note	Optional	55.0
`enableScorePersistence`	Boolean	Indicates whether you want to persist the prediction scores (`true`) or not (`false`).	Optional	55.0
`enableSuggestionPersistence`	Boolean	Indicates whether you want to persist the suggestions (`true`) or not (`false`). The `enableScorePersistence` field must be enabled to persist suggestions. Note	Optional	55.0
`enrichModelClassification`	Boolean	Indicates whether you want to retrieve the classification model type and the classification threshold (`true`) or not (`false`).	Optional	55.0
`enrichModelFeatures`	Boolean	Indicates whether you want to retrieve the model feature details, including label and data type (`true`) or not (`false`).	Optional	55.0
`enrichPredictionDefinition`	Boolean	Indicates whether you want to retrieve the prediction definition label (`true`) or not (`false`).	Optional	55.0
`featureColumnMap`	Map<String, String>	Represents the map that contains which features need to be persisted and where they must be persisted. The key-value pair must contain: `key`—Feature name `value`—ResponseObjects (configured in the Admin UI setup).FieldName	Optional	55.0
`featureExtractionParameters`	Feature Extraction Parameters Field Map Value[]	Represents the input parameters that are required by the Feature Extractor to extract the features that a model requires to make the prediction. Supports a maximum number of 200 records.	Optional This field is required when the input type is `ExtractedRawData` or `ExtractedRecordOverrides`. Note	55.0
`featureExtractorId`	String	The ID of the feature extractor record from the AIFeatureExtractor object. The specified feature extractor is used to extract the features for the prediction. For information on the custom feature extractor interface implementation, see CustomFeatureExtractor Interface.	Optional	55.0
`historyReferencePoint`	String	Represents a reference point for a comparison between current and previous prediction scores.	Optional	55.0
`inputType`	String	The type of input used to make the prediction. Supports a maximum number of 200 records. Possible values are: Records—All the features for a model are present in the Salesforce database. RawData—All the features for a model are provided in the API request itself. RecordOverrides—The API reads a part of the features for the model from the Salesforce database by using the specified record Id. The remaining features are provided in the API request as raw data. ExtractedRawData—The API computes some or all the features for the model at runtime using the configured Feature Extractor, others can be passed as raw data in the API request. ExtractedRecordOverrides—The API computes some features for the model at run time by using the configured Feature Extractor. For the remaining features, the API refers to the Salesforce database through the specified record ID.	Required	55.0
`insightColumnMap`	Map<String, String>	Represents the map that contains which insight's Name/Value need to be persisted, and to which object they must be persisted. The key-value pair must contain: `key`—INSIGHT1.Name / INSIGHT1.Value (up to maximum of 3 insights Name/Value) `value`—ResponseObjects (configured in the Admin UI setup).FieldName	Optional	55.0
`insightsSettings`	Map<String, Integer>	A map for configuring insight settings. Here are the settings that contribute to the prediction score: `maxInsights`—Maximum number of insights that you want the machine learning model to generate. `maxSuggestionCount`—Maximum number of suggestions that you want the machine learning model to generate. `suggestionImpactMinimumPct`—Minimum eligible percentage for improving the prediction score based on suggestions. For more information, see Define Maximum Suggestions and Insights in the AI Accelerator Admin Guide.	Optional	55.0
`predictionDefinition`	String	The developer name or API name from the DiscoveryGoal object.	Required	55.0
`rawData`	Raw Data Input Wrap[]	A two-dimensional array of row values in which each row is a comma-separated list of values for features provided in `columnNames`. Supports a maximum number of 200 records.	Optional This field is required when the input type is `RawData` or `RecordOverrides`. Note	55.0
`records`	String[]	The IDs of the Salesforce record that is used as input features for model to make the prediction.	Optional This field is required when the input type is `Records`, `RecordOverrides` or `ExtractedRecordOverrides`. Note	55.0
`scorePersistenceColumn`	String	The name and value of the score that needs to be persisted, and to which object it must be persisted. The valid format is ResponseObject.FieldName.	Optional This field is required when `enableScorePersistence` is set to true. Note	55.0
`suggestionColumnMap`	Map<String, String>	Represents the map that contains which suggestions Name/Value need to be persisted, and to which object they must be persisted. The key-value pair must contain: `key`—SUGGESTION1.Name / SUGGESTION1.Value (maximum of 5 suggestions Name/Value) `value`—ResponseObjects (configured in the Admin UI setup).FieldName	Optional	55.0
`usecaseDefinition`	String	The ID of the usecase definition record from the AIUsecaseDefinition object.	Required	55.0

JSON example

An example of inputType as Records..

1{
2  "usecaseDefinition": "0sIxx00000006Gj",
3  "predictionDefinition": "1ORxx0000004IpY",
4  "inputType": "Records",
5  "records": {
6    "wrappedList": [
7      "a00x0000000CHa0AAG"
8    ]
9  },
10  "insightsSettings": {
11    "insightsSettings": {
12      "maxSuggestionCount": 1,
13      "maxInsights": 1,
14      "suggestionImpactMinimumPct": 0
15    }
16  },
17  "insightColumnMap": {
18    "columnMap": {
19      "INSIGHT1.Name": "Demo__c.InsightName1Override__c",
20      "INSIGHT1.Value": "Demo__c.InsightValue1__c",
21      "INSIGHT1.Impact": "Demo__c.InsightImpact1__c"
22    }
23  },
24  "suggestionColumnMap": {
25    "columnMap": {
26      "SUGGESTION1.Name": "Demo__c.RecommendationName1__c",
27      "SUGGESTION1.Value": "Demo__c.RecommendationValue1__c",
28      "SUGGESTION1.Impact": "Demo__c.RecommendationImpact1Override__c"
29    }
30  },
31  "enableScorePersistence": true,
32  "async": false
33}

An example of inputType as RawData.

1{
2  "usecaseDefinition": "0sIxx00000006Gj",
3  "predictionDefinition": "1ORxx0000004IpY",
4  "inputType": "RawData",
5  "columnNames": {
6    "wrappedList": [
7      "corp_year_week__c",
8      "sap_source_id__c",
9      "sap_ppg_id__c",
10      "sales_units__c"
11    ]
12  },
13  "rawData": {
14    "rawData": [
15      {
16        "rawDataInputWrap": {
17          "rawDataInput": [
18            "202016",
19            "0YQx0000000CaS8GAK",
20            "01tx00000006j2DAAQ",
21            "20"
22          ]
23        }
24      },
25      {
26        "rawDataInputWrap": {
27          "rawDataInput": [
28            "202016",
29            "0YQx0000000CaS8GAK",
30            "01tx00000006j2DAAQ",
31            "20000"
32          ]
33        }
34      }
35    ]
36  },
37  "insightsSettings": {
38    "insightsSettings": {
39      "maxSuggestionCount": 1,
40      "maxInsights": 1,
41      "suggestionImpactMinimumPct": 0
42    }
43  },
44  "featureColumnMap": {
45    "columnMap": {
46      "corp_year_week__c": "Demo__c.YearWeekFeature__c",
47      "sap_source_id__c": "Demo__c.StoreIdFeature__c",
48      "sap_ppg_id__c": "Demo__c.ProductIdFeature__c",
49      "sales_units__c": "Demo__c.SalesUnitsFeatureOverride__c"
50    }
51  },
52  "enableSuggestionPersistence": false,
53  "async": false
54}

An example of inputType as RecordOverrides.

1{
2  "usecaseDefinition": "0sIxx00000006Gj",
3  "predictionDefinition": "1ORxx0000004IpY",
4  "inputType": "RawData",
5  "columnNames": {
6    "wrappedList": [
7      "corp_year_week__c",
8      "sap_source_id__c",
9      "sap_ppg_id__c",
10      "sales_units__c"
11    ]
12  },
13  "rawData": {
14    "rawData": [
15      {
16        "rawDataInputWrap": {
17          "rawDataInput": [
18            "202016",
19            "0YQx0000000CaS8GAK",
20            "01tx00000006j2DAAQ",
21            "20"
22          ]
23        }
24      },
25      {
26        "rawDataInputWrap": {
27          "rawDataInput": [
28            "202016",
29            "0YQx0000000CaS8GAK",
30            "01tx00000006j2DAAQ",
31            "20000"
32          ]
33        }
34      }
35    ]
36  },
37  "insightsSettings": {
38    "insightsSettings": {
39      "maxSuggestionCount": 1,
40      "maxInsights": 1,
41      "suggestionImpactMinimumPct": 0
42    }
43  },
44  "featureColumnMap": {
45    "columnMap": {
46      "corp_year_week__c": "Demo__c.YearWeekFeature__c",
47      "sap_source_id__c": "Demo__c.StoreIdFeature__c",
48      "sap_ppg_id__c": "Demo__c.ProductIdFeature__c",
49      "sales_units__c": "Demo__c.SalesUnitsFeatureOverride__c"
50    }
51  },
52  "enableSuggestionPersistence": false,
53  "async": false
54}

An example of inputType as ExtractedRawData.

1{
2  "usecaseDefinition": "0sIxx00000006Gj",
3  "predictionDefinition": "1ORxx0000004IpY",
4  "inputType": "Records",
5  "featureExtractionParameters": {
6    "featureExtractionParameters": [
7      {
8        "featureExtractionParametersMapValue": {
9          "recordId": "01tx00000006j2DAAQ1",
10          "rawData": {
11            "corp_year_week__c": "202016"
12          }
13        }
14      }
15    ]
16  },
17  "insightsSettings": {
18    "insightsSettings": {
19      "maxSuggestionCount": 1,
20      "maxInsights": 1,
21      "suggestionImpactMinimumPct": 0
22    }
23  },
24  "enableScorePersistence": true,
25  "async": false
26}

An example of inputType as ExtractedRecordOverrides.

1{
2  "usecaseDefinition": "0sIxx00000006Gj",
3  "predictionDefinition": "1ORxx0000004IpY",
4  "inputType": "Records",
5  "records": {
6    "wrappedList": [
7      "a00x0000000CHa0AAG"
8    ]
9  },
10  "featureExtractionParameters": {
11    "featureExtractionParameters": [
12      {
13        "featureExtractionParametersMapValue": {
14          "recordId": "01tx00000006j2DAAQ1"
15        }
16      }
17    ]
18  },
19  "insightsSettings": {
20    "insightsSettings": {
21      "maxSuggestionCount": 1,
22      "maxInsights": 1,
23      "suggestionImpactMinimumPct": 0
24    }
25  },
26  "insightColumnMap": {
27    "columnMap": {
28      "INSIGHT1.Name": "Demo__c.InsightName1Override__c",
29      "INSIGHT1.Value": "Demo__c.InsightValue1__c",
30      "INSIGHT1.Impact": "Demo__c.InsightImpact1__c"
31    }
32  },
33  "suggestionColumnMap": {
34    "columnMap": {
35      "SUGGESTION1.Name": "Demo__c.RecommendationName1__c",
36      "SUGGESTION1.Value": "Demo__c.RecommendationValue1__c",
37      "SUGGESTION1.Impact": "Demo__c.RecommendationImpact1Override__c"
38    }
39  },
40  "enableScorePersistence": true,
41  "async": false
42}

Response body for POST

Prediction Output

Industries Common Resources Developer Guide

Predictions

Components of AI Accelerator Predictions API