:ビルトイン特徴量オペレーター

概要

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" の単一文字であり、2 文字ではありません。

正規化子

raw_feature と match_feature の両方は、minmax, zscore, log10, and expression の 4 種類の正規化手法をサポートしています。これらの構成と計算方法は次のとおりです。

• 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] です。

• ベクター同士の 要素ごとの 計算

  • 変数 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
        }
      ]
    }
  ]
}

式

• ビルトイン関数（スカラー）

  関数名	パラメーター数	説明
  rnd	0	[0, 1) の範囲で乱数を生成します。
  isnan	1	入力が NaN の場合に 1.0 を返し、それ以外の場合は 0.0 を返します。この関数にはバージョン 1.0.5 以降が必要です。
  sin	1	数値の正弦を返します。
  cos	1	数値の余弦を返します。
  tan	1	数値の正接を返します。
  asin	1	数値の逆正弦を返します。
  acos	1	数値の逆余弦を返します。
  atan	1	数値の逆正接を返します。
  sinh	1	数値の双曲線正弦を返します。
  cosh	1	数値の双曲線余弦を返します。
  tanh	1	数値の双曲線正接を返します。
  asinh	1	数値の逆双曲線正弦を返します。
  acosh	1	数値の逆双曲線余弦を返します。
  atanh	1	数値の逆双曲線正接を返します。
  log2	1	数値の底 2 の対数を返します。
  log10	1	数値の底 10 の対数を返します。
  log	1	数値の自然対数（底 e）を返します。
  ln	1	数値の自然対数（底 e）を返します。
  exp	1	オイラー数（e）を数値のべき乗にします。
  sqrt	1	数値の平方根を返します。
  sign	1	数値の符号を返します。負の場合は -1、正の場合は 1、ゼロの場合は 0 です。
  abs	1	数値の絶対値を返します。
  rint	1	数値を最も近い整数に丸めます。
  round	1	「ゼロから遠ざかる方向への丸め」方式を使用して、数値を最も近い整数に丸めます。
  roundp	2	数値を指定された精度に丸めます。例：roundp(3.14159, 2) は 3.14 を返します。
  mod	2	除算の余りを返します。
  floor	1	数値を下方向へ最も近い整数に丸めます。
  ceil	1	数値を上方向へ最も近い整数に丸めます。
  trunc	1	小数部分を削除して数値を切り捨てます。
  sigmoid	1	数値のシグモイドを返します。
  sphere_dist	4	2 つの GPS ポイント間の球面距離を返します。引数：lng1、lat1、lng2、lat2。
  haversine	4	2 つの GPS ポイント間のハーバーサイン距離を返します。引数：lng1、lat1、lng2、lat2。
  min	可変	引数リストから最小値を返します。
  max	可変	引数リストから最大値を返します。
  sum	可変	すべての引数の合計を返します。
  avg	可変	すべての引数の平均値を返します。

  注：これらのビルトイン関数はバッチ計算とブロードキャストをサポートしています。

• ビルトインベクトル演算関数

  関数名	パラメーター数	説明
  len	1	ベクターの長さ（要素数）を返します。
  l2_norm	1	L2 正規化されたベクターを返します。
  squared_norm	1	ベクターの L2 ノルムの二乗を返します。
  dot	2	2 つのベクターの内積を返します。
  euclid_dist	2	2 つのベクター間のユークリッド距離を返します。
  corr	2	2 つのベクター間のピアソン相関係数を返します。
  std_dev	1	ベクターの標本標準偏差（n-1 で除算）を返します。
  pop_std_dev	1	ベクターの母集団標準偏差（n で除算）を返します。
  variance	1	ベクターの標本分散（n-1 で除算）を返します。
  pop_variance	1	ベクターの母集団分散（n で除算）を返します。
  reduce_min	1	ベクター内の最小値を返します。
  reduce_max	1	ベクター内の最大値を返します。
  reduce_sum	1	ベクター内のすべての要素の合計を返します。
  reduce_mean	1	ベクター内のすべての要素の平均値を返します。
  reduce_prod	1	ベクター内のすべての要素の積を返します。

  注：式にこれらのビルトインベクトル演算関数のいずれかが含まれている場合、式内の他のすべての変数はスカラーである必要があります。

