FeatureStore Java SDK - Platform For AI - Centre de documentation Alibaba Cloud

Utilisez le SDK Java FeatureStore pour lire les données de caractéristiques en ligne depuis votre projet PAI FeatureStore au moment de l'inférence. Le SDK prend en charge trois types de caractéristiques :

Type de caractéristique	Méthode de récupération	Cas d'utilisation typique
Caractéristique hors ligne	Vue de caractéristique (`FeatureView`)	Attributs utilisateur ou élément synchronisés par lots
Caractéristique en temps réel	Vue de caractéristique (`FeatureView`)	Signaux mis à jour en direct écrits directement dans le magasin en ligne
Caractéristique séquentielle	Vue de caractéristique séquentielle (`SequenceFeatureView`)	Historique d'événements ordonnés (clics, lectures, achats)

Pour récupérer des caractéristiques groupées par modèle, utilisez Model.getOnlineFeatures() ou Model.getOnlineFeaturesWithEntity() au lieu d'interroger chaque vue de caractéristique individuellement.

Prérequis

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

Un projet FeatureStore avec au moins une entité de caractéristique, une vue de caractéristique et une caractéristique de modèle configurées et synchronisées. Consultez la rubrique Configurer un projet FeatureStore.
Un ID AccessKey et un secret AccessKey pour votre compte Alibaba Cloud. Consultez la rubrique Créer une AccessKey.
L'ID AccessKey et le secret AccessKey stockés en tant que variables d'environnement locales. Consultez la rubrique Configurer des variables d'environnement.

Remarque

Le SDK se connecte directement au magasin en ligne. Le client doit s'exécuter au sein d'un Virtual Private Cloud (VPC). Par exemple, un magasin en ligne basé sur Hologres n'est accessible qu'à partir du VPC associé à cette instance Hologres.

Étape 1 : Installer le SDK

Téléchargez et installez le SDK Java FeatureStore.

Étape 2 : Initialiser le client

Créez un objet Configuration avec vos identifiants et le nom de votre projet, puis transmettez-le à FeatureStoreClient. Tous les appels ultérieurs de récupération de caractéristiques passent par ce client.

API

Configuration configuration = new Configuration(regionId, accessKeyId, accessKeySecret, projectName);

Paramètres

Paramètre	Exemple	Description
`regionId`	`cn-hangzhou`	Région de déploiement de votre projet FeatureStore
`accessKeyId`	`System.getenv("ACCESS_KEY_ID")`	ID AccessKey lu à partir d'une variable d'environnement
`accessKeySecret`	`System.getenv("ACCESS_KEY_SECRET")`	Secret AccessKey lu à partir d'une variable d'environnement
`projectName`	`holo_pro`	Nom de votre projet FeatureStore

Exemple

public class Constants {
    public static String accessId = "";
    public static String accessKey = "";
    public static String host = "paifeaturestore.cn-hangzhou.aliyuncs.com";

    static {
        // Read credentials from environment variables — never hardcode them.
        accessId = System.getenv("ACCESS_KEY_ID");
        accessKey = System.getenv("ACCESS_KEY_SECRET");
    }
}

// Initialize the configuration.
Configuration configuration = new Configuration("cn-hangzhou", Constants.accessId,
                                                Constants.accessKey, "dec8");
configuration.setDomain(Constants.host);

// Build the API client and the FeatureStore client.
ApiClient apiClient = new ApiClient(configuration);
FeatureStoreClient fsclient = new FeatureStoreClient(apiClient);

Étape 3 : Récupérer les données de caractéristiques à partir d'une vue de caractéristique

Utilisez FeatureView.getOnlineFeatures() pour interroger les caractéristiques stockées dans une vue de caractéristique spécifique. Les deux surcharges renvoient un FeatureResult contenant un enregistrement par ID de jointure.

API

// Retrieve all fields. No alias mapping.
public FeatureResult getOnlineFeatures(String[] joinIds);

// Retrieve selected fields, with optional field aliasing.
public FeatureResult getOnlineFeatures(String[] joinIds, String[] features, Map<String, String> aliasFields);

Paramètres

Paramètre	Exemple	Description
`joinIds`	`{"100001167","100001168"}`	Valeurs de clé primaire à rechercher. Renvoie un enregistrement par clé.
`features`	`{"user_id","city"}`	Champs à inclure dans la réponse. Passez `new String[]{"*"}` pour renvoyer tous les champs.
`aliasFields`	`{"user_id":"uId"}`	Renomme les champs dans la réponse. La clé correspond au nom du champ d'origine ; la valeur correspond à l'alias.

