Skip to content

Commit

Permalink
refactor documents
Browse files Browse the repository at this point in the history
  • Loading branch information
@chengmengli06
chengmengli06 committed Sep 13, 2023
1 parent b8f4851 commit 879445b
Show file tree
Hide file tree
Showing 6 changed files with 79 additions and 249 deletions.
36 changes: 19 additions & 17 deletions docs/source/feature/fg_docs/IdFeature.md
View file
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,21 @@ 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 |

## 示例:

| 类型 | 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"
- ^C是FG encode之后输出的特征值的分隔符, 其ASCII编码是"\\x03"
39 changes: 2 additions & 37 deletions docs/source/feature/fg_docs/LookupFeature.md
View file
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: 15 additions & 29 deletions docs/source/feature/fg_docs/MatchFeature.md
View file
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,14 @@ 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。这种情况，用户也可以考虑使用lookup_feature。 假设各字段的值如下

| 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

允许用户 category 和 item 两个值为 ALL（注意，不是配置的值，是传入的值），进行 wildcard 匹配，可以匹配出多个值。输出结果类似于 hit。
- needDiscrete=true, 结果: brand_hit_ALL_30068_20
- needDiscrete=false, 结果: 20.0
30 changes: 15 additions & 15 deletions docs/source/feature/fg_docs/RawFeature.md
View file
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所依赖的字段来源 |
| 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

0 comments on commit 879445b

Please sign in to comment.