• ビルトイン二項演算子

  演算子	説明	優先度
  =	代入 *	0
  ||	論理 OR	1
  &&	論理 AND	2
  |	ビット単位の OR	3
  &	ビット単位の AND	4
  <=	以下	5
  >=	以上	5
  !=	等しくない	5
  ==	等しい	5
  >	より大きい	5
  <	より小さい	5
  +	加算	6
  -	減算	6
  *	乗算	7
  /	部門	7
  %	剰余	7
  ^	x を y 乗します。	8

  * 代入演算子は特殊です。引数の 1 つを変更し、変数にのみ適用されます。

• ビルトイン三項演算子

  この演算子は if-else 機能を提供します。

  遅延評価により、式の必要な分岐のみが評価されます。

  演算子	説明	構文
  ?:	if-then-else 演算子	condition ? value_if_true : value_if_false

• ビルトイン定数

  定数	説明	値
  _pi	数学定数 π（パイ）。	3.141592653589793
  _e	数学定数 e（オイラー数）。	2.718281828459045

概要

combo_feature オペレーターは、複数のソースフィールドの直積を計算して合成特徴を作成します。このプロセスは特徴クロスとしても知られています。id_feature オペレーターは、単一のソースフィールドのみを含む combo_feature の特殊なケースです。通常、特徴クロスのソースフィールドは異なるテーブルに由来します（例：ユーザー特徴量とアイテム特徴量の組み合わせ）。

構成

