Artificial Intelligence Recommendation：內建特徵運算元

功能介紹

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",
  "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
  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過濾工具", "Regex文法速查", "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",
  "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表示Regex替換特徵，將匹配上的子字串替換為指定的子字串。

可配置多個 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時，輸入輸出如下：