FeatureStore Java SDK - Platform For AI: Central de Documentação do Alibaba Cloud

Utilize o FeatureStore Java SDK para ler dados de features online do seu projeto PAI FeatureStore durante a inferência. O SDK oferece suporte a três tipos de features:

Tipo de feature	Método de recuperação	Uso típico
Feature offline	Visualização de feature (`FeatureView`)	Atributos de usuário ou item sincronizados em lote
Feature em tempo real	Visualização de feature (`FeatureView`)	Sinais atualizados em tempo real gravados diretamente no armazenamento online
Feature de sequência	Visualização de feature de sequência (`SequenceFeatureView`)	Histórico ordenado de eventos (cliques, reproduções, compras)

Para recuperar features agrupadas por modelo, utilize Model.getOnlineFeatures() ou Model.getOnlineFeaturesWithEntity() em vez de consultar cada visualização de feature individualmente.

Pré-requisitos

Antes de começar, verifique se você possui:

Um projeto FeatureStore com pelo menos uma entidade de feature, uma visualização de feature e uma feature de modelo configurados e sincronizados. Consulte Configurar um projeto FeatureStore.
Um AccessKey ID e um AccessKey secret para sua conta Alibaba Cloud. Consulte Criar um AccessKey.
O AccessKey ID e o AccessKey secret armazenados como variáveis de ambiente locais. Consulte Configurar variáveis de ambiente.

Nota

O SDK conecta-se diretamente ao armazenamento online. O cliente deve ser executado dentro de uma Virtual Private Cloud (VPC). Por exemplo, um armazenamento online baseado em Hologres só é acessível de dentro da VPC associada àquela instância do Hologres.

Etapa 1: Instale o SDK

Baixe e instale o FeatureStore Java SDK.

Etapa 2: Inicializar o cliente

Crie um objeto Configuration com suas credenciais e nome do projeto e passe-o para FeatureStoreClient. Todas as chamadas subsequentes de recuperação de features passam por este cliente.

API

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

Parâmetros

Parâmetro	Exemplo	Descrição
`regionId`	`cn-hangzhou`	A região onde seu projeto FeatureStore está implantado
`accessKeyId`	`System.getenv("ACCESS_KEY_ID")`	AccessKey ID lido de uma variável de ambiente
`accessKeySecret`	`System.getenv("ACCESS_KEY_SECRET")`	AccessKey secret lido de uma variável de ambiente
`projectName`	`holo_pro`	O nome do seu projeto FeatureStore

Exemplo

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);

Etapa 3: Recuperar dados de features de uma visualização de feature

Use FeatureView.getOnlineFeatures() para consultar features armazenadas em uma visualização de feature específica. Ambas as sobrecargas retornam um FeatureResult contendo um registro por join ID.

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);

Parâmetros

Parâmetro	Exemplo	Descrição
`joinIds`	`{"100001167","100001168"}`	Valores de chave primária para consulta. Retorna um registro por chave.
`features`	`{"user_id","city"}`	Campos a serem incluídos na resposta. Passe `new String[]{"*"}` para retornar todos os campos.
`aliasFields`	`{"user_id":"uId"}`	Renomeia campos na resposta. A chave é o nome original do campo; o valor é o alias.

Exemplo 1: Visualização de feature offline

Recupere dados de features sincronizados de uma tabela offline.

// 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
);

Resposta de exemplo:

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

Exemplo 2: Visualização de feature em tempo real

Recupere dados de features gravados diretamente em uma tabela online.

// 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
);

Resposta de exemplo:

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

Exemplo 3: Visualização de feature de sequência

Recupere sequências de eventos ordenadas usando SequenceFeatureView. Chame project.getSeqFeatureView() em vez 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"});

Resposta de exemplo:

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

Etapa 4: Recuperar dados de features de uma feature de modelo

Uma feature de modelo agrupa as visualizações de features e entidades de features que um modelo necessita no momento da inferência, permitindo buscar todas elas com uma única chamada em vez de consultar cada visualização de feature individualmente. Use Model.getOnlineFeatures() para recuperar features de todas as entidades de features associadas, ou Model.getOnlineFeaturesWithEntity() para limitar a resposta a uma entidade de feature específica.

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);

Parâmetros

Parâmetro	Exemplo	Descrição
`joinIds`	`{"user_id": ["101598051", "101598471"]}`	Um mapa de nomes de join ID para listas de valores de chave primária. Cada chave corresponde a uma entidade de feature.
`featureEntityName`	`"user"`	O nome da entidade de feature para escopo da consulta. Usado apenas com `getOnlineFeaturesWithEntity()`.

Uma feature de modelo pode estar associada a múltiplas entidades de features. Forneça o mesmo número de IDs para cada tipo de join ID. O SDK pareia os IDs por posição em todas as listas.

Exemplo 1: Feature de modelo sem features de sequência

Este exemplo recupera features para user_id e item_id da feature de modelo model_ots1, que une uma entidade de feature de usuário e uma entidade de feature de item.

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"));

Recuperar features de todas as entidades de features:

FeatureResult fr1 = mf1.getOnlineFeatures(mm);

Resposta de exemplo:

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

Recuperar features apenas de uma entidade de feature específica:

Passe o nome da entidade de feature ("server") para limitar a resposta aos campos dessa entidade.

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

Resposta de exemplo:

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

Exemplo 2: Feature de modelo com features de sequência

Quando uma feature de modelo inclui uma visualização de feature de sequência, a resposta combina campos de features regulares com campos de sequência. Este exemplo usa mdt1, onde join_id corresponde a 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"));

Recuperar features de todas as entidades de features:

FeatureResult fr3 = mdt2.getOnlineFeatures(fsmap);

Resposta de exemplo (campos de sequência com prefixo click_50_seq_ aparecem junto com atributos regulares):

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

Recuperar features apenas de uma entidade de feature específica:

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

Resposta de exemplo (apenas campos do lado do usuário e campos de sequência, campos de item excluídos):

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

Próximos passos

Configurar um projeto FeatureStore — configure projetos, entidades de features, visualizações de features e features de modelo
Criar um AccessKey — obtenha credenciais para autenticação do SDK
Repositório do FeatureStore Java SDK — código-fonte completo do SDK, notas de lançamento e histórico de versões