内置特征算子

功能介绍

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、int32、int64）。支持批量计算和广播机制。

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

配置方法

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

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

配置示例

{
    "feature_name": "expr_feat",
    "feature_type": "expr_feature",
    "value_type": "float",
    "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
  isnan	1	return 1.0 if input is NaN, elsewise 0.0 （需要1.0.5版本以上）
  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
  mod	2	取余数
  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
  %	modulo	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"，而不是两个符号

输出个数等于：

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

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

功能介绍

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

lookup_feature依赖map和key两个字段：

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

• 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，vim中的输入方式是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之间的分隔符。

  • 支持第一层的字典直接用map类型的输入，即支持Map<K, string>类型的输入，其中K可以是string,int32,int64类型，value是用string表示的内层dict，分隔符同上

• 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时仅作中间结果,不输出给模型。

示例

{
  "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"
}

功能介绍

输出字符串词匹配信息。例如在搜索场景中，计算搜索词（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。

请注意，所有聚合操作符（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。历史行为通常是一个序列，例如点击序列、购买序列等，组成这个序列的实体可能是物品本身，也可能是物品的属性。

配置方法

例如需要对用户的点击序列进行处理，序列长度为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"
    },
    {
      "feature_name": "time_diff_seq",
      "feature_type": "custom_feature",
      "operator_name": "SeqExpr",
      "operator_lib_file": "3rdparty/lib64/libseq_expr.so",
      "expression": ["user:cur_time", "user:clk_time_seq"],
      "formula": "cur_time - clk_time_seq",
      "sequence_fields": ["clk_time_seq"],
      "default_value": "0",
      "value_type": "double",
      "is_op_thread_safe": false,
      "value_dimension": 1
    }
  ]
}

• 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}__${input_name}, 如：click_50_seq__ts

    • ${input_name}一般用expression配置项来配置，但不同的子特征类型可能会不同；${input_name}不包含输入域前缀（item: or user:）

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

  • sequence_fields：指定输入序列的字段名，值是string或者[string]数组

    • 当特征算子只有一个输入字段时，该字段的内容必须是一个序列；此时可以不用配置sequence_fields

    • 当特征算子有多个输入字段时，如果不配置sequence_fields，则假设所有item侧的特征（item:XXX）是序列输入字段

  • 离线任务中使用的FG输入表需要包含所有子特征对应的column，

    • 当column是一个序列时（参考sequence_fields的规则），命名为${sequence_name}__${input_name}

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

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

    • 当column不是一个序列时，命名为${input_name}，无需加前缀

      • 例如，此配置的例子中，离线表需要1个非序列column：${cur_time}

    • 可以通过全局配置input_alias，为长的column名称设置一个更短的别名（参考下面的示例）

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

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

任意特征都可以配置为序列子特征，示例如下：

