Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc]refactor documents #417

Merged
merged 3 commits into from
Jan 8, 2024
+86 −251
Merged

[doc]refactor documents #417

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
879445b
refactor documents
chengmengli06 Sep 12, 2023
18d9fc3
update fg docs according to comments
chengmengli06 Jan 5, 2024
c3df100
fix fg doc errors
chengmengli06 Jan 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 21 additions & 17 deletions docs/source/feature/fg_docs/IdFeature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## 功能介绍

id_feature是一个sparse feature，是一种最简单的离散特征，只是简单的将某个字段的值与用户配置的feature名字拼接。
id_feature表示离散特征, 包含单值离散特征和多值离散特征.

## 配置方法

Expand All @@ -14,19 +14,23 @@ id_feature是一个sparse feature，是一种最简单的离散特征，只是
}
```

| 字段名 | 含义 |
| -------------- | ----------------------------------------------------------------------------- |
| feature_name | 必选项，feature_name会被当做最终输出的feature的前缀 |
| expression | 必选项，expression描述该feature所依赖的字段来源 |
| need_prefix | 可选项，true表示会拼上feature_name作为前缀，false表示不拼，默认为true，通常在shared_embedding的场景会用false |
| invalid_values | 可选项，表示这些values都会被输出成null。list string，例如\[""\]，表示将所有的空字符串输出变成null。 |

例子 （ ^\]表示多值分隔符，注意这是一个符号，其ASCII编码是"\\x1D"，而不是两个符号）

| 类型 | item:is_main的取值 | 输出的feature |
| -------- | --------------- | ------------------------------------------- |
| int64_t | 100 | (item_is_main_100, 1) |
| double | 5.2 | (item_is_main_5, 1)（小数部分会被截取） |
| string | abc | (item_is_main_abc, 1) |
| 多值string | abc^\]bcd | (item_is_main_abc, 1),(item_is_main_bcd, 1) |
| 多值int | 123^\]456 | (item_is_main_123, 1),(item_is_main_456, 1) |
| 字段名 | 含义 |
| ------------ | ----------------------------------------------------------------------------- |
| feature_name | 必选项，feature_name会被当做最终输出的feature的前缀 |
| expression | 必选项，expression描述该feature所依赖的字段来源 |
| need_prefix | 可选项，true表示会拼上feature_name作为前缀，false表示不拼，默认为true，通常在shared_embedding的场景会用false |

## 示例:

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

下面以item侧的特征is_main作为案例来说明在不同类型下的原始值和输出值：

下面以item侧的特征is_main作为案例来说明在不同配置下特征的输入和输出:

| 类型 | item:is_main的取值 | 输出的feature |
| -------- | --------------- | ---------------------------------- |
| int64_t | 100 | item_is_main_100 |
| double | 5.2 | item_is_main_5（小数部分会被截取） |
| string | abc | item_is_main_abc |
| 多值string | abc^\]bcd | item_is_main_abc^Citem_is_main_bcd |
| 多值int | 123^\]456 | item_is_main_123^Citem_is_main_456 |

- ^\]表示多值分隔符，注意这是一个符号，其ASCII编码是"\\x1D", 也可以写作"\\u001d"
- ^C是FG encode之后输出的特征值的分隔符, 其ASCII编码是"\\x03"
39 changes: 2 additions & 37 deletions docs/source/feature/fg_docs/LookupFeature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,9 @@

## 功能介绍

如果离线生成不符合预期 请先使用最新的离线fg包
lookup_feature 和 match_feature类似，是从一组kv中匹配到自己需要的结果。lookup_feature 依赖 map 和 key 两个字段，map是一个多值string(MultiString)类型的字段，其中每一个string的样子如"k1:v2"。；key可以是一个任意类型的字段。生成特征时，先是取出key的值，将其转换成string类型，然后在map字段所持有的kv对中进行匹配，获取最终的特征。

lookup_feature 和 match_feature类似，是从一组kv中匹配到自己需要的结果。

lookup_feature 依赖 map 和 key 两个字段，map是一个多值string(MultiString)类型的字段，其中每一个string的样子如"k1:v2"。；key可以是一个任意类型的字段。生成特征时，先是取出key的值，将其转换成string类型，然后在map字段所持有的kv对中进行匹配，获取最终的特征。

map 和 key 源可以是 item，user，context 的任意组合。在线输入的时候item的多值用多值分隔符char(29)分隔，user和context的多值在tpp访问时用list表示。该特征仅支持json形式的配置方式。
map 和 key 源可以是 item, user, context 的任意组合。在线输入的时候item的多值用多值分隔符char(29)分隔，user和context的多值在tpp访问时用list表示。该特征仅支持json形式的配置方式。

## 配置方法

Expand Down Expand Up @@ -79,34 +75,3 @@ key:{"k1"}
```

