内置特征算子

功能介绍

id_feature表示离散特征，包含单值离散特征和多值离散特征。

配置方法

{
  "feature_type": "id_feature",
  "feature_name": "item_is_main",
  "expression": "item:is_main",
  "need_prefix": true,
  "separator": "\u001D",
  "default_value": ""
}

• 支持分箱操作，配置方法请参见特征分箱（离散化）。

• 支持array类型的多值输入。

示例

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

^]表示多值分隔符，这是一个符号，其ASCII编码是"\x1D"，也可以写作"\u001d"。

功能介绍

raw_feature表示连续值特征，支持数值int、float、double等数值类型. 支持单值连续特征和多值连续特征。

配置方法

{
 "feature_type" : "raw_feature",
 "feature_name" : "ctr",
 "expression" : "item:ctr",
 "normalizer" : "method=log10"
}

• 支持分箱操作，配置方法请参见特征分箱（离散化）。

• 支持array类型的多值输入。

示例

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

Normalizer

raw_feature和match_feature支持normalizer，共四种，minmax、zscore、log10、expression配置和计算方法如下：

• minmax

  配置例子：method=minmax,min=2.1,max=2.2

  计算公式：x = (x - min) / (max - min)

• zscore

  配置例子：method=zscore,mean=0.0,standard_deviation=10.0

  计算公式：x = (x - mean) / standard_deviation

• log10

  配置例子：method=log10,threshold=1e-10,default=-10

  计算公式：x = x > threshold ? log10(x) : default;

• expression

  配置例子：method=expression,expr=sign(x)

  计算公式：可以配置任意的函数或表达式，变量名固定为x，代表表达式的输入。

功能介绍

expr_feature表示表达式特征，用来对表达式求值，可以输出float类型的特征值。

配置方法

示例

当pv=2,click=3时，上述表达式特征值为：0.6224593312

表达式

• 内置函数

  函数名	参数数量	解释
  sin	1	sine function
  cos	1	cosine function
  tan	1	tangens function
  asin	1	arcus sine function
  acos	1	arcus cosine function
  atan	1	arcus tangens function
  sinh	1	hyperbolic sine function
  cosh	1	hyperbolic cosine
  tanh	1	hyperbolic tangens function
  asinh	1	hyperbolic arcus sine function
  acosh	1	hyperbolic arcus tangens function
  atanh	1	hyperbolic arcur tangens function
  log2	1	logarithm to the base 2
  log10	1	logarithm to the base 10
  log	1	logarithm to base e (2.71828...)
  ln	1	logarithm to base e (2.71828...)
  exp	1	e raised to the power of x
  sqrt	1	square root of a value
  sign	1	sign function -1 if x<0; 1 if x>0
  rint	1	round to nearest integer
  abs	1	absolute value
  sigmoid	1	sigmoid function
  l2_norm	1	l2 normalize of a vector
  dot	2	dot product of two vectors
  euclid_dist	2	euclidean distance between two vectors
  min	var.	min of all arguments
  max	var.	max of all arguments
  sum	var.	sum of all arguments
  avg	var.	mean value of all arguments

• 内置二元操作符

  操作符	描述	优先级
  =	assignement *	0
  ||	logical or	1
  &&	logical and	2
  |	bitwise or	3
  &	bitwise and	4
  <=	less or equal	5
  >=	greater or equal	5
  !=	not equal	5
  ==	equal	5
  >	greater than	5
  <	less than	5
  +	addition	6
  -	subtraction	6
  *	multiplication	7
  /	division	7
  ^	raise x to the power of y	8

  The assignment operator is special since it changes one of its arguments and can only by applied to variables.

• 内置三元操作符

  支持 if-else 语法

  It uses lazy evaluation in order to make sure only the necessary branch of the expression is evaluated.

  操作符	描述	优先级
  ?:	if then else operator	C++ style syntax

• 内置常量

  操作符	描述	优先级
  _pi	The one and only pi.	3.141592653589793238462643
  _e	Euler's number.	2.718281828459045235360287

功能介绍

combo_feature是多个字段（或表达式）的组合（即笛卡尔积），id_feature可以看成是一种特殊的combo_feature，即参与交叉字段只有一个的combo_feature。一般来讲，参与交叉的各个字段来自不同的表（比如user特征和item特征进行交叉）。

配置方法

{
  "feature_type" : "combo_feature",
  "feature_name" : "comb_age_item",
  "expression" : ["user:age_class", "item:item_id"],
  "need_prefix": true,
  "separator": "\u001D",
  "default_value": ""
}

• 支持分箱操作，配置方法请参见特征分箱（离散化）。

• 支持array类型的多值输入。

示例

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

输出的feature个数等于：

|F1| * |F2| * ... * |Fn|

其中Fn指依赖的第n个字段的值的个数。

功能介绍

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

lookup_feature依赖map和key两个字段：

• map是一个字典类型；或者是多值string(MultiString)类型的字段，其中每一个string的样子如"k1:v2"。

• key可以是一个任意类型的字段。有多个key时推荐使用array类型的输入；生成特征时，先是取出key的值，将其转换成map的健值类型，然后在map字段所持有的kv对中进行匹配，获取最终的特征。

配置方法

{
  "feature_type": "lookup_feature",
  "feature_name": "item_match_item",
  "map": "item:item_attr",
  "key": "item:item_value",
  "need_discrete": true,
  "need_key": true
}

• 支持分箱操作，配置方法请参见特征分箱（离散化）。

• 字典支持map类型的输入，key支持array类型的输入。

示例

对于上面的配置，假设对于某个 doc：

item_attr : "k1:v1^]k2:v2^]k3:v3"

^]表示多值分隔符，这是一个符号，其ASCII编码是"\x1D"，而不是两个符号。该字符在emacs中的输入方式是C-q C-5，在vi中的输入方式是C-v C-5。这里item_attr是个多值string。

当map用来表征多个kv对时，是个多值string，而不是string。

item_value : "k2"

特征变换结果为"item_match_item_k2_v2"。

feature_name: fg
map: {"k1:123", "k2:234", "k3:3"}
key: {"k1"}
结果：feature={"fg_123"}

map: {"k1:123", "k2:234", "k3:3"}
key: {"k1"}
结果：feature={123}

合并查询结果

如果存在多个key时，可以通过配置combiner来组合多个查到的值。可能的配置有sum、mean、max、min。

如果要使用combiner的话需要将need_discrete设置为false，这种情况下value必须是数值型，或者是能够转换为数值的字符串。

功能介绍

match_feature一般用来做特征之间的匹配关系，本质是一个两层map的匹配。

配置方法

配置文件使用JSON格式。

{
  "feature_name": "user__l1_ctr_1",
  "feature_type": "match_feature",
  "category": "ALL",
  "need_discrete": false,
  "item": "item:category_level1",
  "user": "user:l1_ctr_1",
  "match_type": "hit"
}

• user：一个嵌套的字典（nested_dict），即dict of dict。

  • user字段使用string的方式描述了一个两层map。

  • |为第一层map的item之间的分隔符，^为第一层map的key与value之间的分隔符。

  • ,为第二层map的item之间的分隔符，:第二层map的key与value之间的分隔符。

• category：primary key，即查询第一层map的key值

  ALL为通配符，表示这一层所有的key值都能够匹配上。

• item：secondary key，即查询第二层map的key值

  ALL为通配符，表示这一层所有的key值都能够匹配上。

• need_discrete

  • true：模型使用match_feature输出的特征名，忽略特征值。默认为false。

  • false：模型取match_feature输出的特征值，而忽略特征名。

• match_type

  • hit：输出命中的feature；用category的值在第一层map中查找，然后使用item的值在第二层map中查找，最终得到一个结果。如果不需要使用两层匹配，只需要一层匹配，则可以在map的第一层key中填入ALL，然后在fg配置的category一项中也填成"ALL"即可。

  • multihit：允许category和item字段的值为MATCH_WILDCARD选项，即"ALL"，可以匹配出多个值。

• normalizer

  可选项，归一化方法，与raw_feature的同名配置含义相同，只有在need_discreate=false时才生效。

• show_category

  是否需要在查询结果中拼上category前缀，当need_discrete=true并且match_type=hit时默认为true，否则默认为false。

• show_item

  是否需要在查询结果中拼上item前缀，当need_discrete=true并且match_type=hit时默认为true，否则默认为false。

• value_type

  可选项，指定输出特征的类型，默认为string。