{
  "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" の単一文字であり、2 文字ではありません。

出力値の数は次のように計算されます。

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

ここで、|Fn| は n 番目のソースフィールドの値の数を表します。

概要

match_feature と同様に、lookup_feature オペレーターはキーと値のペアのセット内でキーを検索し、対応する値を返します。

このオペレーターは map と key の 2 つのパラメーターに依存します。

• map パラメーターは辞書または多値文字列です。多値文字列では、各要素は "k1:v1" 形式のキーと値のペアです。

• key パラメーターは任意のデータ型にすることができます。複数のキーがある場合は、配列型の入力が推奨されます。特徴量を生成する際、オペレーターは key パラメーターの値を取得し、それを map のキー型に変換してから、マップ内で対応する値を見つけます。

構成

{
  "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 パラメーターは配列型入力をサポートします。

例

上記の構成について、ドキュメントに次のデータがあると仮定します。

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

記号 ^] は複数値の区切り文字を表します。これは、ASCII コード "\x1D" を持つ 1 文字であり、2 文字ではありません。emacs では C-q C-5 を、vim では C-v C-5 を押してこの文字を入力します。ここで、item_attr は複数値の文字列です。

map パラメーターが文字列として複数のキーと値のペアを表す場合、それは標準文字列ではなく多値文字列である必要があります。

item_value : "k2"

結果の特徴量は item_match_item_k2_v2 です。

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

map: {"k1:123", "k2:234", "k3:3"}
key: {"k1"}
Result: feature={123}

検索結果の結合

複数のキーを指定する場合、combiner パラメーターを使用して取得した値を集計できます。

combiner を使用するには、need_discrete を false に設定する必要があります。この場合、検索された値は数値または数値に変換可能な文字列である必要があります。

概要

match_feature オペレーターは通常、特徴量間のマッチングに使用されます。本質的には、2 段階のマップ検索を実行します。

構成

構成ファイルは 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：ネストされた辞書。

  • user フィールドは、2 段階のマップを表す文字列を使用します。

  • 第 1 段階のマップでは、| が項目間の区切り文字であり、^ がキーとその値の間の区切り文字です。

  • 第 2 段階のマップでは、, が項目間の区切り文字であり、: がキーとその値の間の区切り文字です。

  • 第 1 段階の辞書は Map<K, string> 入力もサポートしており、K は string,int32,int64 型にすることができます。マップの値は内部辞書を表す文字列であり、同じ区切り文字を使用します。

• category：第 1 段階のマップ検索の主キーです。

  ALL はワイルドカードで、このレベルのすべてのキーに一致します。

• item：第 2 段階のマップ検索のセカンダリキーです。

  ALL はワイルドカードで、このレベルのすべてのキーに一致します。

• need_discrete

  • true：モデルは出力から生成された特徴量名を使用し、特徴量値を無視します。デフォルトでは、このパラメーターは false です。

  • false：モデルは出力からマッチした特徴量値を使用し、特徴量名を無視します。

• match_type

  • hit：単一のマッチした特徴量を出力します。オペレーターはまず category 値を使用して第 1 段階のマップをクエリし、次に結果の第 2 段階のマップを item 値でクエリして最終値を取得します。単一レベルのマッチングを実行するには、第 1 段階のマップキーを ALL に設定し、特徴量生成（FG）構成の category パラメーターを "ALL" に設定します。

  • multihit：category および item フィールドで ALL ワイルドカードを使用した場合に、複数の値をマッチして出力します。

• normalizer

  正規化方法です。このパラメーターは raw_feature オペレーターのものと同じ意味を持ち、need_discrete=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

  オプション。文字列型の key フィールドの多値区切り文字です。デフォルトは "\u001D" です。

• default_value

  オプション。null 入力に対するデフォルト値です。

• value_dimension

  オプション。出力のデータ構造を定義します。デフォルトは 0 です。1 に設定すると、出力は value_type 型の単一値になります。それ以外の場合は、array<value_type> 型の配列になります。

• stub_type

  オプション。true に設定すると、出力は中間結果として扱われ、モデルに送信されません。デフォルトは false です。

例

{
  "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",
  "match_type": "hit"
}

概要

2 つの文字列間の用語一致に関する情報を出力します。たとえば、query がアイテムの title に含まれているかどうかを判断するためにこの特徴量を使用できます。

「An Exploration of Proximity Measures in Information Retrieval」という論文では、これらの特徴量の計算方法について説明されています。

title（document）の term シーケンスが次のようになっていると仮定します：t1,t2,t1,t3,t5,t4,t2,t3,t4

• MinCover は、各 query term を少なくとも 1 回カバーする最短の document セグメントの長さを測定します。

• MinDist（最小ペアワイズ距離）：query term のマッチングペア間で見つかった最小距離です。たとえば、クエリ Q=t1,t2,t3 がドキュメント内でペアワイズ距離 1、2、3 を持つ場合、MinDist は min(1,2,3)=1 です。

• MaxDist（最大ペアワイズ距離）：query term のマッチングペア間で見つかった最大距離です。同じ例では、MaxDist=max(1,2,3)=3 です。

• AveDist（平均ペアワイズ距離）：query term のマッチングペア間のペアワイズ距離の平均です。同じ例では、AveDist=(1+2+3)/3=2 です。

MinDist、MaxDist、AveDist のすべての集約演算子は、マッチング query term 間のペアワイズ距離に基づいて定義されることに注意してください。document にマッチング query term が 1 つしかない場合、MinDist、AveDist、MaxDist の値は document の長さになります。

構成

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

概要

ユーザーの過去の行動は重要な特徴量です。この行動は通常、クリックや購入などのシーケンスとして表現されます。シーケンスを構成するエンティティは、アイテム自体またはその属性です。

構成

たとえば、最大長 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_length：シーケンスの最大長です。

• sequence_delim：シーケンス内の要素を区切るデリミタです。

• sequence_pk：シーケンスのプライマリキーです。例：user:click_50_seq は、ユーザーが最近クリックした上位 50 件の itemID を格納します。モデル推論サービスはこのフィールドをキーとして side info をクエリします。

  • オンライン推論サービス（EAS Processor）のリクエストパラメーターには、キーが sequence_pk である特徴量を含める必要があります。

    • 例：click_50_seq: 5410233389955966;1832586（区切り文字は sequence_delim で指定された値）

      • 上記の例では、click_50_seq 特徴量の値は 5410233389955966;1832586 です。

  • シーケンスのアイテム側サブ特徴量は、モデル推論サービスへのリクエストに含める必要はありません。

    • モデル推論サービスはこのフィールドをキーとしてアイテムの side info をクエリします。

    • たとえば、この構成では、item_id, price シーケンス特徴量は推論サービスへのリクエストに含める必要がありません。代わりに、Processor のアイテムキャッシュから取得され、fg SDK を使用して連結されます。このプロセスにより、オフライントレーニング時に使用されたフォーマットと一貫性が保たれます。

  • シーケンスのユーザー側サブ特徴量は、モデル推論サービスへのリクエストに含める必要があります。

    • 特徴量名は ${sequence_name}__${input_name} です。例：click_50_seq__ts。

    • ${input_name} は通常 expression オプションで構成されますが、サブ特徴量タイプによって構成が異なる場合があります。${input_name} には input domain プレフィックス（item: や user: など）は含まれません。

• Features：side info はシーケンスの情報で、アイテムの静的属性値や行動時間情報などが含まれます。

  • sequence_fields：入力シーケンスのフィールド名を指定します。値は string または [string] 配列です。

    • 特徴量オペレーターが 1 つの入力フィールドのみを持つ場合、そのフィールドの内容はシーケンスである必要があります。この場合、sequence_fields を構成する必要はありません。

    • 特徴量オペレーターが複数の入力フィールドを持つ場合、sequence_fields を構成しないと、すべてのアイテム側特徴量（例：item:XXX）がシーケンス入力フィールドであるとみなされます。

  • オフラインタスクの入力テーブルには、すべてのサブ特徴量に対応する列を含める必要があります。

    • 列がシーケンスの場合（sequence_fields のルールを参照）、列名は ${sequence_name}__${input_name} になります。

      • たとえば、この構成では、オフラインテーブルに 4 つの列が必要です：click_50_seq__item_id、click_50_seq__price、click_50_seq__ts、および click_50_seq__clk_time_seq。

      • オフラインテーブルの列には array 型（パフォーマンス向上のため推奨）を使用できますが、string 型で sequence_delim を要素の区切り文字として使用することもサポートされています。

    • 列がシーケンスでない場合、列名は ${input_name} にプレフィックスを付けずに命名します。

      • たとえば、この構成では、オフラインテーブルに 1 つの非シーケンス列が必要です：${cur_time}

    • input_alias グローバル構成を使用して、長い列名に短いエイリアスを設定できます（以下の例を参照）。

  • 特徴量ビニングをサポートしています。詳細については、「特徴量ビニング（離散化）」をご参照ください。ビニングが構成されている場合、出力要素タイプは int64 になり、形状は value_dimension 構成によって決定されます。

  • value_dimension（または value_dim）：シーケンス内の各要素のディメンションです。sequence_raw_feature の場合、このパラメーターが array<float> のときに出力タイプは 1 になり、それ以外の値の場合は 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

これらの 2 つの特殊ケースでは、次のオプションパラメーターを追加できます。

• sequence_length：シーケンスの最大長です。この長さを超える要素は切り捨てられます。デフォルト値は -1 で、シーケンスは切り捨てられません。

• sequence_delim：シーケンス要素間の区切り文字です。デフォルト値は ; です。

以下のコードは構成例を示しています。

{
  "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_delim で構成された文字を区切り文字とする文字列です。

• この構成では、オンラインサービス（Processor）は side info をクエリしません。完全な入力を提供する必要があります。

• フラット化フォーマットのシーケンス特徴量の入力フィールド名は、構成された名前と同じであり、${sequence_name}__ というプレフィックスは付きません。

オンライン特徴量生成

行動 sideinfo は 2 つの方法で取得できます。1 つは EasyRec Processor のアイテムキャッシュから sideinfo を取得する方法です。sequence_pk で指定されたフィールドがプライマリキーとして使用され、アイテムキャッシュ内でアイテム属性情報を検索します。もう 1 つの方法は、対応するフィールド値をリクエストに設定する方法です。たとえば、上記の構成の "ts" フィールドは（リクエスト時間 - イベント時間）を表し、これは推薦リクエスト時間からユーザー行動時間を引いたものです。この値は各リクエストで変化するため、リクエストから取得する必要があります。

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

user_features {
  key: "click_50_seq__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": "|"
}

シーケンス版は 2 つの方法で構成できます。

• 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：基本的な数値結合（合計）

構成：

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

入力と出力：

例 2：行動イベントシーケンス（値マッピングあり）

構成：

{
  "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 を返します。このオペレーターは、tokenizers-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 の場合、オペレーターは output_delim で指定された文字で区切られたトークン ID の文字列を返します。

語彙の例

概要

text_normalizer オペレーターはテキスト正規化を実行します。その機能には、大文字小文字の変換、繁体字から簡体字への変換、全角文字から半角文字への変換、特殊文字のフィルタリング、GBK/UTF-8 エンコーディングの変換、漢字の分割が含まれます。

構成

{
    "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 ファイルの各行には 1 文字のみを含めることができます。そうでない場合、フィルタリングは失敗します。

テキスト正規化オプション

parameter パラメーターは、以下の数値の 1 つ以上の合計を指定します。

たとえば、大文字から小文字への変換、全角から半角への変換、繁体字から簡体字への変換、特殊文字のフィルタリングが必要な場合、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=["Regular Expression Code Generator", "HTML Filtering Tool", "Regular Expression Syntax Cheatsheet", "The Cat/"]

• outputs=["regex code generator", "HTML filtering tool", "regular expression syntax quick reference", "the cat/"]

機能

BM25（Best Matching）アルゴリズムは、情報検索における主要なテキストマッチングアルゴリズムであり、検索関連性スコアを計算するために使用されます。このアルゴリズムはまずクエリを用語 $$q_i$$ に解析します。次に、各検索結果 D について、各用語 $$q_i$$ の D に対する関連性スコアを計算します。最後に、各用語 $$q_i$$ の関連性スコアの加重和を計算して、クエリと D 間の最終的な関連性スコアを生成します。

中国語の場合、クエリのトークン化を形態素解析として扱い、各用語を形態素$$q_i$$ として扱うことができます。

BM25 アルゴリズムの一般的な数式は次のとおりです。

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

ここで、$$Q$$ はクエリを表し、qi は $$i$$ 番目のクエリ term、$$d$$ はドキュメント、$$w_i$$ は $$q_i$$ の重み、そして R(q_i, d) はドキュメント $$q_i$$ に対する の関連スコアです。

用語の重要度

ドキュメントに対する term の関連性を判断するためのメソッドはいくつかあります。最も一般的なものの 1 つは、逆文書頻度（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$$ の識別力（discriminating power）は低くなります。したがって、関連性を判定する上で $$q_i$$ は重要度が低くなります。

用語の関連性

BM25 において、クエリ項 $$q_i$$ とドキュメント $$d$$ の間の関連スコア（$$R(q_i,d)$$ で表される）は、次のとおりです。

$$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,\; and{k}_2=0$$ です。$$f_i$$ はドキュメント $$q_i$$ 内における term の出現頻度であり、 はクエリ内における term の出現頻度です。 はドキュメント の長さであり、 は全ドキュメントにおける平均ドキュメント長です。クエリ内では term は通常 1 回しか出現しないため ()、この数式は次のように簡略化されます：

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

$$b$$ の定義から、パラメーター $$b$$ がドキュメントの長さが関連性に与える影響を調整することがわかります。$$K$$ の値が大きいほど、ドキュメントの長さが関連スコアに与える効果は大きくなり、逆もまた同様です。ドキュメントの相対的な長さが長いほど、$$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 が優先され、使用されます。

• この機能をオンラインサービスで使用する場合、term_doc_freq_file ファイルと fg.json を同じディレクトリに配置します。

概要

2 つの key-value インデックスのベクターのドット積を計算するか、2 つのセットの共通要素数（交差のサイズ）を求めます。

構成

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

• この特徴量は、配列 や マップ などの複合型をサポートしています。パフォーマンスを最適化するには、複合型を使用してください。

• 入力に 値 部分が含まれない場合、デフォルトの 値 は 1.0 になります。このプロパティを利用して、2 つのセットの共通要素数を求めることができます。

• default_value を構成しない場合、デフォルト値は 0 に設定されます。

例

概要

str_replace_feature オペレーターは、入力文字列内で一致したすべての部分文字列を指定された置き換え文字列に置き換えます。

重複する一致部分は、貪欲に（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 の方が優先度が高くなります。

• このオペレーターは特徴量ビニングをサポートしています。構成の詳細については、「Feature Binning (Discretization)」をご参照ください。

  • hash_bucket_size：特徴量変換結果をハッシュ化し、剰余演算を適用します。

  • vocab_list：語彙リストに基づいて入力をビン分けし、各値をリスト内のインデックスにマッピングします。

  • vocab_dict：各特徴量値を vocab_dict 内の対応する値にマッピングすることで入力をビン分けします。

  • vocab_file：vocab_list または vocab_dict をファイルから読み込みます。

• このオペレーターは array 型の複数値入力をサポートしています。

例

次の表は、前述の構成例に対する出力を示しています。

概要

regex_replace_feature オペレーターは、正規表現に一致する部分文字列を指定された置換文字列で置き換えます。

複数のパターンを設定できます。オペレーターは、指定されたいずれかのパターンに一致する部分文字列を置き換えます。

構成

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

• このオペレーターは特徴量ビニングをサポートしています。構成の詳細については、「特徴量ビニング (離散化)」ドキュメントをご参照ください。以下のパラメーターが利用可能です。

  • hash_bucket_size：特徴量の値をハッシュし、剰余演算を適用します。

  • vocab_list：語彙リストに基づいて特徴量の値をビン分けし、リスト内のインデックスにマップします。

  • vocab_dict：各特徴量の値を vocab_dict 内の対応する値にマップします。

  • vocab_file：vocab_list または vocab_dict をファイルから読み込みます。

• 多値の array 入力をサポートしています。

例

概要

ブールマスクを使用してシーケンスから要素をフィルターします。tf.boolean_mask(tensor, mask) と同様の動作をします。

これは sequence feature の一種です。

構成

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

• 特徴量ビニングをサポートしています。構成の詳細については、「特徴量ビニング (離散化)」をご参照ください。

• 配列またはネストされた配列形式の複数値入力をサポートしています。

使用例

式特徴量との併用

{
  "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 スタイルのスライス構文を使用して入力配列をスライスするか、特定のインデックスにある要素を取得します。

これは シーケンス特徴量 の一種です。

構成

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

• このオペレーターは特徴量ビニングをサポートしています。構成の詳細については、「特徴量ビニング (離散化)」をご参照ください。

• このオペレーターは配列やネストされた配列を含む複数値入力をサポートしています。

例

sequence_delim="," および value_dimension=1 を設定した場合の入力と出力は次のとおりです。