{
  "features": [
    {
      "sequence_name": "common_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",
          "value_dimension": 1
        },
        {
          "feature_name": "price",
          "feature_type": "raw_feature",
          "expression": "item:price"
        },
        {
          "feature_name": "ts",
          "feature_type": "raw_feature",
          "expression": "user:ts"
        },
        {
          "feature_name": "expr_feat",
          "feature_type": "expr_feature",
          "expression": "a > b",
          "variables": ["item:a", "item:b"],
          "sequence_fields": "a",
          "default_value": "0",
          "value_dimension": 1
        },
        {
          "feature_name": "lookup_feat",
          "feature_type": "lookup_feature",
          "map": "user:dict",
          "key": "item:prop",
          "separator": ",",
          "default_value": "0",
          "value_type": "float",
          "combiner": "sum",
          "boundaries": [0.0, 0.15, 0.5]
        },
        {
          "feature_name": "match_feat",
          "feature_type": "match_feature",
          "user": "user:nested_dict",
          "category": "item:pkey",
          "item": "item:skey",
          "separator": "\u001D",
          "default_value": "0",
          "matchType": "hit",
          "value_type": "float",
          "value_dimension": 1
        },
        {
          "feature_name": "bm25_score",
          "feature_type": "bm25_feature",
          "separator": " ",
          "default_value": "0",
          "query": "user:query",
          "document": "item:document",
          "sequence_fields": "query",
          "document_number": 100,
          "avg_doc_length": 6,
          "term_doc_freq_dict": {
            "this": 30,
            "example": 10,
            "document": 15
          }
        },
        {
          "feature_name": "overlap_feat",
          "feature_type": "overlap_feature",
          "query": "user:query2",
          "title": "item:title2",
          "sequence_fields": "query2",
          "method": "index_of",
          "separator": " ",
          "default_value": "-1"
        },
        {
          "feature_type": "kv_dot_product",
          "feature_name": "query_doc_sim",
          "query": "user:query3",
          "document": "item:title",
          "sequence_fields": "query3",
          "separator": "|",
          "default_value": "0"
        },
        {
          "feature_name": "seg_feat",
          "feature_type": "tokenize_feature",
          "expression": "input_a",
          "default_value": "0",
          "output_type": "word",
          "tokenizer_type": "sentencepiece",
          "vocab_file": "spmodel.model"
        },
        {
          "feature_name": "txt_norm",
          "feature_type": "text_normalizer",
          "expression": "input",
          "default_value": "<oov>",
          "parameter": 28
        },
        {
          "feature_name": "seq_combo_feat",
          "feature_type": "combo_feature",
          "expression": ["user:tags", "item:cat"],
          "sequence_fields": ["tags"],
          "separator": "_",
          "default_value": "0",
          "value_dimension": 1
        },
        {
          "feature_name": "norm_str",
          "feature_type": "str_replace_feature",
          "expression": ["user:profile"],
          "default_value": "",
          "replace_file": "synonyms.txt",
          "replacements": {
            "|": "",
            "aa": "x",
            "a": "X"
          },
          "value_dimension": 1
        },
        {
          "feature_name": "query_tokens",
          "feature_type": "regex_replace_feature",
          "expression": ["user:query_tokens"],
          "default_value": "",
          "value_type": "string",
          "regex_pattern": [ "\\|", "#", "\\(.*\\)" ],
          "replacement": "",
          "value_dimension": 1
        },
        {
          "feature_name": "slice",
          "feature_type": "slice_feature",
          "value_type": "int32",
          "expression": ["context:array"],
          "slice": "0:3",
          "value_dimension": 3,
          "num_buckets": 100000
        },
        {
          "feature_name": "mask_feature",
          "feature_type": "bool_mask_feature",
          "value_type": "float",
          "expression": [
            "user:click_items",
            "item:is_valid"
          ]
        },
        {
          "feature_name": "time_diff_seq",
          "feature_type": "custom_feature",
          "operator_name": "SeqExpr",
          "operator_lib_file": "3rdparty/lib64/libseq_expr.so",
          "expression": ["user:cur_time", "user:clk_time_seq"],
          "formula": "cur_time - clk_time_seq",
          "sequence_fields": ["clk_time_seq"],
          "default_value": "0",
          "value_type": "double",
          "is_op_thread_safe": false,
          "value_dimension": 1
        }
      ]
    }
  ],
  "input_alias": {
    "common_seq__clk_time_seq": "clk_time_seq"
  }
}

备注：input_alias 配置输入字段的别名，格式为"origin_field": "alias_field"，可以用一个短一点的名字来代替原来的输入字段名。

平铺形式的配置

一般情况下，只需要把非序列特征类型（feature_type）加上sequence_前缀就得到序列版本。注意，序列版本的特征一般情况下是必须要配置default_value的。

例如：

• sequence_id_feature：输出值类型固定为string类型，如需其他类型建议用slice_feature代替

• sequence_raw_feature：输出值类型固定为float类型，如需其他类型建议用slice_feature代替

• sequence_match_feature

• sequence_lookup_feature

• sequence_expr_feature

• sequence_combo_feature

• sequence_overlap_feature

