API de rappel - - Centre de documentation Alibaba Cloud

L'API de rappel intégrée à PAI-Rec capture les paramètres de requête, les caractéristiques utilisateur et les caractéristiques d'élément au moment précis de chaque demande de recommandation. Utilisez ces journaux pour l'analyse des données, l'entraînement hors ligne de modèles ou l'apprentissage en ligne.

Les méthodes hors ligne, telles que l'association des caractéristiques par fenêtres temporelles, sont peu fiables car la latence entre les composants système est difficile à estimer, ce qui entraîne une fuite de caractéristiques. L'API de rappel résout ce problème en enregistrant les caractéristiques à la source : lorsque la demande de recommandation atteint le service de recommandation, le système consigne l'ID de requête, les caractéristiques utilisateur et les caractéristiques d'élément dans une file de messages (DataHub ou Kafka), puis synchronise les données vers MaxCompute (ODPS).

Callback API flow diagram

Prérequis

Avant de commencer, assurez-vous de disposer des éléments suivants :

Un déploiement PAI-Rec avec le moteur DPI configuré
Un projet DataHub et l'URL de l'endpoint pour votre source de données
(Facultatif) Un modèle EasyRec, si votre flux de rappel utilise des caractéristiques générées par le modèle

Référence de l'API

Endpoint

POST /api/callback

Paramètres de requête

Paramètre	Type	Obligatoire	Description	Contraintes	Exemple
`scene_id`	string	Oui	Le nom de la scène pour laquelle consigner les données	—	`homepage`
`uid`	string	Oui	L'ID d'enregistrement de l'utilisateur	—	`85578510`
`request_id`	string	Oui	Un identifiant unique pour la demande de recommandation	—	`d9cb1c8d***`
`item_list`	json list	Oui	La liste des ID d'éléments recommandés	Chaque élément doit inclure `item_id`	`[{"item_id":"99886867"}, {"item_id":"99888623"}]`
`features`	json string	Non	Les caractéristiques utilisateur au moment de la requête	Chaîne JSON valide	`{"age":25, "city":"beijing"}`
`request_info`	json string	Non	Informations supplémentaires sur la requête	Chaîne JSON valide	`{"recom_id":"12334234"}`

Exemple de requête

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"}}'

Réponse

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

Champ	Type	Description
`code`	integer	Code d'état HTTP. `200` indique un succès.
`msg`	string	Message d'état. `success` indique que le rappel a été enregistré.

Configuration du rappel

La configuration du rappel comporte deux parties : le bloc CallBackConfs qui définit le comportement de journalisation, et le bloc DatahubConfs qui définit l'emplacement d'écriture des données.

CallBackConfs

"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
  }
}

Paramètre	Description	Par défaut	Contraintes
`home_feed` (nom de la scène)	La scène pour laquelle consigner les données	—	Doit correspondre à un nom de scène dans `SceneConfs`
`DataSource.Type`	Le type de file de messages	—	Actuellement, seul `datahub` est pris en charge
`DataSource.Name`	Le nom de la source de données DataHub	—	Doit correspondre à une clé dans `DatahubConfs`
`RankConf`	La configuration du modèle, identique à la configuration du modèle du moteur DPI	—	Omettez ce champ si aucune caractéristique générée par le modèle n'est utilisée
`RawFeatures`	Indique s'il faut enregistrer les caractéristiques brutes des éléments provenant du modèle EasyRec	`false`	Définissez sur `true` pour activer ; vous devez également définir `RawFeaturesRate`
`RawFeaturesRate`	Taux d'échantillonnage pour les caractéristiques brutes	`0`	Entier compris entre `0` et `100`. Ne prend effet que lorsque `RawFeatures` est défini sur `true`.
`ItemSize`	Nombre maximal d'éléments à traiter par rappel	Tous les éléments du flux de recommandation	Les éléments sont tronqués aux premiers `ItemSize` éléments avant l'échantillonnage
`ItemSizeRate`	Taux d'échantillonnage appliqué après la troncature `ItemSize`	—	Entier compris entre `1` et `100`. Si `ItemSize` et `ItemSizeRate` sont tous deux définis, le système tronque d'abord à `ItemSize` éléments, puis échantillonne selon `ItemSizeRate`.
`UseUserFeatures`	Indique s'il faut utiliser les caractéristiques utilisateur du flux de recommandation lorsque `AutoInvokeCallBack` est activé	—	Lorsqu'il est défini sur `true`, aucune récupération séparée des caractéristiques utilisateur dans `FeatureConfs` n'est nécessaire pour le flux de rappel