如果存在多个 key 时，可以通过配置 combiner 来组合多个查到的值。可能的配置有 `sum, mean, max, min`。 ps：如果要使用combiner的话需要将needDiscrete设置为false，只有dense类才能做combiner，生成的value会是数值类的

一个配置样例 update on 2021.04.15

```json
"kv_fields_encode": [
{
"name": "cnty_dense_features",
"dimension": 99,
"min_hash_type": 0,
"use_sparse": true
},
{
"name": "cross_a_tag",
"dimension": 12,
"min_hash_type": 0,
"use_sparse": true
},
{
"name": "cross_gender",
"dimension": 12,
"min_hash_type": 0,
"use_sparse": true
},
{
"name": "cross_purchasing_power",
"dimension": 12,
"min_hash_type": 0,
"use_sparse": true
}
]
```
44 changes: 16 additions & 28 deletions docs/source/feature/fg_docs/MatchFeature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ match_feature本质是是一个两层map的匹配，user字段使用string的方

## 配置方式

json格式配置文件：
配置文件使用json格式

```json
{
Expand All @@ -37,34 +37,22 @@ json格式配置文件：
}
```

needDiscrete:true 时，模型使用 match_feature 输出的特征名，忽略特征值。默认为 true。
needDiscrete:false 时，模型取 match_feature 输出的特征值，而忽略特征名。

matchType：
hit:输出命中的feature

xml配置文件：

```xml
<features name="matched_features">
<feature name="brand_hit" dependencies="user:user_brand_tags_hit1,item:brand_id" category="item:auction_root_category" type="hit"/>
<feature name="brand_matched_hit" dependencies="user:user_brand_tags_cos1,item:brand_id" category="ALL" type="hit"/>
</features>
```

dependencie:需要做Match 的两个特征

category: 类目的feature 字段。category="ALL"不需要分类目匹配
- needDiscrete
- true: 模型使用 match_feature 输出的特征名，忽略特征值。默认为 true;
- false: 模型取 match_feature 输出的特征值，而忽略特征名.
- matchType：
- hit: 输出命中的feature
- multihit: 允许category和item字段的值为MATCH_WILDCARD选项, 即"ALL", 可以匹配出多个值

## Normalizer

match_feature 支持和 raw_feature 一样的 normalizer，具体可见 [raw_feature](./RawFeature.md)。

## 配置详解
## 配置示例

### hit

对于下面的配置
配置

