Callback API

PAI-Rec includes a built-in callback API that logs real-time features, such as request parameters and real-time user and item features, at the time of a recommendation request. You can use these logs for data analytics, offline model training, or online learning.

Background

Real-time features are a critical part of recommendation systems. These include real-time statistical features and real-time sequence features, especially user sequence features. Adding real-time features usually improves the performance of a recommendation system. However, real-time features require high accuracy. Using offline methods to infer real-time features, such as associating data by time windows, can lead to problems. It is difficult to estimate the latency between system links. This can cause inaccurate features and feature leakage. Adding these inaccurate features to retrieval and sorting models is often counterproductive.

To ensure accuracy, for a given training sample S_i corresponding to a recommendation request R_i, the real-time features must be the user and item features captured at the exact moment of the request. Therefore, the best time to record real-time features is when the recommendation request reaches the recommendation service. While the algorithm calculates the recommendation results, you can log the request ID, real-time user features, and real-time item features to a message queue, such as DataHub or Kafka. Then, sync the logs to MaxCompute (ODPS).

API definition

API endpoint

/api/callback

Request parameters

Request example

curl 'http://host/api/callback' -d '{"uid":"84603208","request_id":"d9cb1c8d-4d3f-491b-9ea3-380481dabde3","scene_id":"homepage","features":{"age":25, "city":"beijing"}, "item_list":[{"item_id":"113939841"},{"item_id":"113764910"}],"request_info":{"recom_id":"1111111"}}'

Response data

{
 "code":200,
 "msg":"success",
}

Callback configuration

The callback flow has two main parts.

• Load user and item features.

• In many cases, if you use an EasyRec model, the item features are included with the model. You must request the EasyRec model to retrieve the Feature Generation (FG) features that the model generates.

You can write the feature data to a message queue, such as DataHub.

"CallBackConfs": {
  "home_feed": {
    "DataSource": {
      "Name": "pairec_callback_dh",
      "Type": "datahub"
    },
    "RankConf": {
      "RankAlgoList": [
        "ali_rnk_v2_woid_callback_public_v2"
      ],
      "ContextFeatures": [
        "none"
      ],
      "Processor": "EasyRec"
    },
    "RawFeatures": false,
    "RawFeaturesRate": 0,
    "ItemSize": 100,
    "ItemSizeRate": 10,
    "UseUserFeatures": true
  }
  
}

• home_feed is the scene name. This parameter specifies the scene for which data is logged.

• DataSource

  • Type: The type of message queue. Currently, only DataHub is supported.

  • pairec_callback_dh: The name of the DataHub data source. You can find this name in DatahubConfs.

• RankConf: The model configuration. This is the same as the model configuration for the DPI engine service. If there are no features generated by a model, you do not need to configure this.

• RawFeatures: Specifies whether to record the raw features of items. Set this parameter to true to record them. If set to true, you must also set RawFeaturesRate to a sampling ratio between 0 and 100.

• ItemSize: Controls the number of items for the callback. If the recommendation API returns too many items, use this parameter to limit the number. The callback processes only the first ItemSize items. If you do not set this parameter, the number of items delivered by the recommendation flow is used by default.

• ItemSizeRate: Samples a number of items based on a ratio. The value can be from 1 to 100. If you set both ItemSize and ItemSizeRate, the system first truncates the list to ItemSize items and then samples from the truncated list based on the ItemSizeRate.

• UseUserFeatures: When using AutoInvokeCallBack, specifies whether to use the user features obtained from the recommendation flow. If you set this parameter, you do not need to configure user feature retrieval in FeatureConfs for the callback flow.

Data source configuration

  "DatahubConfs": {
    "pairec_callback_dh": {
      "Endpoint": "http://dh-cn-hangzhou-int-vpc.aliyuncs.com",
      "ProjectName": "${ProjectName}",
      "TopicName": "pairec_callback_log",
      "Schemas": [
        {
          "Field": "request_id",
          "Type": "string"
        },
        {
          "Field": "module",
          "Type": "string"
        },
        {
          "Field": "scene",
          "Type": "string"
        },
        {
          "Field": "request_time",
          "Type": "integer"
        },
        {
          "Field": "user_features",
          "Type": "string"
        },
        {
          "Field": "item_features",
          "Type": "string"
        },
        {
          "Field": "request_info",
          "Type": "string"
        },
        {
          "Field": "user_id",
          "Type": "string"
        },
        {
          "Field": "item_id",
          "Type": "string"
        },
        {
          "Field": "raw_features",
          "Type": "string"
        },
        {
          "Field": "generate_features",
          "Type": "string"
        },
        {
          "Field": "context_features",
          "Type": "string"
        }
      ]
    }
    }

