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

概要

id_feature オペレーターは、離散特徴を処理します。これは、ユーザー 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" の 1 文字であり、"\u001d" とも記述できます。

概要

raw_feature オペレーターは、連続特徴を処理します。これは int、float、double などの数値型をサポートし、単一値および複数値の連続特徴の両方を扱います。

構成

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

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

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

例

^] は、複数値の区切り文字を表します。これは ASCII エンコーディング "\x1D" の 1 文字であり、2 文字ではありません。

ノーマライザー

raw_feature および match_feature パラメーターは、minmax、zscore、log10、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' = log10(x)（ただし x > threshold の場合）、それ以外の場合は x' = default

• expression

  構成例：method=expression,expr=sign(x)

  数式：カスタム関数または式を定義できます。入力値は変数 x で表されます。

概要

expr_feature オペレーターは、数学的式を評価し、その結果を特徴量値として返します。このオペレーターはバッチコンピューティングおよびブロードキャストをサポートしています。

重要：すべての入力は 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) の範囲で乱数を生成します。
  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	ベクトル内のすべての要素の積を返します。

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

• ビルトイン二項演算子

  演算子	説明	優先度
  =	代入。この特殊な演算子は、引数の 1 つを変更し、変数にのみ適用されます。	0
  ||	論理和（OR）	1
  &&	論理積（AND）	2
  |	ビット単位の論理和（OR）	3
  &	ビット単位の論理積（AND）	4
  <=	以下	5
  >=	以上	5
  !=	等しくない	5
  ==	等しい	5
  >	より大きい	5
  <	より小さい	5
  +	加算	6
  -	減算	6
  *	乗算	7
  /	部門	7
  %	剰余	7
  ^	x を y 乗する	8

• ビルトイン三項演算子

  C スタイルの構文を使用した if-then-else 論理をサポートします。

  遅延評価を採用しており、必要なブランチのみを評価します。

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

• ビルトイン定数

  定数	説明	値
  _pi	数学定数 π（円周率）です。	3.141592653589793
  _e	数学定数 e（オイラー数）です。	2.718281828459045

概要

combo_feature オペレーターは、複数の入力フィールドまたは式から特徴量の組み合わせ（デカルト積）を作成します。このプロセスは、特徴クロスとも呼ばれます。id_feature オペレーターは、クロスに使用されるフィールドが 1 つだけであるという点で、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 の 1 文字であり、2 文字ではありません。

出力特徴量の数は、次のように計算されます。

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

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

概要

lookup_feature オペレーターは、match_feature と同様です。これは、キーと値のペアのセットから値を取得します。

このオペレーターには、map および key パラメーターが必要です。

• map は辞書型または MultiString 型のフィールドであり、各文字列は「k1:v1」の形式です。

• key は任意の型のフィールドであり、複数のキーに対応する場合は配列型の入力が推奨されます。特徴量を生成するには、キーの値を取得し、それを map のキー型に変換した後、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 パラメーターを設定して取得した値をマージできます。有効な集計方法には、sum、mean、max、および min があります。

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：データソースであり、文字列としてエンコードされた 2 段階のネストされたマップです。

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

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

• category：1 段階目のマップ検索のプライマリキーです。

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

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

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

• need_discrete

  • true：オペレーターは、特徴量名とキーの複合文字列を返します。モデルはこの文字列を特徴量として使用し、一致した値は無視します。

  • false（デフォルト）：オペレーターは一致した特徴量値のみを返します。モデルはこの値を直接使用します。

• match_type

  • hit：1 つの一致した特徴量を返します。オペレーターは、category 値で 1 段階目のマップを照会し、得られた 2 段階目のマップを item 値で照会して、1 つの結果を得ます。単一段階のマッチングを行う場合、1 段階目のマップのキーに ALL を設定し、category パラメーターにも ALL を設定できます。

  • multihit：ワイルドカード ALL を category および item フィールドで使用できるようにし、複数の一致値を返すことができます。

• 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

  任意。文字列型の key フィールドの複数値区切り文字を指定します。デフォルト値は "\u001D" であり、1 文字である必要があります。

• default_value

  任意。入力特徴量が空の場合に使用するデフォルト値を指定します。

• value_dimension

  任意。デフォルト値は 0 です。このパラメーターは、オフラインタスクで出力を切り捨てるために使用できます。値が 1 の場合、出力テーブルのスキーマ型は 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",
  "match_type": "hit"
}

概要

overlap_feature オペレーターは、2 つのテキスト入力間の文字列マッチングメトリックを計算します。たとえば、検索アプリケーションでは、query が title に含まれているかどうかを判断するために使用できます。

これらの語の近接度測定方法は、「An Exploration of Proximity Measures in Information Retrieval」という論文に基づいています。

タイトル（ドキュメント）の語シーケンスが次のとおりであると仮定します：t1,t2,t1,t3,t5,t4,t2,t3,t4

• MinCover は、各 query 項目を少なくとも 1 回カバーする最短のドキュメントセグメントの長さとして定義されます。

• MinDist（最小ペア距離）：すべてのペア距離の最小値を計算します。たとえば、ペア距離が 1、2、3 の場合、MinDist = min(1, 2, 3) = 1 になります。