• sequence_bm25_feature

• sequence_kv_dot_product

• sequence_text_normalizer

• sequence_tokenize_feature

• sequence_combine_feature

特殊情况1：有一些特征变换类型本身既有序列的版本，也有非序列的版本。

这个时候通过配置 is_sequence: true/false来激活对应的版本；

此时，feature_type配置项不需要加sequence_前缀。

例如：

• str_replace_feature

• regex_replace_feature

• custom_feature

特殊情况2：有一些特征变换类型本身只有序列的版本，没有非序列的版本。

此时，feature_type配置项不需要加sequence_前缀。

例如：

• slice_feature

• bool_mask_feature

这两种特殊情况都可以增加如下可选配置：

• sequence_length: sequence的最大长度，超出部分会被截断；默认值为-1，表示不做截断

• sequence_delim: sequence元素之间的分隔符，默认值为;

配置示例：

{
  "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"
},
{
  "feature_name": "test",
  "feature_type": "sequence_lookup_feature",
  "map": "user:prefer_tags",
  "key": "item:tags",
  "sequence_length": 2,
  "separator": ",",
  "default_value": "-1024",
  "value_type": "int32",
  "normalizer": "method=expression,expr=x+1",
  "combiner": "sum",
  "default_bucketize_value": 50,
  "num_buckets": 10000
},
{
  "feature_name": "test",
  "feature_type": "sequence_combo_feature",
  "separator": "_",
  "default_value": "0",
  "expression": ["user:f1", "item:f2"],
  "hash_bucket_size": 10000
}

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

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

• 平铺形式的序列特征输入字段名保持与配置相同，不会增加${sequence_name}__前缀。

在线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"
  }
}

功能介绍

combine_feature用于对输入特征的多个值进行合并操作，通过指定的合并策略（combiner）将多个值聚合为一个唯一值。

序列版本sequence_combine_feature 用于对序列特征中的每个元素的多个值合并，它将多值序列转换为单值序列。

核心能力

• 多值合并 ：将序列中每个元素的多个值合并为单个值

• 灵活的合并策略 ：支持 sum、mean、max、min、count 等多种合并方式

• 值映射功能 ：支持字符串到数值的映射字典，适用于行为事件序列等场景

• 双分隔符支持 ：支持序列分隔符和多值分隔符的配置

配置方法

基础配置（数值合并）

{
  "feature_name": "combine_feat",
  "feature_type": "combine_feature",
  "expression": "user:behavior_seq",
  "combiner": "sum",
  "separator": "|"
}

序列版本有两种配置方法（任选一种即可）：

• feature_type 配置为 sequence_combine_feature

• 添加配置项 "is_sequence": true

{
  "feature_name": "seq_combine_feat",
  "feature_type": "sequence_combine_feature",
  "expression": "user:behavior_seq",
  "combiner": "sum",
  "separator": "|",
  "sequence_delim": ";"
}

或者：

{
  "feature_name": "seq_combine_feat",
  "feature_type": "combine_feature",
  "expression": "user:behavior_seq",
  "combiner": "sum",
  "is_sequence": true,
  "separator": "|",
  "sequence_delim": ";"
}

带值映射的配置（行为事件）

{
  "feature_name": "behavior_score",
  "feature_type": "sequence_combine_feature",
  "expression": "user:action_events",
  "combiner": "sum",
  "separator": "|",
  "sequence_delim": ";",
  "value_map": {
    "expo": 1,
    "click": 2,
    "buy": 4
  }
}

先执行值映射，再执行合并操作。

配置字段说明

示例

示例 1：基础数值合并（Sum）

配置：

{
  "feature_name": "score_sum",
  "feature_type": "sequence_combine_feature",
  "expression": "user:scores",
  "combiner": "sum",
  "separator": ",",
  "sequence_delim": ";"
}

输入输出：

示例 2：行为事件序列（带 Value Map）

配置：