In the configuration above, you do not need to create the topic manually. PAI-Rec can automatically create the topic based on the topic name and schema.

Feature loading configuration

For more information, see Feature configuration. The difference is that you must use `scene_name + _callback` as the scene alias for feature loading. For example, the scene name `home_feed_callback` is created by combining `home_feed` and `_callback`.

The scene name home_feed_callback is created by combining home_feed and _callback.

"FeatureConfs": {
  "home_feed_callback": {
    "AsynLoadFeature": true,
    "FeatureLoadConfs": [
      {
        "FeatureDaoConf": {
          "AdapterType": "hologres",
          "HologresName": "pairec-holo",
          "FeatureKey": "user:uid",
          "UserFeatureKeyName": "client_str",
          "HologresTableName": "dwd_ali_user_all_feature_v2_holo",
          "UserSelectFields": "*",
          "FeatureStore": "user"
        },
        "Features": [
          {
            "FeatureType": "new_feature",
            "FeatureName": "day_h",
            "Normalizer": "hour_in_day",
            "FeatureStore": "user"
          },
          {
            "FeatureType": "new_feature",
            "FeatureName": "week_day",
            "Normalizer": "weekday",
            "FeatureStore": "user"
          },
          {
            "FeatureType": "new_feature",
            "FeatureName": "rand_int_v",
            "Normalizer": "random",
            "FeatureStore": "user"
          }
        ]
      },
      {
        "FeatureDaoConf": {
          "AdapterType": "hologres",
          "HologresName": "pairec-holo",
          "FeatureKey": "user:uid",
          "UserFeatureKeyName": "client_str",
          "HologresTableName": "dwd_ali_user_table_v3_expo_static_feature_v2_holo",
          "UserSelectFields": "*",
          "FeatureStore": "user"
        }
      }
    ]
  }
}

Log format

A callback request contains one user ID and a list of items. Because user features can be large, user and item features are logged separately to save space.

The user feature log contains the following data:

• request_id: The request ID from the callback request.

• scene: The scene name from the callback request.

• request_time: The time of the request.

• user_features: The user features, formatted as a JSON string.

• user_id: The user ID.

• request_info: Additional request information from the callback request.

• module: A static field with the value `user`, which indicates that this is a user feature log.

The item feature log contains the following data:

• request_id: The request ID from the callback request.

• scene: The scene name from the callback request.

• request_time: The time of the request.

• module: A static field with the value `item`, which indicates that this is an item feature log.

• item_id: The item ID.

• user_id: The user ID.

• raw_features: The raw features returned by the EasyRec model.

• generate_features: The feature information after FG, returned by the EasyRec model.

• context_features: The context features returned by the EasyRec model.

• item_features: The item features, formatted as a JSON string.

Automatic scene callback

Typically, the callback is deployed as a separate service, and you must assemble the data to call it. However, the PAI-Rec DPI engine also supports automatic calls to the callback flow. To enable this feature, configure the callback settings in the configuration file and then enable the `AutoInvokeCallBack` flag in `SceneConfs`. After a recommendation request is complete, the system automatically calls the callback API.

If `AutoInvokeCallBack` is set to `true`, you can also set `AutoInvokeCallBackRate` to control the percentage of requests that trigger a callback. The value can be from 1 to 100. If you do not set `AutoInvokeCallBackRate`, or if you set it to 0, all traffic triggers a callback.

"SceneConfs": {
  "${scene_name}": {
    "default": {
      "RecallNames": [
        "collaborative_filter"
      ],
      "AutoInvokeCallBack": true,
      "AutoInvokeCallBackRate": 100
    }
  }
}

If you found this helpful, click Like.