```json
{
Expand All @@ -85,16 +73,16 @@ match_feature 支持和 raw_feature 一样的 normalizer，具体可见 [raw_fea
| brand_id | 30068 |
| auction_root_category | 50006842 |

如果 needDiscrete=true，结果为：\<brand_hit_50006842_30068_19，1.0>
如果 needDiscrete=false，结果为：\<brand_hit，19.0>
如果只需要使用一层匹配，则需要将上面配置里的 category 的值改为 ALL。这种情况，用户也可以考虑使用 lookup_feature。 假设各字段的值如下
- needDiscrete=true，结果为: brand_hit_50006842_30068_19
- needDiscrete=false，结果为: 19.0

如果只使用一层匹配，则需要将上面配置里的 category 的值改为 ALL。 假设各字段的值如下

| user_brand_tags_hit | ALL^16788816:40,10122:40,29889:20,30068:20 |
| ------------------- | ------------------------------------------ |
| brand_id | 30068 |

如果 needDiscrete=true，结果：\<brand_hit_ALL_30068_20, 1.0> 如果 needDiscrete=false，结果：\<brand_hit, 20.0>

### multihit
- needDiscrete=true, 结果: brand_hit_ALL_30068_20
- needDiscrete=false, 结果: 20.0

允许用户 category 和 item 两个值为 ALL（注意，不是配置的值，是传入的值），进行 wildcard 匹配，可以匹配出多个值。输出结果类似于 hit。
这种情况，用户也可以考虑使用lookup_feature, user_brand_tags_hit 里面的值的格式需要更改为: "16788816:40^\]10122:40^\]29889:20^\]30068:20", 注意: '^\]'是多值分隔符(\\u001d), 是一个不可见字符。
30 changes: 15 additions & 15 deletions docs/source/feature/fg_docs/RawFeature.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## 功能介绍

raw_feature是一种dense的feature，是直接引用原始feature的字段值作为feature的value。raw feature仅支持数值int、float、double等数值类型，对非数值类型的feature需使用id feature。
raw_feature表示连续值特征, 支持数值int、float、double等数值类型. 支持单值连续特征和多值连续特征.

## 配置方法

Expand All @@ -15,14 +15,14 @@ raw_feature是一种dense的feature，是直接引用原始feature的字段值
}
```

| 字段名 | 含义 |
| --------------- | ---------------------------------------------------------------------------------- |
| feature_name | 必选项，在正常使用时该选项是没用处的，因为实际参与接下来运算的主要是feature value，但是在debug的情况下，可以看到对应feature name的值。 |
| expression | 必选项，expression描述该feature所依赖的字段来源 |
| value_dimension | 可选项，默认值为1，表示输出的字段的维度。 |
| normalizer | 可选项，归一化方法，详见后文 |
| 字段名 | 含义 |
| --------------- | ------------------------------------------------------------ |
| feature_name | 必选项, 特征名 |
| expression | 必选项，expression描述该feature所依赖的字段来源, 来源必须是user、item、context中的一种 |
| value_dimension | 可选项，默认值为1，表示输出的字段的维度 |
| normalizer | 可选项，归一化方法，详见后文 |

## 例子
## 示例

^\]表示多值分隔符，注意这是一个符号，其ASCII编码是"\\x1D"，而不是两个符号

Expand All @@ -34,25 +34,25 @@ raw_feature是一种dense的feature，是直接引用原始feature的字段值

## Normalizer

raw_feature 和 match_feature 支持 normalizer，共三种，`minmax，zscore，log10`。配置和计算方法如下：
raw_feature 和 match_feature 支持 normalizer，共三种，`minmax，zscore，log10`. 配置和计算方法如下:

### log10

```
配置例子：method=log10,threshold=1e-10,default=-10
计算公式：x = x > threshold ? log10(x) : default;
配置例子: method=log10,threshold=1e-10,default=-10
计算公式: x = x > threshold ? log10(x) : default;
```

### zscore

```
配置例子：method=zscore,mean=0.0,standard_deviation=10.0
计算公式：x = (x - mean) / standard_deviation
配置例子: method=zscore,mean=0.0,standard_deviation=10.0
计算公式: x = (x - mean) / standard_deviation
```

### minmax

```
配置例子：method=minmax,min=2.1,max=2.2
计算公式：x = (x - min) / (max - min)
配置例子: method=minmax,min=2.1,max=2.2
计算公式: x = (x - min) / (max - min)
```
Loading
Loading