• MaxDist（最大ペア距離）：MinDist の逆です。すべてのペア距離の最大値を計算します。たとえば、ペア距離が 1、2、3 の場合、MaxDist = max(1, 2, 3) = 3 になります。

• AveDist（平均ペア距離）：すべてのペア距離の平均値を計算します。たとえば、ペア距離が 1、2、3 の場合、AveDist = (1 + 2 + 3) / 3 = 2 になります。

すべての集計演算子（MinDist、MaxDist、および AveDist）は、マッチする query 項目間のペア距離に基づいて定義されることに注意してください。ドキュメントが query 項目を 1 つだけマッチする場合、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 の場合。

概要

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

構成方法

たとえば、長さ 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 件のアイテム ID を格納します。モデル推論サービスは、このフィールドをキーとして side info を照会します。

  • オンライン推論サービス（EAS プロセッサー）へのリクエストパラメーターには、sequence_pk の値をキーとする特徴量が含まれている必要があります。

    • 例：click_50_seq: 5410233389955966;1832586（区切り文字は sequence_delim 構成の値）

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

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

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

    • たとえば、この構成では、シーケンス特徴量内の item_id、price 特徴量は推論サービスへのリクエストに渡されません。代わりに、プロセッサーが 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。

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

    • カラムがシーケンスでない場合、名前は ${input_name} となり、プレフィックスは付きません。

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

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

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

  • value_dimension（value_dim とも略される）：シーケンス内の各要素のディメンションを指定します。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"
  }
}</oov>

注：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 で指定された文字で要素が区切られた文字列です。

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

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

オンライン特徴量生成

行動 sideinfo は 2 つの方法で取得できます。1 つ目の方法は、EasyRec プロセッサーのアイテムキャッシュから取得し、sequence_pk で指定されたフィールドをプライマリキーとしてアイテムのプロパティを検索することです。2 つ目の方法は、リクエストで対応するフィールド値を提供することです。たとえば、前述の構成の「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"
  }
}

はじめに

sequence_combine_feature オペレーターは、シーケンス特徴量の各要素の複数の値を結合します。これは、指定された結合方法を使用して各要素の複数の値を集約し、複数値シーケンスを単一値シーケンスに変換します。

主な機能

• 複数値の結合：シーケンスの各要素の複数の値を単一の値に結合します。

• 柔軟な結合戦略：sum、mean、max、min、および count を含む複数の結合戦略をサポートします。

• 値マップ：文字列識別子を数値に変換する値マップをサポートしており、行動イベントシーケンスの処理に役立ちます。

• 二重区切り文字サポート：シーケンス区切り文字と複数値区切り文字を別々に構成できます。

構成

基本構成（数値結合）

{
  "feature_name": "seq_combine_feat",
  "feature_type": "sequence_combine_feature",
  "expression": "user:behavior_seq",
  "combiner": "sum",
  "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 を返します。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 のカンマ区切り文字列に変換します。

語彙ファイルの例

概要

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 行につき 1 文字のみを含める必要があります。これにより、フィルタリングが正常に実行されます。

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

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
}

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

• 出力：["正则生成代码", "html过滤工具", "正则表达式语法速查", "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$$ はクエリを表し、$$q_i$$ はクエリの $$i$$ 番目の語、$$d$$ はドキュメント、$$w_i$$ は $$q_i$$ の重み、R(qi,d) は $$q_i$$ のドキュメント $$d$$ に対する関連性スコアを表します。

語の重要度

語のドキュメントに対する関連性を重み付けする方法はいくつかあります。一般的な方法は、逆文書頻度（IDF）です。数式は次のとおりです。

$$Inverse\; Document\; Frequency\; (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$$ を使用する重要度は低くなります。

語の関連性

語 $$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$$ はドキュメント $$d$$ における の頻度であり、 はクエリにおける の頻度です。 はドキュメント の長さであり、 はすべてのドキュメントの平均長です。ほとんどの場合、 はクエリ内で 1 回しか出現しないため、 となり、数式は次のように簡略化できます：

$$R(q_i,d)=\frac{}{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」数式は、アルゴリズム設計において大きな柔軟性を提供し、形態素解析、term 重み付け、および term-ドキュメント関連性の異なるアプローチに基づいて、検索関連性スコアを算出するさまざまな方法を可能にします。

設定

{
  "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 が優先されます。

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

概要

2つの キーと値 ベクターのドット積、または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 演算子は、入力文字列内で一致したすべての部分文字列を、指定された置換後の文字列に置き換えます。

注：重複して一致した部分は、貪欲に置き換えられます。

構成

{
  "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： 特徴量変換の結果をハッシュ化し、剰余演算を実行します。

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

  • vocab_dict： ビニング結果は、特徴量値に対応する vocab_dict 内の値です。

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

• この演算子は多値配列入力をサポートしています。

例

次の表に、上記構成の実行結果を示します。

概要

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 を読み取ります。

• この特徴量は配列形式の複数値入力をサポートします。

例

概要

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

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

• 配列またはネストされた配列である多値入力をサポートしています。

例

式特徴量との併用

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

本質的には、sequence feature です。

構成

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

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

• この演算子は、配列やネストされた配列を含む複数値入力をサポートしています。

例

sequence_delim="," および value_dimension=1 を設定した場合、入力と出力は次のようになります：