• separator

  可选项，指定string类型的key字段的多值分隔符，默认为 "\u001D"，只能是单个符号。

• default_value

  可选项，输入特征为空时，用默认值代替。

• value_dimension

  可选项，默认值为0，可以在离线任务中用来截断输出；值为1时输出表的schema类型为value_type，否则为array<value_type>。

• stub_type

  可选项，默认值为false，当值为true时，当前配置的特征变换仅用作pipeline的中间结果，最终不会输出（给模型）。

示例

{
  "50011740": {
    "50011740": 0.2,
    "36806676": 0.3,
    "122572685": 0.5
  },
  "50006842": {
    "16788": 0.1
  }
}

{
  "feature_name": "brand_hit",
  "feature_type": "match_feature",
  "category": "item:auction_root_category",
  "need_discrete": true,
  "item": "item:brand_id",
  "user": "user:user_brand_tags_hit",
  "matchType": "hit"
}

功能介绍

用来输出一些字符串字词匹配信息的feature。

Term Proximity Measures特征的计算方法参考论文《An Exploration of Proximity Measures in Information Retrieval》。

假设title(document)的term序列为：t1,t2,t1,t3,t5,t4,t2,t3,t4

• MinCover is defined as the length of the shortest document segment that covers each query term at least once in a document.

• MinDist(Minimum pair distance)：计算所有pair的最小距离的最小值。比如Q=t1,t2,t3，则MinDist=min(1,2,3)=1。

• MaxDist(Maximum pair distance)：与 MinDist 正好相反，它是求最大值。比如Q=t1,t2,t3，则MaxDist=max(1,2,3)=3。

• AveDist(Average pair distance)：计算所有pair的最小距离的平均值，比如Q=t1,t2,t3，则AveDist=(1+2+3)/3=2 AveDist=(1+2+3)/3=2。

请注意，所有聚合操作符（MinDist、MaxDist、AveDist）都是基于匹配查询词之间的成对距离来定义的。当文档仅匹配一个查询词时，MinDist、AveDist 和 MaxDist 均被定义为文档的长度。

配置方法

{
  "feature_type" : "overlap_feature",
  "feature_name" : "is_contain",
  "query" : "user:attr1",
  "title" : "item:attr2",
  "method" : "is_contain",
  "separator" : " ",
  "normalizer" : ""
}

overlap feature 的输出为float类型。

示例

query为"high,high2,fiberglass,abc"，title为"high,quality,fiberglass,tube,for,golf,bag"。

功能介绍

⽤户的历史⾏为也是⼀个很重要的feature。历史⾏为通常是⼀个序列，例如点击序列、购买序列等，组成这个序列的实体可能是物品本身，也可能是物品的属性。

配置方法

例如需要对⽤户的点击序列进⾏fg，序列⻓度为50，每个序列提取item_id、price和ts特征，其中ts=请求时间（request_time）-用户行为时间（event_time）。配置如下：

{
  "sequence_name": "click_50_seq",
  "sequence_column": "click_50_seq",
  "sequence_length": 10,
  "sequence_delim": ";",
  "attribute_delim": "#",
  "sequence_table": "item",
  "sequence_pk": "user: click_50_seq",
  "features": [
    {
        "feature_name": "item_id",
        "feature_type": "id_feature",
        "value_type": "String",
        "expression": "item: item_id"
    },
    {
        "feature_name": "price",
        "feature_type": "raw_feature",
        "expression": "item: price"
    },
    {
        "feature_name": "ts",
        "feature_type": "raw_feature",
        "expression": "user: ts"
    }
  ]
}

• sequence_name：sequence名称。

• sequence_column：sequence输出名称。

• sequence_length：sequence的最大长度。

• sequence_delim：sequence元素之间的分隔符。

• attribute_delim：sequence元素内部各个属性之间的分隔符，仅离线需要。

• sequence_pk：sequence primary key，主键，如user:click_50_seq，里面保存了user点击的最近的50个itemId，模型推理服务中会使用这个字段作为key去查询side info。

• features：sequence的sideinfo，包含item的静态属性值和行为时间信息等。

• 支持分箱操作，配置方法请参见特征分箱（离散化），配置了分箱时输出的元素类型为int64，shape由下面的value_dimension配置决定。

• value_dimension：Sequence的每个元素的维度，对于sequence_raw_feature来说配置为1时输出的类型为array<float>，配置为其它值时输出的类型为array<array<float>>；对于sequence_id_feature来说配置为1时输出的类型为array<string>，配置为其它值时输出的类型为array<array<string>>。默认值为0。

平铺形式的配置

{
  "feature_name": "clk_seq__item_id",
  "feature_type": "sequence_id_feature",
  "sequence_name": "clk_seq",
  "sequence_length": 50,
  "sequence_delim": ";",
  "expression": "item:clk_item_seq",
  "separator": "\u001D",
  "default_value": ""
},
{
  "feature_name": "clk_seq__item_price",
  "feature_type": "sequence_raw_feature",
  "sequence_name": "clk_seq",
  "sequence_length": 50,
  "sequence_delim": ";",
  "expression": "item:clk_item_prices",
  "separator": "\u001D",
  "default_value": "0"
}

这种配置方式在线Processor不会查询sideinfo，需要用户提供完整的输入。

输入字段clk_item_seq、clk_item_prices本身需要是一个Sequence序列，可以是array类型；也可以是字符串类型，由sequence_delim配置的字符分隔元素值。

可选配置：

• 支持分箱操作，配置方法请参见特征分箱（离散化），配置了分箱时输出的元素类型为int64，shape由下面的value_dimension配置决定

• value_dimension：Sequence的每个元素的维度，对于sequence_raw_feature来说配置为1时输出的类型为array<float>，配置为其它值时输出的类型为array<array<float>>；对于sequence_id_feature来说配置为1时输出的类型为array<string>，配置为其它值时输出的类型为array<array<string>>。默认值为0。

在线FG

⽀持两种⽅式获取⾏为sideinfo信息，⼀种是从EasyRec Processor的item cache获取sideinfo信息，以sequence_pk配置的字段为主键，从item cache中查找item的属性信息；另⼀种⽤户在请求中填充对应的字段值，如上述配置中的"ts"字段，其含义是（request_time - event_time），即推荐请求时间-用户行为时间，这个是随请求时间变化的，因此需要从请求中获取：

user_features {
  key: "click_50_seq"
  value {
    string_feature: "9008721;34926279;22487529;73379;840804;911247;31999202;7421440;4911004;40866551"
  }
}

user_features {
  key: "click__ts"
  value {
    string_feature: "23;113;401363;401369;401375;401405;486678;486803;486922;486969"
  }
}

功能介绍

tokenize_feature是对输入字符串分词，返回分词字符串或者分词之后的词id。支持tokenize-cpp的分词词典文件（tokenizer.json）。

配置方法

{
    "feature_name": "title_token",
    "feature_type": "tokenize_feature",
    "expression": "item:title",
    "default_value": "",
    "vocab_file": "tokenizer.json",
    "tokenizer_type": "bpe",
    "output_type": "word_id",
    "output_delim": ","
}

示例

output_type=word_id，输入一个字符串，当输出是词id，用逗号分隔组合为字符串。

功能介绍

文本归一化，功能包括：大小写转换、简繁体归一、全半角归一、特殊符号过滤、GBK/UTF8编码转换、汉字字符拆分等。

配置方法

{
    "feature_name": "txt_norm",
    "feature_type": "text_normalizer",
    "expression": "item:title",
    "stop_char_file": "stop_char.txt",
    "max_length": 256,
    "parameter": 0,
    "remove_space": false,
    "is_gbk_input": false,
    "is_gbk_output": false
}

备注：

• stop_char_file文件必须使用GBK编码。

• stop_char_file文件内每行只能有一个字符，否则会过滤失败。

文本归一化选项

parameter参数从下面的数字中选择一个，或者多个进行求和。

例如，需要的功能为：大写转换成小写、全角到半角、繁体到简体、去特殊符号；则parameter=4+8+16+32=60

parameter参数的默认值就是60。

#define __NORMALIZED_LOWER2UPPER__ 		2 			/*小写转换成大写*/
#define __NORMALIZED_UPPER2LOWER__ 		4 			/*大写转换成小写*/
#define __NORMALIZED_SBC2DBC__ 			8 			/*全角到半角*/
#define __NORMALIZED_BIG52GBK__			16 			/*繁体到简体*/
#define __NORMALIZED_FILTER__ 			32 			/*去特殊符号*/
#define __NORMALIZED_SYNONYMS__			64 			/*同义词归一(暂未实现)*/
#define __NORMALIZED_SORTQUERY__		128 		/*query重排序(暂未实现)*/
#define __NORMALIZED_SPELLCHECK__		256 		/*query的智能纠错 (暂未实现)*/
#define __NORMALIZED_SPLITCHARS__		512 		/*汉字拆成单字（空格分隔）*/

示例

{
  "feature_name": "txt_norm",
  "feature_type": "text_normalizer",
  "expression": "input_a",
  "parameter": 28
}

• inputs=["正則生成代碼", "Html過濾工具", "正則表達式語法速查", "The Cat／"]

• outputs=["正则生成代码", "html过滤工具", "正则表达式语法速查", "the cat/"]

功能介绍

BM25（Best Matching）算法是当前信息检索领域主流的文本匹配算法，通常用来作为搜索相关性评分。即对Query进行语素解析，生成语素qi；然后，对于每个搜索结果D，计算每个语素qi与D的相关性得分；最后，将qi相对于D的相关性得分进行加权求和，从而得到Query与D的相关性得分。

对中文而言，可以把对Query的分词作为语素分析，把每个词（term）看成语素qi。

BM25算法的一般性公式如下：

其中，Q表示某个query，qi表示query中的第i个term，d表示某个文档，wi表示qi的权重，R(qi,d)表示qi与文档d的相关性得分。

Term 重要度

判断一个词与一个文档的相关性的权重，方法有多种，较常用的是IDF。这里以IDF为例，公式如下：

其中，N表示语料库中的文档总数，n(qi)表示语料库中包含qi的文档总数。

根据IDF的定义可以看出，对于给定的文档集合，包含了qi的文档数越多，qi的权重则越低。也就是说，当很多文档都包含了qi时，qi的区分度就不高，因此使用qi来判断相关性时的重要度就较低。

Term 相关性

再来看termqi与文档d的相关性得分R(qi,d)。首先来看BM25中相关性得分的一般形式：

其中，k1、k2、b为调节因子，通常根据经验设置，一般k1=1.2，b=0.75；fi为qi在d中的出现频率，qfi为qi在Query中的出现频率。dl为文档d的长度，avgdl为所有文档的平均长度。由于绝大部分情况下，qi在query中只会出现一次，即qfi=1，因此公式可以简化为：

从K的定义中可以看到，参数b的作用是调整文档长度对相关性影响的大小。b越大，文档长度的对相关性得分的影响越大，反之越小。而文档的相对长度越长，K值将越大，则相关性得分会越小。可以理解为，当文档较长时，包含qi的机会越大，因此，同等fi的情况下，长文档与qi的相关性应该比短文档与qi相关性弱。

综上，BM25算法的相关性得分公式可总结为：

从BM25的公式可以看到，通过使用不同的分词方法、词权重判定方法，以及词与文档的相关性判定方法，可以衍生出不同的搜索相关性得分计算方法，为设计算法提供了较大的灵活性。

配置方法

{
  "feature_type": "bm25_feature",
  "feature_name": "query_doc_relevance",
  "query": "user:query",
  "document": "item:title",
  "term_doc_freq_file": "term_doc_freq.txt",
  "avg_doc_length": 100.0,
  "k1": 1.2,
  "b": 0.75,
  "separator": "\u001D",
  "default_value": ""
}

• term_doc_freq_file和term_doc_freq_dict二选一，优先使用前者，当两者都配置时，使用前者。

• 在线服务中使用该特征时，term_doc_freq_file文件与fg.json放在同一个目录下。

功能介绍

计算两个key-value索引的向量的点积，或两个集合的交集的大小。

配置方法

{
  "feature_type": "kv_dot_product",
  "feature_name": "query_doc_sim",
  "query": "user:query",
  "document": "item:title",
  "separator": "|",
  "default_value": "0"
}

• 支持复杂类型输入（array，map），推荐优先使用复杂类型。

• 当输入没有value部分时，默认value为1.0；可以利用此性质求两个集合的交集大小。

• 如果不配置default_value，则默认值强制设定为0。

示例