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

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

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

例

以下の例では、アイテム側の特徴 `is_main` を使用して、さまざまな設定での特徴の入力と出力を示します：

記号 ^] は複数値のセパレーターを表します。これは ASCII コード "\x1D" の単一文字であり、"\u001d" とも書くことができます。

機能紹介

`raw_feature` オペレーターは連続特徴を表します。int、float、double などの数値型をサポートし、単一値と複数値の両方の連続特徴を処理します。

設定

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

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

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

例

記号 ^] は複数値のセパレーターを表します。これは 2 文字ではなく、ASCII コード "\x1D" の単一文字であることに注意してください。

Normalizer

`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 = x > threshold ? log10(x) : default;

• expression

  設定例：method=expression,expr=sign(x)

  数式：任意の関数または式を設定できます。変数名は x に固定されており、式の入力を表します。

機能紹介

`expr_feature` オペレーターは式特徴を表します。式を評価し、float 型の特徴値を出力します。バッチコンピューティングとブロードキャストをサポートします。

注意：この特徴オペレーターを使用する場合、すべての入力は double 型に変換可能でなければなりません。

設定

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

pv = 2, click = 3 の場合、式特徴の値は 0.6224593312 です。

設定例

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

• スカラーとベクトルの計算 (ブロードキャスト)

  • 変数 a=1 と変数 b=[1, 2, 6] の場合、結果は [2, 3, 7] です。

• ベクトル対ベクトルの element-wise 計算

  • 変数 a=[3, 2, 1] と変数 b=[1, 2, 6] の場合、結果は [4, 4, 7] です。

• 一時変数とコンマ式をサポート

  • 例：x=roundp(a),(a-x)*b。この例では、x は一時変数であり、variables で設定する必要はありません。

  • コンマ式は左から右に評価されます。最も右のサブ式の値が返されます。

  • メモリのオーバーヘッドを削減するために、意味的に適切な場合は既存の変数を一時変数として再利用してください。

式特徴とシーケンス特徴の組み合わせ

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

式

• 組み込み関数 (スカラー)

  関数名	パラメーター数	説明
  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 (2.71828...) を底とする対数
  ln	1	e (2.71828...) を底とする対数
  exp	1	e の x 乗
  sqrt	1	値の平方根
  sign	1	符号関数 (-1 if x<0; 1 if x>0)
  abs	1	絶対値
  rint	1	最も近い整数に丸める
  round	1	最も近い整数に丸めます。常に 0 から遠い方に丸めます。
  roundp	1	カスタム精度に丸めます。例：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	var.	全引数の最小値
  max	var.	全引数の最大値
  sum	var.	全引数の合計
  avg	var.	全引数の平均値

  注意：前述の組み込み関数は、バッチコンピューティングとブロードキャストをサポートしています。

• 組み込みベクトル演算関数

  関数名	パラメーター数	説明
  len	1	ベクトルの長さ
  l2_norm	1	ベクトルの L2 正規化
  squared_norm	1	ベクトルの二乗正規化
  dot	2	2 つのベクトルの内積
  euclid_dist	2	2 つのベクトル間のユークリッド距離
  corr	2	2 つのベクトルのピアソン相関係数
  std_dev	1	ベクトルの標準偏差、n で割る
  pop_std_dev	1	ベクトルの母集団標準偏差、n-1 で割る
  variance	1	ベクトルの標本分散、n で割る
  pop_variance	1	ベクトルの母集団分散、n-1 で割る
  reduce_min	1	ベクトルの最小値
  reduce_max	1	ベクターの最大値の縮約
  reduce_sum	1	ベクターの要素の合計
  reduce_mean	1	ベクトルの平均
  reduce_prod	1	ベクトルの積

  注意：式に前述の組み込みベクトル演算関数が含まれている場合、ベクトル関数のパラメーターではない他の変数はスカラーでなければなりません。

• 組み込み二項演算子

  オペレーター	説明	優先度
  =	代入 *	0
  ||	論理和	1
  &&	論理積	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 演算子	C++ スタイルの構文

• 組み込み定数

  オペレーター	説明	優先度
  _pi	唯一無二の円周率。	3.141592653589793238462643
  _e	オイラー数。	2.718281828459045235360287

機能紹介

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

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

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

例

^] 記号は複数値のセパレーターを表します。これは 2 文字ではなく、ASCII コード「\x1D」の単一文字であることに注意してください。

出力特徴の数は次のとおりです：

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

Fn は、n 番目の依存フィールドの値の数を指します。

機能紹介

`match_feature` と同様に、`lookup_feature` オペレーターは、キーと値のペアのセットから必要な結果を照合して取得します。

`lookup_feature` オペレーターは、`map` と `key` の 2 つのフィールドに依存します。

• map は辞書または複数値の文字列 (MultiString) フィールドで、各文字列は「k1:v1」などの形式です。

• 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
}

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

• 辞書はマップ型の入力をサポートし、キーは配列型の入力をサポートします。

例

上記の設定について、特定のドキュメントに対して次のように仮定します：

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

記号 ^] は複数値のセパレーターを表します。これは 2 文字ではなく、ASCII コード "\x1D" の単一文字です。emacs では C-q C-5 を押すことで、vim では C-v C-5 を押すことでこの文字を入力できます。ここで、item_attr は複数値の文字列です。

マップが複数のキーと値のペアを表す場合、それは単一の文字列ではなく、複数値の文字列です。

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}

クエリ結果のマージ

複数のキーがある場合、コンバイナを設定して複数の取得値を結合できます。可能な設定は sum、mean、max、min です。

コンバイナを使用するには、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：ネストされた辞書 (nested_dict) で、辞書の辞書です。

  • user フィールドは、2 段階のマップを記述するために文字列を使用します。

  • | 文字は、第 1 レベルのマップの項目間のセパレーターです。^ 文字は、第 1 レベルのマップのキーと値の間のセパレーターです。

  • , 文字は、第 2 レベルのマップの項目間のセパレーターです。: 文字は、第 2 レベルのマップのキーと値の間のセパレーターです。

• category：プライマリキーで、第 1 レベルのマップで検索するためのキーです。

  ALL は、このレベルのすべてのキーがマッチングできることを示すワイルドカード文字です。

• item：セカンダリキーで、第 2 レベルのマップで検索するためのキーです。

  ALL は、このレベルのすべてのキーがマッチングできることを示すワイルドカード文字です。

• need_discrete

  • true：モデルは `match_feature` によって出力された特徴名を使用し、特徴値を無視します。デフォルト値は false です。

  • false：モデルは `match_feature` によって出力された特徴値を使用し、特徴名を無視します。

• match_type

  • hit：マッチした特徴を出力します。オペレーターは category の値を使用して第 1 レベルのマップを検索し、次に item の値を使用して第 2 レベルのマップを検索して結果を取得します。2 段階ではなく 1 段階のマッチングのみが必要な場合は、マップの第 1 レベルのキーを ALL に設定し、特徴生成設定の category パラメーターも「ALL」に設定できます。

  • multihit：category および item フィールドを MATCH_WILDCARD オプションである「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

  オプション。string 型の複数値 key フィールドのセパレーターです。デフォルト値は「\u001D」です。単一の文字のみがサポートされます。

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

機能紹介

文字列と単語のマッチング情報を含む特徴を出力します。たとえば、検索シナリオでは、検索クエリが商品タイトルに含まれているかどうかを計算します。

用語近接性尺度特徴の計算方法は、論文「An Exploration of Proximity Measures in Information Retrieval」で説明されています。

タイトル (ドキュメント) の用語シーケンスが次のようであると仮定します：t1,t2,t1,t3,t5,t4,t2,t3,t4

• MinCover は、ドキュメント内で各クエリ用語を少なくとも 1 回カバーする最短のドキュメントセグメントの長さとして定義されます。

• MinDist (最小ペア距離)：すべてのペアワイズ最小距離の最小値を計算します。たとえば、Q=t1,t2,t3 の場合、MinDist=min(1,2,3)=1 です。

• MaxDist (最大ペア距離)：MinDist の逆です。最大値を見つけます。たとえば、Q=t1,t2,t3 の場合、MaxDist=max(1,2,3)=3 です。

• AveDist (平均ペア距離)：すべてのペアワイズ最小距離の平均を計算します。たとえば、Q=t1,t2,t3 の場合、AveDist=(1+2+3)/3=2 です。

すべての集約オペレーター (MinDist、MaxDist、AveDist) は、マッチングする検索クエリ用語間のペアワイズ距離に基づいて定義されることに注意してください。ドキュメントが 1 つの検索クエリ用語にしかマッチしない場合、MinDist、AveDist、MaxDist はすべてドキュメントの長さとして定義されます。

設定

{
  "feature_type" : "overlap_feature",
  "feature_name" : "is_contain",
  "query" : "user:attr1",
  "title" : "item:attr2",
  "method" : "is_contain",
  "separator" : " ",
  "normalizer" : ""
}

重複特徴の出力は float 型です。

例 1

クエリは「high,high2,fiberglass,abc」で、タイトルは「high,quality,fiberglass,tube,for,golf,bag」です。

例 2

method=index_of、タイトルは 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 を格納します。モデル推論サービスはこのフィールドをキーとして使用して サイド情報 をクエリします。

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

    • 例：click_50_seq: 5410233389955966;1832586 (セパレーターは sequence_delim に設定された値です)。

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

  • シーケンスのアイテム側サブ特徴は、リクエストパラメーターでモデル推論サービスに渡す必要はありません。

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

    • たとえば、この設定では、シーケンス特徴内の item_id, price 特徴はリクエストで推論サービスに渡す必要はありません。代わりに、Processor のアイテムキャッシュから読み取られ、Processor 内の特徴生成 (FG) SDK によって連結され、オフライン学習中に使用された形式と一致することが保証されます。

  • シーケンスのユーザー側サブ特徴は、リクエストパラメーターでモデル推論サービスに渡す必要があります。

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

    • ${input_name} は通常、expression 設定項目を使用して設定されますが、設定はサブ特徴のタイプによって異なる場合があり、${input_name} には 入力ドメイン プレフィックス (item: または user:) は含まれません。

• features：シーケンスの サイド情報 で、アイテムの静的プロパティ値と行動時間情報が含まれます。

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

    • 特徴オペレーターに 1 つの入力フィールドしかない場合、そのフィールドの内容はシーケンスでなければなりません。この場合、sequence_fields を設定する必要はありません。

    • 特徴オペレーターに複数の入力フィールドがある場合、sequence_fields を設定しないと、すべてのアイテム側特徴 (item:XXX) がシーケンス入力フィールドであると見なされます。

  • オフラインタスクで使用される FG 入力テーブルには、すべてのサブ特徴に対応する列が含まれている必要があります。

    • 列がシーケンスである場合 (sequence_fields ルールに基づく)、名前を ${sequence_name}__${input_name} とします。

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

      • パフォーマンス向上のため、オフラインテーブルの列タイプは配列にすることを推奨します。sequence_delim を要素セパレーターとする string 型もサポートされています。

    • 列がシーケンスでない場合、プレフィックスなしで ${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"
  }
}

注意：input_alias パラメーターは入力フィールドのエイリアスを設定します。形式は "origin_field": "alias_field" です。元の入力フィールド名をより短い名前で置き換えることができます。

タイル設定

ほとんどの場合、非シーケンス特徴のシーケンスバージョンを作成するには、その feature_type に sequence_ プレフィックスを追加します。通常、特徴のシーケンスバージョンには default_value を設定する必要があることに注意してください。

例：

• sequence_id_feature

• sequence_raw_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

特殊ケース 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) は sideinfo をクエリしません。ユーザーは完全な入力を提供する必要があります。

• タイル化されたシーケンス特徴の入力フィールド名は、設定どおりのままであり、${sequence_name}__ のプレフィックスは付きません。

オンライン特徴生成

行動のサイド情報を取得するには 2 つの方法があります。1 つは、EasyRec Processor のアイテムキャッシュからサイド情報を取得する方法です。sequence_pk で設定されたフィールドをプライマリキーとして使用し、アイテムキャッシュからアイテムのプロパティ情報を見つけます。もう 1 つの方法は、ユーザーがリクエストに対応するフィールド値を提供する方法です。たとえば、上記の設定の「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"
  }
}

機能紹介

`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 ファイルの各行には 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 cheat sheet", "The Cat/"]

• outputs=["regular expression code generator", "html filtering tool", "regular expression syntax cheat sheet", "the cat/"]

機能紹介

BM25 (Best Matching) アルゴリズムは、情報検索の分野で主流のテキストマッチングアルゴリズムであり、通常、検索関連性スコアリングに使用されます。クエリを形態素 $$q_i$$ に解析します。次に、各検索結果 D について、各形態素 $$q_i$$ と D の関連性スコアを計算します。最後に、$$q_i$$ の D に対する関連性スコアの加重和を計算して、クエリと 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) です。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$$ とドキュメント $$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$$ 内の の出現頻度、 はクエリ内の q​ の出現頻度です。 はドキュメント $$d$$ の長さ、$$vgdl$$ は全ドキュメントの平均長を表します。ほとんどのクエリでは が一度しか出現しないため、 と見なせます。したがって、この数式は次のように簡略化できます：

$$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 数式は、トークン化、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 ファイルと 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"
}

• この特徴は、配列やマップなどの複雑な入力タイプをサポートしています。可能な場合は、複雑なタイプを使用することを推奨します。

• 入力に value 部分がない場合、デフォルトの value は 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 の場合、入出力は次のようになります。