[feat] add vocab file for features (#97)

Author: tiankongdeguiji

data/test/id_vocab_dict_2

@@ -0,0 +1,4 @@
+  0
+<OOV> 1
+abc 2
+efg 2

data/test/id_vocab_dict_3

@@ -0,0 +1,4 @@
+xyz 0
+<OOV> 1
+abc 2
+efg 2

data/test/id_vocab_list_0

@@ -0,0 +1,4 @@
+<BLK>
+<OOV>
+abc
+efg

data/test/id_vocab_list_1

@@ -0,0 +1,4 @@
+xyz
+<OOV>
+abc
+efg

docs/source/feature/data.md

@@ -159,11 +159,11 @@ sample_weight_fields: 'col_name'
     - --ODPS_CONFIG_FILE_PATH: 该环境变量指向的是odpscmd的配置文件
   - 在[DataWorks](https://workbench.data.aliyun.com/)的独享资源组中安装pyfg，「资源组列表」- 在一个调度资源组的「操作」栏 点「运维助手」-「创建命令」（选手动输入）-「运行命令」
     ```shell
-    /home/tops/bin/pip3 install http://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg039-0.3.9-cp37-cp37m-linux_x86_64.whl
+    /home/tops/bin/pip3 install http://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg044-0.4.4-cp37-cp37m-linux_x86_64.whl
     ```
   - 在DataWorks中建立`PyODPS 3`节点运行FG，节点调度参数中配置好bizdate参数
     ```
-    from pyfg039 import offline_pyfg
+    from pyfg044 import offline_pyfg
     offline_pyfg.run(
       o,
       input_table="YOU_PROJECT.TABLE_NAME",

docs/source/feature/feature.md

@@ -14,7 +14,7 @@ TorchEasyRec多种类型的特征，包括IdFeature、RawFeature、ComboFeature
 
 - **init_fn**: 特征嵌入初始化方式，默认不需要设置，如需自定义，可以设置任意的torch内置初始化函数，如`nn.init.uniform_,a=-0.01,b=0.01`
 
-- **default_value**: 特征默认值。如果默认值为""，则没有默认值，后续模型中对于空特征的嵌入为零向量。注意: 该默认值为`bucktize`前的默认值。`bucktize`的配置包括`hash_bucket_size`/`vocab_list`/`boundaries`
+- **default_value**: 特征默认值。如果默认值为""，则没有默认值，后续模型中对于空特征的嵌入为零向量。注意: 该默认值为`bucketize`前的默认值。`bucketize`的配置包括`num_buckets`/`hash_bucket_size`/`vocab_list`/`vocab_dict`/`vocab_file`/`boundaries`
 
 - **separator**: FG在输入为string类型时的多值分隔符，默认为`\x1d`。更建议用数组（ARRAY）类型来表示多值，训练和推理性能更好
 
@@ -86,6 +86,11 @@ feature_configs {
 
 - **vocab_dict**: 指定字典形式词表，适合多个词需要编码到同一个编号情况，**编号需要从2开始**，编码0预留给默认值，编码1预留给超出词表的词
 
+- **vocab_file**: 指定词表或字典形式词表的文件路径，适合取值比较多兵可以枚举的特征，编码未预留，必须设置**default_bucketize_value**参数
+
+  - 词表形式：一行一个词
+  - 字典词表形式：一行一个词和编号，词和编号间用空格分隔
+
 - **zch**: 零冲突hash，可设置Id的准入和驱逐策略，详见[文档](../zch.md)
 
 - **weighted**: 是否为带权重的Id特征，输入形式为`k1:v1\x1dk2:v2`
@@ -240,21 +245,13 @@ feature_configs: {
 
 如果Map的值为离散值 或 `need_key=true`，可设置:
 
-- **hash_bucket_size**: hash bucket的大小。
-- **num_buckets**: buckets数量, 仅仅当输入是integer类型时，可以使用num_buckets
-- **vocab_list**: 指定词表，适合取值比较少可以枚举的特征。
-- **vocab_dict**: 指定字典形式词表，适合多个词需要编码到同一个编号情况，**编号需要从2开始**，编码0预留给默认值，编码1预留给超出词表的词
-- **zch**: 零冲突hash，可设置Id的准入和驱逐策略，详见[文档](../zch.md)
 - **value_dim**: 默认值是1，可以设置0，value_dim=0时支持多值ID输出
+- 其余配置同IdFeature
 
 如果Map的值为连续值，可设置:
 
-- **boundaries**: 分箱/分桶的值。
-- **normalizer**: 连续值特征的变换方式，同RawFeature
 - **value_dim**: 默认值是1，连续值输出维度
-- **value_separator**: 连续值分隔符
-- **mlp**: 由一层MLP变换特征到`embedding_dim`维度
-- **autodis**: 由AutoDis模块变换特征到`embedding_dim`维度，详见[AutoDis文档](../autodis.md)
+- 其余配置同RawFeature
 
 ## MatchFeature: 主从键字典查询特征
 
@@ -283,20 +280,13 @@ feature_configs: {
 
 如果Map的值为离散值 或 `show_pkey=true` 或 `show_skey=true`，可设置:
 
-- **hash_bucket_size**: hash bucket的大小。
-- **num_buckets**: buckets数量, 仅仅当输入是integer类型时，可以使用num_buckets
-- **vocab_list**: 指定词表，适合取值比较少可以枚举的特征。
-- **vocab_dict**: 指定字典形式词表，适合多个词需要编码到同一个编号情况，**编号需要从2开始**，编码0预留给默认值，编码1预留给超出词表的词
-- **zch**: 零冲突hash，可设置Id的准入和驱逐策略，详见[文档](../zch.md)
 - **value_dim**: 默认值是1，可以设置0，value_dim=0时支持多值ID输出
+- 其余配置同IdFeature
 
 如果Map的值为连续值，可设置:
 
-- **boundaries**: 分箱/分桶的值。
-- **normalizer**: 连续值特征的变换方式，同RawFeature
 - **value_dim**: 目前只支持value_dim=1
-- **mlp**: 由一层MLP变换特征到`embedding_dim`维度
-- **autodis**: 由AutoDis模块变换特征到`embedding_dim`维度，详见[AutoDis文档](../autodis.md)
+- 其余配置同RawFeature
 
 ## ExprFeature: 表达式特征
 

docs/source/usage/serving.md

@@ -43,7 +43,7 @@ cat << EOF > tzrec_rank.json
       }
     }
   ],
-  "processor":"easyrec-torch-0.7"
+  "processor":"easyrec-torch-1.0"
 }
 EOF
 

requirements/runtime.txt

@@ -7,8 +7,8 @@ graphlearn @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/graphlearn-1.
 graphlearn @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/graphlearn-1.3.3-cp310-cp310-linux_x86_64.whl ; python_version=="3.10"
 grpcio-tools<1.63.0
 pandas
-pyfg @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg-0.3.9-cp311-cp311-linux_x86_64.whl ; python_version=="3.11"
-pyfg @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg-0.3.9-cp310-cp310-linux_x86_64.whl ; python_version=="3.10"
+pyfg @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg-0.4.4-cp311-cp311-linux_x86_64.whl ; python_version=="3.11"
+pyfg @ https://tzrec.oss-cn-beijing.aliyuncs.com/third_party/pyfg-0.4.4-cp310-cp310-linux_x86_64.whl ; python_version=="3.10"
 pyodps>=0.12.0
 scikit-learn
 tensorboard

tzrec/features/combo_feature.py

@@ -62,6 +62,9 @@ def num_embeddings(self) -> int:
             num_embeddings = len(self.vocab_list)
         elif len(self.vocab_dict) > 0:
             num_embeddings = max(list(self.vocab_dict.values())) + 1
+        elif len(self.vocab_file) > 0:
+            self.init_fg()
+            num_embeddings = self._fg_op.vocab_list_size()
         else:
             raise ValueError(
                 f"{self.__class__.__name__}[{self.name}] must set hash_bucket_size"
@@ -126,4 +129,7 @@ def fg_json(self) -> List[Dict[str, Any]]:
         elif len(self.vocab_dict) > 0:
             fg_cfg["vocab_dict"] = self.vocab_dict
             fg_cfg["default_bucketize_value"] = self.default_bucketize_value
+        elif len(self.vocab_file) > 0:
+            fg_cfg["vocab_file"] = self.vocab_file
+            fg_cfg["default_bucketize_value"] = self.default_bucketize_value
         return [fg_cfg]

tzrec/features/feature.py

@@ -656,6 +656,21 @@ def vocab_dict(self) -> Dict[str, int]:
                 self._vocab_dict = {}
         return self._vocab_dict
 
+    @property
+    def vocab_file(self) -> str:
+        """Vocab file."""
+        if self.config.HasField("vocab_file"):
+            if not self.config.HasField("default_bucketize_value"):
+                raise ValueError(
+                    "default_bucketize_value must be set when use vocab_file."
+                )
+            vocab_file = self.config.vocab_file
+            if self.config.HasField("asset_dir"):
+                vocab_file = os.path.join(self.config.asset_dir, vocab_file)
+            return vocab_file
+        else:
+            return ""
+
     @property
     def default_bucketize_value(self) -> int:
         """Default bucketize value."""

tzrec/features/id_feature.py

@@ -87,6 +87,9 @@ def num_embeddings(self) -> int:
             num_embeddings = len(self.vocab_list)
         elif len(self.vocab_dict) > 0:
             num_embeddings = max(list(self.vocab_dict.values())) + 1
+        elif len(self.vocab_file) > 0:
+            self.init_fg()
+            num_embeddings = self._fg_op.vocab_list_size()
         else:
             raise ValueError(
                 f"{self.__class__.__name__}[{self.name}] must set hash_bucket_size"
@@ -175,6 +178,10 @@ def fg_json(self) -> List[Dict[str, Any]]:
             fg_cfg["vocab_dict"] = self.vocab_dict
             fg_cfg["default_bucketize_value"] = self.default_bucketize_value
             fg_cfg["value_type"] = "string"
+        elif len(self.vocab_file) > 0:
+            fg_cfg["vocab_file"] = self.vocab_file
+            fg_cfg["default_bucketize_value"] = self.default_bucketize_value
+            fg_cfg["value_type"] = "string"
         elif self.config.HasField("num_buckets"):
             fg_cfg["num_buckets"] = self.config.num_buckets
             if self.config.default_value:
@@ -188,3 +195,10 @@ def fg_json(self) -> List[Dict[str, Any]]:
         else:
             fg_cfg["value_dim"] = 0
         return [fg_cfg]
+
+    def assets(self) -> Dict[str, str]:
+        """Asset file paths."""
+        assets = {}
+        if len(self.vocab_file) > 0:
+            assets["vocab_file"] = self.vocab_file
+        return assets

tzrec/features/id_feature_test.py

@@ -413,6 +413,59 @@ def test_id_feature_with_num_buckets(
         np.testing.assert_allclose(parsed_feat.values, np.array(expected_values))
         np.testing.assert_allclose(parsed_feat.lengths, np.array(expected_lengths))
 
+    @parameterized.expand(
+        [
+            ["", "data/test/id_vocab_list_0", 4, [2, 3, 1], [2, 0, 1]],
+            ["xyz", "data/test/id_vocab_list_1", 4, [2, 3, 0, 1], [2, 1, 1]],
+            ["", "data/test/id_vocab_dict_2", 3, [2, 2, 1], [2, 0, 1]],
+            ["xyz", "data/test/id_vocab_dict_3", 3, [2, 2, 0, 1], [2, 1, 1]],
+        ],
+        name_func=test_util.parameterized_name_func,
+    )
+    def test_id_feature_with_vocab_file(
+        self,
+        default_value,
+        vocab_file,
+        expected_num_embeddings,
+        expected_values,
+        expected_lengths,
+    ):
+        id_feat_cfg = feature_pb2.FeatureConfig(
+            id_feature=feature_pb2.IdFeature(
+                feature_name="id_feat",
+                embedding_dim=16,
+                vocab_file=vocab_file,
+                default_bucketize_value=1,
+                expression="user:id_str",
+                pooling="mean",
+                default_value=default_value,
+            )
+        )
+
+        id_feat = id_feature_lib.IdFeature(id_feat_cfg, fg_mode=FgMode.FG_NORMAL)
+
+        expected_emb_bag_config = EmbeddingBagConfig(
+            num_embeddings=expected_num_embeddings,
+            embedding_dim=16,
+            name="id_feat_emb",
+            feature_names=["id_feat"],
+            pooling=PoolingType.MEAN,
+        )
+        self.assertEqual(repr(id_feat.emb_bag_config), repr(expected_emb_bag_config))
+        expected_emb_config = EmbeddingConfig(
+            num_embeddings=expected_num_embeddings,
+            embedding_dim=16,
+            name="id_feat_emb",
+            feature_names=["id_feat"],
+        )
+        self.assertEqual(repr(id_feat.emb_config), repr(expected_emb_config))
+
+        input_data = {"id_str": pa.array(["abc\x1defg", "", "hij"])}
+        parsed_feat = id_feat.parse(input_data)
+        self.assertEqual(parsed_feat.name, "id_feat")
+        np.testing.assert_allclose(parsed_feat.values, np.array(expected_values))
+        np.testing.assert_allclose(parsed_feat.lengths, np.array(expected_lengths))
+
 
 if __name__ == "__main__":
     unittest.main()

tzrec/features/lookup_feature.py

@@ -85,6 +85,7 @@ def is_sparse(self) -> bool:
                 or self.config.HasField("num_buckets")
                 or len(self.vocab_list) > 0
                 or len(self.vocab_dict) > 0
+                or len(self.vocab_file) > 0
                 or len(self.config.boundaries) > 0
             )
         return self._is_sparse
@@ -102,6 +103,9 @@ def num_embeddings(self) -> int:
             num_embeddings = len(self.vocab_list)
         elif len(self.vocab_dict) > 0:
             num_embeddings = max(list(self.vocab_dict.values())) + 1
+        elif len(self.vocab_file) > 0:
+            self.init_fg()
+            num_embeddings = self._fg_op.vocab_list_size()
         else:
             num_embeddings = len(self.config.boundaries) + 1
         return num_embeddings
@@ -235,6 +239,11 @@ def fg_json(self) -> List[Dict[str, Any]]:
                 fg_cfg["default_bucketize_value"] = self.default_bucketize_value
                 fg_cfg["value_type"] = "string"
                 fg_cfg["needDiscrete"] = True
+            elif len(self.vocab_file) > 0:
+                fg_cfg["vocab_file"] = self.vocab_file
+                fg_cfg["default_bucketize_value"] = self.default_bucketize_value
+                fg_cfg["value_type"] = "string"
+                fg_cfg["needDiscrete"] = True
             elif len(self.config.boundaries) > 0:
                 fg_cfg["boundaries"] = list(self.config.boundaries)
 
@@ -247,3 +256,10 @@ def fg_json(self) -> List[Dict[str, Any]]:
         if raw_fg_cfg is not None:
             fg_cfgs.append(raw_fg_cfg)
         return fg_cfgs
+
+    def assets(self) -> Dict[str, str]:
+        """Asset file paths."""
+        assets = {}
+        if len(self.vocab_file) > 0:
+            assets["vocab_file"] = self.vocab_file
+        return assets

tzrec/features/match_feature.py

@@ -87,6 +87,7 @@ def is_sparse(self) -> bool:
                 or self.config.HasField("num_buckets")
                 or len(self.config.vocab_list) > 0
                 or len(self.config.vocab_dict) > 0
+                or len(self.config.vocab_file) > 0
                 or len(self.config.boundaries) > 0
             )
         return self._is_sparse
@@ -104,6 +105,9 @@ def num_embeddings(self) -> int:
             num_embeddings = len(self.vocab_list) + 1
         elif len(self.vocab_dict) > 0:
             num_embeddings = max(list(self.vocab_dict.values())) + 1
+        elif len(self.vocab_file) > 0:
+            self.init_fg()
+            num_embeddings = self._fg_op.vocab_list_size()
         else:
             num_embeddings = len(self.config.boundaries) + 1
         return num_embeddings
@@ -208,10 +212,22 @@ def fg_json(self) -> List[Dict[str, Any]]:
             fg_cfg["default_bucketize_value"] = self.default_bucketize_value
             fg_cfg["value_type"] = "string"
             fg_cfg["needDiscrete"] = True
+        elif len(self.vocab_file) > 0:
+            fg_cfg["vocab_file"] = self.vocab_file
+            fg_cfg["default_bucketize_value"] = self.default_bucketize_value
+            fg_cfg["value_type"] = "string"
+            fg_cfg["needDiscrete"] = True
         elif len(self.config.boundaries) > 0:
             fg_cfg["boundaries"] = list(self.config.boundaries)
 
         if fg_cfg["needDiscrete"]:
             fg_cfg["value_dim"] = self.value_dim
         #     del fg_cfg["combiner"]
         return [fg_cfg]
+
+    def assets(self) -> Dict[str, str]:
+        """Asset file paths."""
+        assets = {}
+        if len(self.vocab_file) > 0:
+            assets["vocab_file"] = self.vocab_file
+        return assets

tzrec/features/sequence_feature.py

@@ -327,6 +327,9 @@ def fg_json(self) -> List[Dict[str, Any]]:
         elif len(self.config.vocab_dict) > 0:
             fg_cfg["vocab_dict"] = self.vocab_dict
             fg_cfg["default_bucketize_value"] = self.default_bucketize_value
+        elif len(self.vocab_file) > 0:
+            fg_cfg["vocab_file"] = self.vocab_file
+            fg_cfg["default_bucketize_value"] = self.default_bucketize_value
         if self.config.HasField("value_dim"):
             fg_cfg["value_dim"] = self.config.value_dim
         else: