内置特征算子

功能介绍

id_feature表示离散特征，包含单值离散特征（如用户ID和物品ID特征）和多值离散特征（如商品的颜色特征，可以有多个取值）。

配置方法

{
  "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类型的特征值。支持批量计算和广播机制。

备注：使用该特征算子时，所有输入都必须能够转成double类型。

配置方法

{
  "feature_type" : "expr_feature",
  "feature_name" : "ctr_sigmoid",
  "expression" : "sigmoid(pv/(1+click))",
  "variables": ["item:pv", "item:click"]
}

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

配置示例

{
    "feature_name": "expr_feat",
    "feature_type": "expr_feature",
    "expression": "a+b",
    "variables": ["a", "b"],
    "value_dimension": 3
}

• 标量与向量的计算（广播机制）

  • 当变量a=1，变量b=[1, 2, 6]时，结果为[2, 3, 7]

• 向量与向量的element-wise计算

  • 当变量a=[3, 2, 1]，变量b=[1, 2, 6]时，结果为[4, 4, 7]

• 支持临时变量和逗号表达式

  • 例如：x=roundp(a),(a-x)*b；这个例子中x是临时变量，不需要配置在variables中

  • 逗号表达式会从左到右依次计算，最终返回最右边的子表达式的值

  • 在语义允许的情况下，尽量复用已有的变量作为临时变量，可减少内存开销

表达式特征与序列特征的结合

{
  "features": [
    {
      "feature_name": "sphere_distance",
      "feature_type": "expr_feature",
      "expression": "sphere_dist(click_id_lng,click_id_lat,j_lng,j_lat)",
      "variables": ["user:click_id_lng", "user:click_id_lat", "item:j_lng", "item:j_lat"],
      "default_value": "0",
      "value_dimension": 3,
      "stub_type": true
    },
    {
      "feature_name": "time_diff",
      "feature_type": "expr_feature",
      "variables": ["user:cur_time", "user:clk_time_seq"],
      "expression": "cur_time-clk_time_seq",
      "default_value": "0",
      "separator": ";",
      "value_dimension": 3,
      "stub_type": true
    },
    {
      "sequence_name": "click_seq",
      "sequence_length": 3,
      "sequence_delim": ";",
      "sequence_pk": "user:click_item",
      "features": [
        {
          "feature_name": "spherical_distance",
          "feature_type": "raw_feature",
          "expression": "feature:sphere_distance",
          "default_value": "0.0"
        },
        {
          "feature_name": "time_diff_seq",
          "feature_type": "id_feature",
          "expression": "feature:time_diff",
          "default_value": "0.0",
          "num_buckets": 10000
        }
      ]
    }
  ]
}

表达式

• 内置函数（scalar）

  函数名	参数数量	解释
  rnd	0	Generate a random number between 0 and 1
  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
  abs	1	absolute value
  rint	1	round to nearest integer
  round	1	四舍五入，总是使用"远离零"的舍入方式（round half away from zero）
  roundp	1	自定义精度取整函数, e.g. roundp(3.14159,2)=3.14
  floor	1	向下取整
  ceil	1	向上取整
  trunc	1	截断取整（直接去掉小数部分）
  sigmoid	1	sigmoid function
  sphere_dist	4	sphere distance between two gps points, args(lng1, lat1, lng2, lat2)
  haversine	4	haversine distance between two gps points, args(lng1, lat1, lng2, lat2)
  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

  备注：上述内置函数支持批量计算和广播机制

• 内置向量运算函数

  函数名	参数数量	解释
  len	1	the length of a vector
  l2_norm	1	l2 normalize of a vector
  squared_norm	1	squared normalize of a vector
  dot	2	dot product of two vectors
  euclid_dist	2	euclidean distance between two vectors
  corr	2	Pearson Correlation Coefficient of two vectors
  std_dev	1	standard deviation of a vector, divide n
  pop_std_dev	1	population standard deviation of a vector, divide n-1
  variance	1	sample variance of a vector, divide n
  pop_variance	1	population variance of a vector, divide n-1
  reduce_min	1	reduce min of a vector
  reduce_max	1	reduce max of a vector
  reduce_sum	1	reduce sum of a vector
  reduce_mean	1	reduce mean of a vector
  reduce_prod	1	reduce product of a vector

  备注：当表达式包含上述内置向量运算函数时，非向量函数参数的其他变量只能是单值类型(scalar)。

• 内置二元操作符

  操作符	描述	优先级
  =	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。例如在搜索场景中，计算搜索词（query）是否包含在商品标题（title）中。

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类型。

示例1

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

示例2

method=index_of，title为the cat sat on the mat。

功能介绍

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

配置方法

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

{
  "sequence_name": "click_50_seq",
  "sequence_length": 50,
  "sequence_delim": ";",
  "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_length：sequence的最大长度。

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

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

  • 在线推理服务（EAS Processor）的请求参数中需要包括以sequence_pk的值为key的特征

    • 例如：click_50_seq: 5410233389955966;1832586 (分隔符为sequence_delim配置的值)

      • 上面的例子中，click_50_seq特征的值是5410233389955966;1832586

  • item-side的sequence的子特征不需要在请求参数中传递给模型推理服务

    • 模型推理服务中会使用这个字段作为key去查询item的side info

    • 例如该配置中，序列特征中的item_id, price特征不需要请求传入给推理服务，而是在processor内部通过fg sdk 从processor的物品缓存中读取并拼接，保证和离线训练时的格式一致。

  • user-side的sequence的子特征需要在请求参数中传递给模型推理服务

    • 特征名为${sequence_name}__${feature_name}, 如：click_50_seq__ts

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

  • 离线任务中使用的FG输入表需要包含所有子特征对应的column，并且column的命名为${sequence_name}__${sub_feature_name}

    • 例如，该配置的例子中，离线表需要3个column：click_50_seq__item_id, click_50_seq__price, click_50_seq__ts

  • 离线表中column的类型建议为array类型（性能更佳），也支持用sequence_delim为元素分隔符的string类型

• 支持分箱操作，配置方法请参见特征分箱（离散化），配置了分箱时输出的元素类型为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"
  }
}

自定义序列特征

自定义序列特征算子的开发方法参考自定义特征算子。

{
  "features": [
    {
      "sequence_name": "click_seq",
      "sequence_length": 5,
      "sequence_delim": ";",
      "sequence_pk": "click_item",
      "features": [
        {
          "feature_name": "time_diff_seq",
          "feature_type": "custom_feature",
          "operator_name": "SeqExpr",
          "expression": ["user:cur_time", "user:clk_time_seq"],
          "formula": "click_seq__cur_time - click_seq__clk_time_seq",
          "default_value": "0",
          "value_type": "double",
          "num_buckets": 1000,
          "is_op_thread_safe": false
        },
        {
          "feature_name": "spherical_distance",
          "feature_type": "custom_feature",
          "operator_name": "SeqExpr",
          "expression": ["user:click_id_lng", "user:click_id_lat", "item:j_lng", "item:j_lat"],
          "formula": "spherical_distance",
          "default_value": "0",
          "value_type": "float",
          "is_op_thread_safe": true,
          "value_dimension": 1
        }
      ]
    }
  ]
}

注意，在这种嵌套的序列特征配置方式下，expression中的字段的实际字段名会加上前缀${sequence_name}__，如click_seq__cur_time。

• formula: 表达式，支持的表达式参考expr_feature。

  • spherical_distance: 计算两个经纬度坐标的距离，参数为[lng1_seq, lat1_seq, lng2, lat2]，前两个参数是序列，后两个参数是标量值。

备注：以上功能只为了演示自定义序列特征的用法，上述功能可使用内置的表达式特征+序列特征的组合实现，参考expr_feature。

功能介绍

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

分词词典格式参考：

1. https://github.com/huggingface/tokenizers

2. https://github.com/mlc-ai/tokenizers-cpp。

配置方法

{
    "feature_name": "title_token",
    "feature_type": "tokenize_feature",
    "expression": "item:title",
    "default_value": "",
    "vocab_file": "tokenizer.json",
    "tokenizer_type": "sentencepiece",
    "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。

示例

功能介绍

regex_replace_feature表示正则表达式替换特征, 将匹配上的子串替换为指定的子串。

配置方法

{
  "feature_name": "query",
  "feature_type": "regex_replace_feature",
  "expression": ["user:query"],
  "regex_patten": "\\|",
  "replacement": " ",
  "default_value": ""
}

• 支持分箱操作，配置方法请查看分箱操作：

  • hash_bucket_size: 对特征变换结果进行hash和取模

  • vocab_list: 根据词汇表分箱，把输入映射到词汇表的索引

  • vocab_dict: 分箱结果为特征值对应的vocab_dict字典的值

  • vocab_file: 从文件读入vocab_list或vocab_dict

• 支持array类型的多值输入

示例

功能介绍

通过布尔值过滤元素，类似tf.boolean_mask(tensor, mask)。

配置方法

{
  "feature_name": "mask_feature",
  "feature_type": "bool_mask_feature",
  "value_type": "float",
  "expression": [
    "user:click_items",
    "item:is_valid"
  ],
  "separator": ","
}

• 支持分箱操作，配置方法请查看文档特征分箱（离散化）

• 支持array类型的多值输入

示例

与表达式特征配合使用

{
  "features": [
    {
      "feature_name": "mask",
      "feature_type": "expr_feature",
      "expression": "price>100",
      "variables": ["item:price"],
      "value_dimension": 3
    },
    {
      "feature_name": "filter_list",
      "feature_type": "bool_mask_feature",
      "expression": [
        "user:click_items",
        "feature:mask"
      ],
      "num_buckets": 10000
    }
  ]
}