{
  "feature_name": "behavior_weight",
  "feature_type": "sequence_combine_feature",
  "expression": "user:actions",
  "combiner": "sum",
  "separator": "|",
  "sequence_delim": ";",
  "value_map": {
    "expo": 1,
    "click": 2,
    "buy": 4
  }
}

输入输出：

功能介绍

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_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进行语素解析，生成语素$$q_i$$；然后，对于每个搜索结果D，计算每个语素$$q_i$$与D的相关性得分；最后，将$$q_i$$相对于D的相关性得分进行加权求和，从而得到Query与D的相关性得分。

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

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

$$score(Q,d)=\sum _{i=1}^n{w}_{i}R(q_i,d)$$

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

Term 重要度

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

$$IDF(q_i)=log\frac{N-n(q_i)+0.5}{n(q_i)+0.5}$$

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

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

Term 相关性

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

$$R(q_i,d)=\frac{f_i\cdot (k_1+1)}{f_i+K}\cdot \frac{q{f}_i\cdot (k_2+1)}{q{f}_i+k_2}$$

$$K=k_1\cdot \left(1-b+b\cdot \frac{dl}{avgdl}\right)$$

其中，$$k_1,k_2,b$$为调节因子，通常根据经验设置，一般$$k_1=1.2,b=0.75,k_2=0$$；$$f_i$$为$$q_i$$在$$d$$中的出现频率，$$q{f}_i$$为$$q_i$$在Query中的出现频率。$$dl$$为文档$$d$$的长度，$$avgdl$$为所有文档的平均长度。由于绝大部分情况下，$$q_i$$在query中只会出现一次，即$$q{f}_i=1$$，因此公式可以简化为：

$$R(q_i,d)=\frac{f_i\cdot (k_1+1)}{f_i+K}$$

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

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

$$score(Q,d)=\sum _{j=1}^{n}IDF(q_i)\frac{f_i\cdot (k_1+1)}{f_i+k_1\cdot (1-b+b\cdot \frac{dl}{avgdl})}$$

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

配置方法

{
  "feature_type": "bm25_feature",
  "feature_name": "query_doc_relevance",
  "query": "user:query",
  "document": "item:title",
  "term_doc_freq_file": "term_doc_freq.txt",
  "document_number": 1000,
  "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。

示例

功能介绍

str_replace_feature 表示字符串替换特征，将匹配上的所有子串替换为指定的对应子串。

Overlapping matches are replaced greedily

配置方法

{
  "feature_name": "norm_str",
  "feature_type": "str_replace_feature",
  "expression": ["user:query"],
  "default_value": "",
  "replacements": {
    "brown": "box",
    "dogs": "jugs",
    "fox": "with",
    "jumped": "five",
    "over": "dozen",
    "quick": "my",
    "the": "pack",
    "the lazy": "liquor",
    "|": "",
    "aa": "x",
    "a": "X"
  },
  "value_dimension": 1
}

• 可以同时配置replace_file和replacements，两者配置的替换字典会进行合并，replacements的优先级更高

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

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

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

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

  • vocab_file: 从文件读入vocab_list或vocab_dict

• 支持array类型的多值输入

示例

上述配置的执行结果如下：

功能介绍

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

可配置多个 pattern，匹配任意 pattern 的子字符串将会被替换。

配置方法

{
  "feature_name": "query",
  "feature_type": "regex_replace_feature",
  "expression": ["user:query"],
  "regex_pattern": "\\|",
  "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"
  ],
  "sequence_delim": ","
}

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

• 支持array类型和嵌套的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
    }
  ]
}

功能介绍

对输入数组切片（实现符合python语法的slice操作），或者获取数组单个索引位置的元素。

本质上是一种序列特征。

配置方法

{
  "feature_name": "test_feature",
  "feature_type": "slice_feature",
  "value_type": "float",
  "expression": [
    "user:click_items"
  ],
  "slice": "2:4"
}

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

• 支持array类型和嵌套的array类型表示多值输入

示例

在配置sequence_delim=","并且value_dimension=1时，输入输出如下：