Exemple 1 : Vue de caractéristique hors ligne

Récupérez les données de caractéristiques synchronisées à partir d'une table hors ligne.

// Get the offline feature view named "mo1".
FeatureView mo1 = project.getFeatureViewMap().get("mo1");
if (mo1 == null) {
    throw new RuntimeException("This featureView does not exist");
}

HashMap<String, String> ss = new HashMap<>();
FeatureResult features = mo1.getOnlineFeatures(
    new String[]{"100001167", "100004088", "100006646"},
    new String[]{"*"},
    ss
);

Exemple de réponse :

[
  {
    "user_id": 100001167,
    "gender": "male",
    "age": 28,
    "city": "Shenyang",
    "item_cnt": 0,
    "follow_cnt": 0,
    "follower_cnt": 0,
    "register_time": 1696658585,
    "tags": "2"
  },
  {
    "user_id": 100004088,
    "gender": "female",
    "age": 28,
    "city": "Changchun",
    "item_cnt": 0,
    "follow_cnt": 8,
    "follower_cnt": 0,
    "register_time": 1695618449,
    "tags": "1"
  },
  {
    "user_id": 100006646,
    "gender": "male",
    "age": 28,
    "city": "Changchun",
    "item_cnt": 0,
    "follow_cnt": 1,
    "follower_cnt": 1,
    "register_time": 1698213339,
    "tags": "1"
  }
]

Exemple 2 : Vue de caractéristique en temps réel

Récupérez les données de caractéristiques écrites directement dans une table en ligne.

// Get the real-time feature view named "tfv1".
FeatureView tfv1 = project.getFeatureViewMap().get("tfv1");
if (tfv1 == null) {
    throw new RuntimeException("This featureView does not exist");
}

FeatureResult rf = tfv1.getOnlineFeatures(
    new String[]{"35d3d5a52a7515c2ca6bb4d8e965149b",
                 "0ab7e3efacd56983f16503572d2b9915",
                 "84dfd3f91dd85ea105bc74a4f0d7a067"},
    new String[]{"*"},
    ss
);

Exemple de réponse :

[
  {"USER_MD5": "35d3d5a52a7515c2ca6bb4d8e965149b", "USER_NICKNAME": "Miss Sini"},
  {"USER_MD5": "0ab7e3efacd56983f16503572d2b9915", "USER_NICKNAME": "Love You"},
  {"USER_MD5": "84dfd3f91dd85ea105bc74a4f0d7a067", "USER_NICKNAME": "Elementary Student's Dad"}
]

Exemple 3 : Vue de caractéristique séquentielle

Récupérez des séquences d'événements ordonnées à l'aide de SequenceFeatureView. Appelez project.getSeqFeatureView() au lieu de getFeatureViewMap().

// Get the sequence feature view named "ots_seq2".
SequenceFeatureView ots_seq2 = project.getSeqFeatureView("ots_seq2");
if (ots_seq2 == null) {
    throw new RuntimeException("This featureView does not exist");
}

// Retrieve all sequence fields. No feature or alias selection needed.
FeatureResult features2 = ots_seq2.getOnlineFeatures(new String[]{"157843277", "157843278"});

Exemple de réponse :

[
  {
    "user_id": "157843277",
    "click_50_seq": "null;200167895",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;200167895",
    "click_50_seq_playtime": "null;15.0",
    "click_50_seq_event_time": "null;1704684504747",
    "click_50_seq_ts": "625662604;625662604"
  },
  {
    "user_id": "157843278",
    "click_50_seq": "null;200167895",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;200167895",
    "click_50_seq_playtime": "null;15.0",
    "click_50_seq_event_time": "null;1704684504747",
    "click_50_seq_ts": "625662604;625662604"
  }
]

Étape 4 : Récupérer les données de caractéristiques à partir d'une caractéristique de modèle

Une caractéristique de modèle regroupe les vues de caractéristiques et les entités de caractéristiques dont un modèle a besoin au moment du service, ce qui vous permet de toutes les récupérer en un seul appel au lieu d'interroger chaque vue de caractéristique individuellement. Utilisez Model.getOnlineFeatures() pour récupérer les caractéristiques de toutes les entités de caractéristiques associées, ou Model.getOnlineFeaturesWithEntity() pour limiter la réponse à une entité de caractéristique spécifique.

API

// Retrieve features from all feature entities in the model feature.
public FeatureResult getOnlineFeatures(Map<String, List<String>> joinIds);

// Retrieve features from a specific feature entity in the model feature.
public FeatureResult getOnlineFeaturesWithEntity(Map<String, List<String>> joinIds, String featureEntityName);

Paramètres

Paramètre	Exemple	Description
`joinIds`	`{"user_id": ["101598051", "101598471"]}`	Une carte des noms d'ID de jointure vers des listes de valeurs de clé primaire. Chaque clé correspond à une entité de caractéristique.
`featureEntityName`	`"user"`	Le nom de l'entité de caractéristique à laquelle limiter la requête. Utilisé uniquement avec `getOnlineFeaturesWithEntity()`.

Une caractéristique de modèle peut être associée à plusieurs entités de caractéristiques. Fournissez le même nombre d'ID pour chaque type d'ID de jointure. Le SDK associe les ID par position dans toutes les listes.

Exemple 1 : Caractéristique de modèle sans caractéristiques séquentielles

Cet exemple récupère les caractéristiques pour user_id et item_id à partir de la caractéristique de modèle model_ots1, qui joint une entité de caractéristique utilisateur et une entité de caractéristique élément.

Model mf1 = project.getModelFeature("model_ots1");

HashMap<String, List<String>> mm = new HashMap<>();
mm.put("user_id", Arrays.asList("101598051", "101598471", "101601287"));
mm.put("item_id", Arrays.asList("200004157", "200006185", "200034730"));

Récupérer les caractéristiques de toutes les entités de caractéristiques :

FeatureResult fr1 = mf1.getOnlineFeatures(mm);

Exemple de réponse :

[
  {
    "user_id": 101598051, "gender": "male", "age": 28, "city": "Hangzhou",
    "item_cnt": 0, "follow_cnt": 0, "follower_cnt": 0,
    "register_time": 1695785665, "tags": "1",
    "item_id": 200004157, "author": 137649839, "category": 2,
    "click_count": 0, "duration": 18.0, "praise_count": 30,
    "pub_time": 1698208690, "title": "#Workout_Check-in"
  },
  {
    "user_id": 200004157, "gender": "female", "age": 31, "city": "Shenzhen",
    "item_cnt": 0, "follow_cnt": 1, "follower_cnt": 0,
    "register_time": 1695726582, "tags": "1",
    "item_id": 200006185, "author": 134195601, "category": 14,
    "click_count": 50, "duration": 55.0, "praise_count": 21,
    "pub_time": 1696700908, "title": "#Idiom_Story"
  },
  {
    "user_id": 101601287, "gender": "female", "age": 33, "city": "Shenzhen",
    "item_cnt": 0, "follow_cnt": 0, "follower_cnt": 55,
    "register_time": 1697519102, "tags": "0",
    "item_id": 200034730, "author": 112739045, "category": 6,
    "click_count": 2, "duration": 9.0, "praise_count": 0,
    "pub_time": 1696568654, "title": "#Workout_Check-in"
  }
]

Récupérer les caractéristiques d'une entité de caractéristique spécifique uniquement :

Transmettez le nom de l'entité de caractéristique ("server") pour limiter la réponse aux champs de cette entité.

FeatureResult fr2 = mf1.getOnlineFeaturesWithEntity(mm, "server");

Exemple de réponse :

[
  {"item_id": 200004157, "author": 137649839, "category": 2,
   "click_count": 0, "duration": 18.0, "praise_count": 30,
   "pub_time": 1698208690, "title": "#Workout_Check-in"},
  {"item_id": 200006185, "author": 134195601, "category": 14,
   "click_count": 50, "duration": 55.0, "praise_count": 21,
   "pub_time": 1696700908, "title": "#Idiom_Story"},
  {"item_id": 200034730, "author": 112739045, "category": 6,
   "click_count": 2, "duration": 9.0, "praise_count": 0,
   "pub_time": 1696568654, "title": "#Workout_Check-in"}
]

Exemple 2 : Caractéristique de modèle avec caractéristiques séquentielles

Lorsqu'une caractéristique de modèle inclut une vue de caractéristique séquentielle, la réponse combine les champs de caractéristiques réguliers avec les champs séquentiels. Cet exemple utilise mdt1, où join_id correspond à user_id.

Model mdt1 = project.getModelFeature("mdt1");
if (mdt1 == null) {
    throw new RuntimeException("This modelFeature does not exist");
}

HashMap<String, List<String>> fsmap = new HashMap<>();
fsmap.put("user_id", Arrays.asList("100001167", "100024146"));
fsmap.put("item_id", Arrays.asList("200138790", "200385417"));

Récupérer les caractéristiques de toutes les entités de caractéristiques :

FeatureResult fr3 = mdt2.getOnlineFeatures(fsmap);

Exemple de réponse (les champs séquentiels préfixés par click_50_seq_ apparaissent aux côtés des attributs réguliers) :

[
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292557212;1704292557212",
    "city": "Shenyang",
    "item_id": "200138790",
    "click_50_seq": "null;204153583",
    "author": 186784264,
    "pub_time": 1696574947,
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 2,
    "title": "#Idiom_Story",
    "register_time": 1696658585,
    "tags": 2,
    "duration": 13.0,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "praise_count": 3,
    "click_50_seq_event": "null;click",
    "category": 20,
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292547792;1704292547792;1704292547792",
    "city": "Ningbo",
    "item_id": 200385417,
    "click_50_seq": "null;299049390",
    "author": 189247964,
    "pub_time": 1696432224,
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 4,
    "title": "#Idiom_Story",
    "register_time": 1697253820,
    "tags": 1,
    "duration": "9.0",
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": 100024146,
    "praise_count": 0,
    "click_50_seq_event": "null;click",
    "category": 0,
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292557212;1704292557212",
    "city": "Shenyang",
    "item_id": 200138790,
    "click_50_seq": "null;204153583",
    "author": 186784264,
    "pub_time": 1696574947,
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 2,
    "title": "#Idiom_Story",
    "register_time": 1696658585,
    "tags": 2,
    "duration": 13.0,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "praise_count": 3,
    "click_50_seq_event": "null;click",
    "category": 20,
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292547792;1704292547792",
    "city": "Ningbo",
    "item_id": 200385417,
    "click_50_seq": "null;299049390",
    "author": 189247964,
    "pub_time": 1696432224,
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "click_count": 4,
    "title": "#Idiom_Story",
    "register_time": 1697253820,
    "tags": 1,
    "duration": 9.0,
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": "100024146",
    "praise_count": "0",
    "click_50_seq_event": "null;click",
    "category": 0,
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  }
]

Récupérer les caractéristiques d'une entité de caractéristique spécifique uniquement :

FeatureResult fr4 = mdt1.getOnlineFeaturesWithEntity(fsmap, "client");

Exemple de réponse (champs côté utilisateur et champs séquentiels uniquement, champs élément exclus) :

[
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292555552;1704292555552",
    "city": "Shenyang",
    "click_50_seq": "null;204153583",
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1696658585,
    "tags": 2,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292546132;1704292546132;1704292546132",
    "city": "Ningbo",
    "click_50_seq": "null;299049390",
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1697253820,
    "tags": "1",
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": 100024146,
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698170945",
    "gender": "male",
    "click_50_seq_ts": "1704292555552;1704292555552",
    "city": "Shenyang",
    "click_50_seq": "null;204153583",
    "follower_cnt": 0,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1696658585,
    "tags": 2,
    "click_50_seq_playtime": "null;98.93932923011255",
    "user_id": "100001167",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;204153583",
    "age": 28
  },
  {
    "click_50_seq_event_time": "null;1698180365",
    "gender": "male",
    "click_50_seq_ts": "1704292546132;1704292546132;1704292546132",
    "city": "Ningbo",
    "click_50_seq": "null;299049390",
    "follower_cnt": 47,
    "follow_cnt": 0,
    "item_cnt": 0,
    "register_time": 1697253820,
    "tags": 1,
    "click_50_seq_playtime": "null;32.15018252408633",
    "user_id": "100024146",
    "click_50_seq_event": "null;click",
    "click_50_seq_item_id": "null;299049390",
    "age": 28
  }
]

Étapes suivantes

Configurer un projet FeatureStore — configurez des projets, des entités de caractéristiques, des vues de caractéristiques et des caractéristiques de modèle
Créer une AccessKey — obtenez des identifiants pour l'authentification du SDK
Référentiel du SDK Java FeatureStore — code source complet du SDK, notes de version et historique des versions