fix id_feature's number_buckets uage with fg，add more info for using

docs/source/benchmark.md

@@ -9,6 +9,7 @@
 - 该数据集是淘宝展示广告点击率预估数据集，包含用户、广告特征和行为日志。[天池比赛链接](https://tianchi.aliyun.com/dataset/dataDetail?dataId=56)
 - 训练数据表：pai_online_project.easyrec_demo_taobao_train_data
 - 测试数据表：pai_online_project.easyrec_demo_taobao_test_data
+- 其中pai_online_project是一个公共读的MaxCompute project，里面写入了一些数据表做测试，不需要申请权限。
 - 在PAI上面测试使用的资源包括2个parameter server，9个worker，其中一个worker做评估:
   ```json
   {"ps":{"count":2,

docs/source/feature/data.md

@@ -2,15 +2,15 @@
 
 EasyRec作为阿里云PAI的推荐算法包，可以无缝对接MaxCompute的数据表，也可以读取OSS中的大文件，还支持E-MapReduce环境中的HDFS文件，也支持local环境中的csv文件。
 
-为了识别这些输入数据中的字段信息，需要设置相应的字段名称和字段类型、设置默认值，帮助EasyRec去读取相应的数据。设置label字段，作为训练的目标。为了适应多目标模型，label字段可以设置多个。
+为了识别这些输入数据中的字段信息，需要设置相应的字段名称和字段类型、设置默认值，帮助EasyRec去读取相应的数据。设置label字段，作为训练的目标。为了适配多目标模型，label字段可设置多个。
 
 另外还有一些参数如prefetch_size，是tensorflow中读取数据需要设置的参数。
 
 ## 一个最简单的data config的配置
 
 这个配置里面，只有三个字段，用户ID（uid）、物品ID（item_id）、label字段（click）。
 
-OdpsInputV2表示读取MaxCompute的表作为输入数据。
+OdpsInputV2表示读取MaxCompute的表作为输入数据。如果是本地机器上训练，注意使用CSVInput类型。
 
 ```protobuf
 data_config {
@@ -160,7 +160,7 @@ def remap_lbl(labels):
 ### prefetch_size
 
 - data prefetch，以batch为单位，默认是32
-- 设置prefetch size可以提高数据加载的速度，防止数据瓶颈
+- 设置prefetch size可以提高数据加载的速度，防止数据瓶颈。但是当batchsize较小的时候，该值可适当调小。
 
 ### shard && file_shard
 

docs/source/feature/feature.rst

@@ -3,7 +3,7 @@
 
 在上一节介绍了输入数据包括MaxCompute表、csv文件、hdfs文件、OSS文件等，表或文件的一列对应一个特征。
 
-在数据中可以有一个或者多个label字段，而特征比较丰富，支持的类型包括IdFeature，RawFeature，TagFeature，SequenceFeature, ComboFeature.
+在数据中可以有一个或者多个label字段，在多目标模型中，需要多个label字段。而特征比较丰富，支持的类型包括IdFeature，RawFeature，TagFeature，SequenceFeature, ComboFeature。
 
 各种特征共用字段
 ----------------------------------------------------------------
@@ -71,12 +71,12 @@ IdFeature: 离散值特征/ID类特征
 
    .. math::
 
-        embedding\_dim=8+x^{0.25}
-  - 其中，x 为不同特征取值的个数
+        embedding\_dim=8+n^{0.25}
+  - 其中，n 是特征的唯一值的个数（如gender特征的取值是男、女，则n=2）
 
 -  hash\_bucket\_size: hash bucket的大小。适用于category_id, user_id等
 
--  对于user\_id等规模比较大的，hash冲突影响比较小的特征，
+-  对于user\_id等规模比较大的，hash冲突影响比较小的特征，用户行为日志不够丰富可通过hash压缩id数量，
 
    .. math::
 
@@ -91,7 +91,8 @@ IdFeature: 离散值特征/ID类特征
 
 
 -  num\_buckets: buckets number,
-   仅仅当输入是integer类型时，可以使用num\_buckets
+   仅仅当输入是integer类型时，可以使用num\_buckets。
+   但是当使用fg特征的时候，不要用integer特征用num\_buckets的方式来变换，注意要用hash\_bucket\_size的方式。
 
 -  vocab\_list:
    指定词表，适合取值比较少可以枚举的特征，如星期，月份，星座等

docs/source/feature/pai_rec_callback_conf.md

@@ -1,4 +1,6 @@
 # PAI-REC 全埋点配置
+## PAI-Rec引擎的callback服务文档
+- [文档](http://pai-vision-data-hz.oss-cn-zhangjiakou.aliyuncs.com/pairec/docs/pairec/html/intro/callback_api.html)
 
 ## 模板
 

docs/source/feature/rtp_fg.md

@@ -2,7 +2,7 @@
 
 - RTP FG: RealTime Predict Feature Generation, 解决实时预测需要的特征工程需求. 特征工程在推荐链路里面也占用了比较长的时间.
 
-- RTP FG能够以比较高的效率生成一些复杂的交叉特征，如match feature和lookup feature, 通过使用同一套c++代码保证离线在线的一致性.
+- RTP FG能够以比较高的效率生成一些复杂的交叉特征，如match feature和lookup feature.离线训练和在线预测的时候通过使用同一套c++代码保证离线在线的一致性.
 
 - 其生成的特征可以接入EasyRec进行训练，从RTP FG的配置(fg.json)可以生成EasyRec的配置文件(pipeline.config).
 

docs/source/feature/rtp_native.md

@@ -1,6 +1,6 @@
 # RTP部署
 
-本文档介绍将EasyRec模型部署到RTP上的流程.
+本文档介绍将EasyRec模型部署到RTP（Real Time Prediction，实时打分服务）上的流程.
 
 - RTP目前仅支持checkpoint形式的模型部署，因此需要将EasyRec模型导出为checkpoint形式
 

docs/source/intro.md

@@ -62,5 +62,5 @@ EasyRec implements state of the art machine learning models used in common recom
 - Run [`knn algorithm`](vector_retrieve.md) of vectors in distribute environment
 
 ### Contact
-
+- DingDing Group: 32260796. (EasyRec usage general discussion.)
 - DingDing Group: 37930014162, click [this url](https://qr.dingtalk.com/action/joingroup?code=v1,k1,oHNqtNObbu+xUClHh77gCuKdGGH8AYoQ8AjKU23zTg4=&_dt_no_comment=1&origin=11) or scan QrCode to join![new_group.jpg](../images/qrcode/new_group.jpg)

docs/source/predict/MaxCompute 离线预测.md

@@ -11,7 +11,7 @@
 drop table if exists ctr_test_output;
 pai -name easy_rec_ext
 -Dcmd=predict
--Dcluster='{"worker" : {"count":5, "cpu":1600,  "memory":40000, "gpu":100}}'
+-Dcluster='{"worker" : {"count":5, "cpu":1000,  "memory":40000, "gpu":0}}'
 -Darn=acs:ram::xxx:role/aliyunodpspaidefaultrole
 -Dbuckets=oss://easyrec/
 -Dsaved_model_dir=oss://easyrec/easy_rec_test/experiment/export/1597299619
@@ -23,6 +23,7 @@ pai -name easy_rec_ext
 -DossHost=oss-cn-beijing-internal.aliyuncs.com;
 ```
 
+- cluster: 这里cpu:1000表示是10个cpu核；核与内存的关系设置1:4000，一般不超过40000；gpu设置为0，表示不用GPU推理。
 - saved_model_dir: 导出的模型目录
 - output_table: 输出表，不需要提前创建，会自动创建
 - excluded_cols: 预测模型不需要的columns，比如labels
@@ -55,6 +56,8 @@ pai -name easy_rec_ext
   - 多分类模型(num_class > 1)，导出字段:
     - logits: string(json), softmax之前的vector, shape\[num_class\]
     - probs: string(json), softmax之后的vector, shape\[num_class\]
+      - 如果一个分类目标是is_click, 输出概率的变量名称是probs_is_click
+      - 多目标模型中有一个回归目标是paytime，那么输出回归预测分的变量名称是：y_paytime
     - logits_y: logits\[y\], float, 类别y对应的softmax之前的概率
     - probs_y: probs\[y\], float, 类别y对应的概率
     - y: 类别id, = argmax(probs_y), int, 概率最大的类别

docs/source/predict/processor.md

@@ -1,17 +1,17 @@
 # EasyRec Processor
 
-EasyRec Processor, 是EasyRec对应的高性能在线打分引擎, 包含特征处理和模型推理功能. EasyRecProcessor运行在PAI-EAS之上, 可以充分利用PAI-EAS多种优化特性.
+EasyRec Processor([阿里云上的EasyRec Processor详细文档，包括版本、使用方式](https://help.aliyun.com/zh/pai/user-guide/easyrec)), 是EasyRec对应的高性能在线打分引擎, 包含特征处理和模型推理功能. EasyRecProcessor运行在PAI-EAS之上, 可以充分利用PAI-EAS多种优化特性.
 
 ## 架构设计
 
-EasyRec Processor包含三个部分: Item特征缓存, 特征处理(Feature Generator), TFModel(tensorflow model).
+EasyRec Processor包含三个部分: Item特征缓存（支持通过[FeatureStore](https://help.aliyun.com/zh/pai/user-guide/featurestore-overview)加载MaxCompute表做初始化）, 特征生成(Feature Generator), TFModel(tensorflow model).
 ![image.png](../../images/processor/easy_rec_processor_1.png)
 
 ## 性能优化
 
 ### 基础实现
 
-将FeatureGenerator和TFModel分开, 先做特征生成，然后再Run TFModel.
+将FeatureGenerator和TFModel分开, 先做特征生成（即fg），然后再Run TFModel得到预测结果.
 
 ### 优化实现
 

docs/source/predict/在线预测.md

@@ -1,6 +1,6 @@
 # Model Serving
 
-推荐使用阿里云上的[模型在线服务(PAI-EAS)](https://help.aliyun.com/document_detail/113696.html)预置的EasyRecProcessor 来部署在线推理服务。EasyRecProcessor针对推荐模型做了多种优化, 相比tensorflow serving和TensorRT方式部署具有显著的[性能优势](./processor.md)。
+推荐使用阿里云上的[模型在线服务(PAI-EAS)](https://help.aliyun.com/document_detail/113696.html)预置的EasyRecProcessor 来部署在线推理服务。EasyRec Processor（[阿里云文档](https://help.aliyun.com/zh/pai/user-guide/easyrec)）针对推荐模型做了多种优化, 相比tensorflow serving和TensorRT方式部署具有显著的[性能优势](./processor.md)。
 
 ## 命令行部署
 

docs/source/quick_start/designer_tutorial.md

@@ -94,3 +94,7 @@ PAI-Designer（Studio 2.0）是基于云原生架构Pipeline Service（PAIFlow
 `pai -name easy_rec_ext -project algo_public  -Dcmd=predict`
 
 - 具体命令及详细[参数说明](../train.md#on-pai)
+
+### 推荐算法定制的方案
+
+- 在Designer中做推荐算法特征工程、排序模型训练、向量召回等案例的阿里云官网[文档链接](https://help.aliyun.com/zh/pai/use-cases/overview-18)

docs/source/quick_start/local_tutorial.md

@@ -4,6 +4,8 @@
 
 我们提供了`本地Anaconda安装`和`Docker镜像启动`两种方式。
 
+有技术问题可加钉钉群：37930014162
+
 #### 本地Anaconda安装
 
 Demo实验中使用的环境为 `python=3.6.8` + `tenserflow=1.12.0`
@@ -52,7 +54,7 @@ sudo docker exec -it <CONTAINER_ID> bash
 
 输入一般是csv格式的文件。
 
-#### 示例数据
+#### 示例数据(点击下载)
 
 - train: [dwd_avazu_ctr_deepmodel_train.csv](http://easyrec.oss-cn-beijing.aliyuncs.com/data/dwd_avazu_ctr_deepmodel_train.csv)
 - test: [dwd_avazu_ctr_deepmodel_test.csv](http://easyrec.oss-cn-beijing.aliyuncs.com/data/dwd_avazu_ctr_deepmodel_test.csv)

docs/source/quick_start/mc_tutorial.md

@@ -4,14 +4,18 @@
 
 针对阿里集团内部用户，请参考[mc_tutorial_inner](mc_tutorial_inner.md)。
 
+有技术问题可加钉钉群：37930014162
+
 ### 输入数据:
 
-输入一般是odps表:
+输入一般是MaxCompute表:
 
 - train: pai_online_project.dwd_avazu_ctr_deepmodel_train
-- test: pai_online_project.dwd_avazu_ctr_deepmodel_test
+- test:  pai_online_project.dwd_avazu_ctr_deepmodel_test
+
+说明：原则上这两张表是自己odps的表，为了方便，以上提供case的两张表可在国内用户的MaxCompute项目空间中访问。
 
-说明：原则上这两张表是自己odps的表，为了方便，以上提供case的两张表在任何地方都可以访问。两个表可以带分区，也可以不带分区。
+两个表可以带分区，也可以不带分区。带分区的方式：odps://xyz_project/table1/dt=20240101
 
 ### 训练:
 
@@ -24,34 +28,34 @@ pai -name easy_rec_ext -project algo_public
 -Dconfig=oss://easyrec/config/MultiTower/dwd_avazu_ctr_deepmodel_ext.config
 -Dtrain_tables='odps://pai_online_project/tables/dwd_avazu_ctr_deepmodel_train'
 -Deval_tables='odps://pai_online_project/tables/dwd_avazu_ctr_deepmodel_test'
--Dcluster='{"ps":{"count":1, "cpu":1000}, "worker" : {"count":3, "cpu":1000, "gpu":100, "memory":40000}}'
+-Dcluster='{"ps":{"count":1, "cpu":1000}, "worker" : {"count":3, "cpu":1000, "gpu":0, "memory":40000}}'
 -Deval_method=separate
 -Dmodel_dir=oss://easyrec/ckpt/MultiTower
 -Darn=acs:ram::xxx:role/xxx
 -Dbuckets=oss://easyrec/
 -DossHost=oss-cn-beijing-internal.aliyuncs.com;
 ```
 
-- -Dcmd: train 模型训练
+- -Dcmd: train 表示模型训练
 - -Dconfig: 训练用的配置文件
 - -Dtrain_tables: 定义训练表
-- -Deval_tables: 定义测试表
+- -Deval_tables: 定义评估表
 - -Dtables: 定义其他依赖表(可选)，如负采样的表
 - -Dcluster: 定义PS的数目和worker的数目。具体见：[PAI-TF任务参数介绍](https://help.aliyun.com/document_detail/154186.html?spm=a2c4g.11186623.4.3.e56f1adb7AJ9T5)
 - -Deval_method: 评估方法
-- separate: 用worker(task_id=1)做评估
+- separate: 用worker(task_id=1)做评估。找到MaxCompute训练任务的logview，打开logview之后在worker1机器的stderr日志中查看评估指标数据。
 - none: 不需要评估
 - master: 在master(task_id=0)上做评估
 - -Dfine_tune_checkpoint: 可选，从checkpoint restore参数，进行finetune
 - 可以指定directory，将使用directory里面的最新的checkpoint.
 - -Dmodel_dir: 如果指定了model_dir将会覆盖config里面的model_dir，一般在周期性调度的时候使用。
-- -Darn: rolearn  注意这个的arn要替换成客户自己的。可以从dataworks的设置中查看arn。
+- -Darn: rolearn  注意这个的arn要替换成客户自己的。可以从dataworks的设置中查看arn;或者阿里云控制台人工智能平台PAI，左侧菜单"开通和授权"，找到全部云产品依赖->Designer->OSS->查看授权信息。
 - -Dbuckets: config所在的bucket和保存模型的bucket; 如果有多个bucket，逗号分割
 - -DossHost: ossHost地址
 
 ### 注意：
 
-- dataworks和pai的project 一样，案例都是pai_online_project，用户需要根据自己的环境修改。如果需要使用gpu，PAI的project需要设置开通GPU。链接：[https://pai.data.aliyun.com/console?projectId=&regionId=cn-beijing#/visual](https://pai.data.aliyun.com/console?projectId=%C2%AEionId=cn-beijing#/visual)  ，其中regionId可能不一致。
+- dataworks和PAI的project一样，案例都是pai_online_project，用户需要根据自己的环境修改。如果需要使用gpu，PAI的project需要设置开通GPU。链接：[https://pai.data.aliyun.com/console?projectId=&regionId=cn-beijing#/visual](https://pai.data.aliyun.com/console?projectId=%C2%AEionId=cn-beijing#/visual)  ，其中regionId可能不一致。
 
   ![mc_gpu](../../images/quick_start/mc_gpu.png)
 
@@ -68,7 +72,7 @@ pai -name easy_rec_ext -project algo_public
 -Dcmd=evaluate
 -Dconfig=oss://easyrec/config/MultiTower/dwd_avazu_ctr_deepmodel_ext.config
 -Deval_tables='odps://pai_online_project/tables/dwd_avazu_ctr_deepmodel_test'
--Dcluster='{"worker" : {"count":1, "cpu":1000, "gpu":100, "memory":40000}}'
+-Dcluster='{"worker" : {"count":1, "cpu":1000, "gpu":0, "memory":40000}}'
 -Dmodel_dir=oss://easyrec/ckpt/MultiTower
 -Darn=acs:ram::xxx:role/xxx
 -Dbuckets=oss://easyrec/

docs/source/quick_start/mc_tutorial_inner.md

@@ -34,7 +34,7 @@ pai -name easy_rec_ext -project algo_public
 -Dconfig=oss://easyrec/config/MultiTower/dwd_avazu_ctr_deepmodel_ext.config
 -Dtrain_tables='odps://pai_online_project/tables/dwd_avazu_ctr_deepmodel_train'
 -Deval_tables='odps://pai_online_project/tables/dwd_avazu_ctr_deepmodel_test'
--Dcluster='{"ps":{"count":1, "cpu":1000}, "worker" : {"count":3, "cpu":1000, "gpu":100, "memory":40000}}'
+-Dcluster='{"ps":{"count":1, "cpu":1000}, "worker" : {"count":3, "cpu":1000, "gpu":0, "memory":40000}}'
 -Deval_method=separate
 -Dmodel_dir=oss://easyrec/ckpt/MultiTower
 -Dbuckets=oss://easyrec/?role_arn=acs:ram::xxx:role/xxx&host=oss-cn-beijing-internal.aliyuncs.com;