DatahubConfs

PAI-Rec crée automatiquement le topic DataHub en fonction du nom du topic et du schéma ; aucune création manuelle de topic n'est requise.

"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"}
    ]
  }
}

Remplacez ${ProjectName} par le nom de votre projet DataHub.

Configuration du chargement des caractéristiques

Le chargement des caractéristiques pour le flux de rappel suit la même structure que la configuration standard des caractéristiques. La seule différence réside dans l'alias de la scène : utilisez {scene_name}_callback comme nom de scène dans FeatureConfs. Par exemple, pour la scène home_feed, utilisez home_feed_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"
        }
      }
    ]
  }
}

Format des journaux

Chaque requête de rappel contient un ID utilisateur et une liste d'éléments. Étant donné que les caractéristiques utilisateur peuvent être volumineuses, les caractéristiques utilisateur et celles des éléments sont écrites sous forme d'enregistrements de journal distincts dans le même topic DataHub, distingués par le champ module.

Journal des caractéristiques utilisateur

Champ	Type	Description
`module`	string	Toujours `"user"` — identifie cet enregistrement comme étant celui des caractéristiques utilisateur
`request_id`	string	L'ID de requête issu de la demande de rappel
`scene`	string	Le nom de la scène issu de la demande de rappel
`request_time`	integer	L'horodatage Unix de la requête
`user_id`	string	L'ID utilisateur
`user_features`	string	Les caractéristiques utilisateur sous forme de chaîne JSON
`request_info`	string	Informations supplémentaires sur la requête issues de la demande de rappel

Journal des caractéristiques des éléments

Champ	Type	Description
`module`	string	Toujours `"item"` — identifie cet enregistrement comme étant celui des caractéristiques des éléments
`request_id`	string	L'ID de requête issu de la demande de rappel
`scene`	string	Le nom de la scène issu de la demande de rappel
`request_time`	integer	L'horodatage Unix de la requête
`user_id`	string	L'ID utilisateur
`item_id`	string	L'ID de l'élément
`item_features`	string	Les caractéristiques de l'élément sous forme de chaîne JSON
`raw_features`	string	Caractéristiques brutes renvoyées par le modèle EasyRec
`generate_features`	string	Sortie de la génération de caractéristiques (FG) du modèle EasyRec
`context_features`	string	Caractéristiques contextuelles renvoyées par le modèle EasyRec

Activation du rappel automatique de scène

Par défaut, le rappel est un service distinct que vous appelez manuellement après chaque demande de recommandation. Le moteur DPI prend également en charge l'invocation automatique du rappel : une fois la demande de recommandation terminée, le système appelle automatiquement le flux de rappel.

Pour activer les rappels automatiques, définissez AutoInvokeCallBack sur true dans SceneConfs :

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

Remplacez ${scene_name} par le nom réel de la scène, tel que home_feed.

Paramètre	Description	Par défaut	Contraintes
`AutoInvokeCallBack`	Indique s'il faut appeler automatiquement le flux de rappel après chaque demande de recommandation	—	Définissez sur `true` pour activer
`AutoInvokeCallBackRate`	Pourcentage de demandes de recommandation qui déclenchent un rappel automatique	—	Entier compris entre `1` et `100`. S'il est défini sur `0` ou omis, tout le trafic déclenche un rappel.

Étapes suivantes

Configuration des caractéristiques