IBM Match 360 REST API を使用した拡張マッチング・アルゴリズムのチューニング

多次元比較フィルターの生成

Copy link to section

マッチング・アルゴリズムで多次元比較フィルターを生成するには、REST API コマンドを使用してマッチング・エンジン構成を更新します。

1. IBM Match 360 API インターフェースにアクセスして認証します。

2. 以下の例のように、フィルターを定義する POST /mdm/v1/algorithms/{record_type} ペイロードを指定します。

   {"person_entity":{"auto_link_threshold":0.4,"matching_attributes":[{"attributes":["legal_name"], "post_filter_methods": ["false_positive_filter"]},{"attributes":["primary_residence"], "post_filter_methods": ["false_positive_filter"]}, {"attributes":["mobile_telephone"]},
   {"attributes":["birth_date"], "post_filter_methods": ["false_positive_filter"]}, {"attributes":["gender"]}, {"attributes":["personal_email"]}]}}
   Copy to clipboardクリップボードにコピーされました

   サンプル・ペイロードで、 false_positive_filter はカスタム・フィルターの名前です。 これは、フィルター名を含むペイロード内の各属性に適用されます。

サンプル API ペイロードは、重みとペナルティーがデフォルト (0) である false_positive_filter を含むアルゴリズムを生成します。

オプションで、組織の要件に合わせて重みとペナルティーをカスタマイズし、 PUT /mdm/v1/algorithms/{record_type} API を使用して更新したアルゴリズムをデプロイすることができます。

フィルターを定義するパラメーターについて

Copy link to section

多次元比較フィルターを定義する構成パラメーターについて理解するには、前のセクションで作成した false_positive_filter の例を検討してください。

API コマンド GET /mdm/v1/algorithms/{record_type}を使用して、現在のアルゴリズムを取得します。

前のセクションで POST 要求を送信した後、対応するペイロードの例を使用して、アルゴリズム構成の以下のセクションが生成されました。

{
  "false_positive_filter": {
    "filter_recipe": [
      {
        "method": "FilterMethod.MultiDimFilter",
        "inputs": [1,2,3],
        "label": "Multi-Dim filter",
        "weights": [
          {
            "distances": [0,0],
            "values": [0,0,0,0,0,0]
          }
        ]
      }
    ],
    "inputs": [
      {"compare_method": "address_compare"},
      {"compare_method": "date_compare"},
      {"compare_method": "pername_compare"}
    ],
    "label": "false_positive_filter"
  }
}
Copy to clipboardクリップボードにコピーされましたShow more

false_positive_filter セクションの例には、多次元比較フィルターを定義する標準パラメーターが含まれています。

• filter_recipe -このセクションには、入力ごとに一致する重みを定義するために必要なレシピを提供するパラメーターの配列が含まれています。

  • inputs filter_recipe.inputs セクションには、このフィルター・レシピが適用される入力の索引が含まれています。 これらは、 inputs セクションにリストされている比較メソッドの順序に対応する数値です。 例えば、この例では、 1 は address_compare メソッドに対応し、 2 は date_compare メソッドに対応し、 3 は pername_compare メソッドに対応します。
  • weights - weights セクションは、3 次元比較で各入力をどのように重み付けするかを定義するエレメントの配列です。 weights セクションには、入力の distances 定義と values 定義が含まれています。 定義されていない入力のデフォルトの重みは 0 です。

• inputs -このセクションには、マッチング属性の比較メソッドが含まれます。 これらの方法では、 filter_recipe セクションで定義した距離と重みを使用します。

• max_distance -オプション (非表示)。 このパラメーターは、最大距離を定義します。 デフォルトの最大距離は 5 です。これは、 filter_recipe.weights.values パラメーターに 6 つのエレメント ("values":[0,1,2,3,4,5]) を含めることができることを意味します。

カスタム・フィルターの構成

Copy link to section

多次元比較フィルターで使用するために既存の比較方法をカスタマイズするには、以下のようにします。

1. 現在のアルゴリズムを取得します。

   GET /mdm/v1/algorithms/{record_type}
   Copy to clipboardクリップボードにコピーされました

2. 必要に応じてアルゴリズムを更新します。 例えば、以下を行うことができます。

   • weights セクションでエレメントを追加または更新して、リストされた入力の重みをカスタマイズします。
   • max_distance パラメーターを追加して、最大距離を定義します。
   • デフォルトのマッチング・ウェイトの代わりにこのフィルターを使用する比較メソッドを入力として追加します。

3. 更新したバージョンでマッチング・アルゴリズムを上書きします。

   PUT /mdm/v1/algorithms/{record_type}
   Copy to clipboardクリップボードにコピーされました

例 1: 最大距離を 9 に設定し、次のように入力と距離のさまざまな組み合わせに対してカスタムの重み付けとペナルティーを指定する場合は、以下のサンプル・ペイロードを使用します。 -input1 distance=0, input2 distance=0, input3 distance = [0,1,2,3,5,9. この場合、距離の組み合わせ [0,0, 3] のスコアは 15 になります。

• input1 distance=1、 input2 distance=0、 input3 distance = [0,1,2,3,4,5,6,7,8, 9]。 この場合、距離の組み合わせ [1,0, 9] は、ペナルティー付きスコア -30 を示します。

{
  "false_positive_filter": {
    "filter_recipe": [
      {
        "method": "FilterMethod.MultiDimFilter",
        "max_distance": 9,
        "inputs": [1,2,3],
        "label": "Multi-Dim filter",
        "weights": [
          {
            "distances": [0,0],
            "values": [0,-5,-10,-15,-20,-25,-30,-30,-30,-30]
          },
          {
            "distances": [1,0],
            "values": [0,-5,-10,-15,-20,-25,-30,-30,-30,-30]
          }
        ]
      }
    ],
    "inputs": [
      {"compare_method": "address_compare"},
      {"compare_method": "date_compare"},
      {"compare_method": "pername_compare"}
    ],
    "label": "false_positive_filter"
  }
}
Copy to clipboardクリップボードにコピーされましたShow more

例 2: 以下のサンプル・ペイロードのように、独自のカスタマイズされた比較メソッドを追加し、それらが全体的な一致スコアの要因から除外されるように構成することができます。 この場合、カスタム・メソッドは多次元比較フィルターでのみ使用されます。

以下の例では、 given_name_only_compare フィルターは overall_score_contribution を falseに設定します。

{
  "given_name_only_compare": {
    "methods": [
      {
        "inputs": [
          {
            "attributes": [
              "legal_name"
            ],
            "fields": [
              "given_name"
            ]
          }
        ],
        "compare_recipe": [
          {
            "comparison_resource": "person_person_entity_person_compare_spec_name",
            "method": "CompareMethod.NameCompare",
            "inputs": [
              1
            ],
            "label": "Given Name Only Match",
            "fields": [
              "given_name"
            ]
          } 
        ]
      }
    ],
    "overall_score_contribution" : false,
    "label": "Given Name Only Compare",
    "weights": [1,0,0,0,0,0,0,0,0,0,0]
  }
}
Copy to clipboardクリップボードにコピーされましたShow more

ソース・レベルのしきい値のサンプル JSON オブジェクト

Copy link to section

以下の JSON の例では、Person エンティティーのソース・レベルのしきい値を定義するマッチング・アルゴリズム構成ファイルのスニペットを確認できます。

"person_entity":{

  "auto_link_threshold":150,

  "clerical_review_threshold":120,

  "source_level_thresholds": {

       "src0": {

            "default":[165, 150],

            “srcxsrc” : {

                  "src0": [null, null],    

                  "src1": [160, 130], 

                  "src2": [123, 111], 

                  "src3": [null, null]

           }

       },

       "src1": {

            “srcxsrc” : {

                  "src1": [160, 130], 

                  "src2": [123, 111], 

                  "src3": [136, 120], 

                  "src4": [120, null]

           }

       }

    }

}
Copy to clipboardクリップボードにコピーされましたShow more

上記の例では、

• デフォルトのグローバル自動リンクしきい値は 150です。
• デフォルトのグローバル事務レビューしきい値は 120です。
• src0、 src1、 src2、 src3、および src4 は、ソース名の例です。
• source_level_thresholds オブジェクト内では、ソースごとのしきい値は、 src0 および src1の 2 つのソースに対して定義されます。

一般的なガイダンス:

• source_level_thresholds オブジェクト内の各ソースの下で、 default パラメーターを使用して、そのソースのデフォルトのグローバル・マッチングしきい値をオプションでオーバーライドすることができます。
• 各ソースの下で、 srcxsrc プロパティーの下に、ソースからソースへのマッチングしきい値の配列を定義できます。 これらのしきい値は、リストされたソースからのレコードを比較するときに使用されます。
• 配列内で、大括弧で囲まれた値は、 [autolink-threshold, clerical-threshold]の形式になります。 そのため、 [136, 120] は、指定されたソースとソースの比較で、オートリンクしきい値が 136、事務レビューしきい値が 120 であることを示します。
• 両方の値が指定されている場合、オートリンクしきい値は常に、事務的なレビューしきい値よりも高くなければなりません。
• 値が nullの場合、そのしきい値は無効になります。
• ペアの両方の値が nullとして指定されている場合、2 つのソース間のマッチングとリンクの両方が無効になります。
• 両方の値が null で、指定された 2 つのソースが同じである場合、ソースは 参照ソース のみと見なされます。 例えば、前述の JSON の例では、 src0 は src0 の参照ソースです。 参照ソースからのレコードのみを持つエンティティーは実行できません。

ソース・レベルのしきい値結果の評価

Copy link to section

カスタム・マッチング・アルゴリズムでソース・レベルのしきい値を構成した場合は、以下の REST API メソッドを使用してスコアリングの詳細を取得します。

POST /v1/compare/?details=debug&crn={CRN}&entity_type={entity_type}&record_type={record_type}
Copy to clipboardクリップボードにコピーされました

このメソッドによって返される情報を使用して、結果を評価し、必要に応じてソース・レベルのしきい値構成を微調整することができます。

ソース・レベルのしきい値とペアのレビュー

Copy link to section

ペア・レビューによって生成されたチューニング推奨を受け入れると、ソース・レベルのしきい値が上書きされる可能性があります。 お客様の組織が IBM Match 360 ペア・レビュー機能を使用してインテリジェントなチューニング推奨を生成する場合、ソース・レベルのしきい値を定義する前にペア・レビュー・タスクを実行することをお勧めします。

カスタム・マッチング・アルゴリズムでソース・レベルのしきい値を既に定義している場合は、 IBM Match 360 CR (mdm-cr) を編集して、ソース・レベルのしきい値機能を無効にします。 CR でソース・レベルのしきい値を無効にするには、以下のコマンドを使用します。

oc patch mdm mdm-cr --type=merge -p '{"spec": {"mdm_matching": {"features": {"source_level_thresholds": {"enabled": false}}}}}' 
Copy to clipboardクリップボードにコピーされました

変更を行った後、CR が調整されるまでに 20 分から 30 分かかる場合があります。 更新された構成を適用するには、 mdm-matching サービス・ポッドも再始動する必要があります。 必要に応じて、これらのポッドを手動で再始動する必要があります。

ソース・レベルのしきい値を再度有効にするには、次のコマンドを実行します。

oc patch mdm mdm-cr --type=merge -p '{"spec": {"mdm_matching": {"features": {"source_level_thresholds": {"enabled": true}}}}}' 
Copy to clipboardクリップボードにコピーされました