カスタムエンティティの参照認知スキル

[アーティクル]
09/01/2024

カスタムエンティティの参照スキルは、定義したエンティティを検出または認識するために使用されます。このスキルでは、スキルセットの実行中に、ユーザーが定義したカスタムの単語と語句の一覧からテキストを検索します。このスキルでは、この一覧を使用して、ソースドキュメント内で見つかった一致するエンティティにラベルを付けます。このスキルでは、ある程度のあいまい一致もサポートされており、類似しているが完全一致ではない一致を見つけるために適用できます。

Note

このスキルは Azure AI サービス API にバインドされていませんが、20 を超えるトランザクションを許可するには Azure AI サービスキーが必要です。このスキルは、Azure AI Search による課金対象となります。

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

データ制限

サポートされる入力レコードの最大サイズは 256 MB です。カスタムエンティティの参照スキルにデータを送信する前にデータを分割する必要がある場合は、テキスト分割スキルを使用することをお勧めします。テキスト分割スキルを使用する場合は、最適なパフォーマンスを得るためにページ長を 5000 に設定します。
"entitiesDefinitionUri" パラメーターを使用して指定された外部ファイルとして指定されている場合、カスタムエンティティ定義の最大サイズは 10 MB です。
エンティティが "inlineEntitiesDefinition" パラメーターを使用してインラインで定義されている場合、最大サイズは 10 KB です。

スキルのパラメーター

パラメーターの大文字と小文字は区別されます。

パラメーター名	説明
`entitiesDefinitionUri`	照合対象のすべてのターゲットテキストを含む外部 JSON または CSV ファイルのパス。このエンティティ定義は、インデクサー実行の開始時に読み取られます。このファイルの実行中に行われた更新は、後続の実行まで反映されません。このファイルには、HTTPS 経由でアクセスできる必要があります。想定される CSV または JSON スキーマについては、後述の「カスタムエンティティ定義の形式」を参照してください。
`inlineEntitiesDefinition`	インライン JSON エンティティの定義。このパラメーターは、entitiesDefinitionUri パラメーター (存在する場合) よりも優先されます。 10 KB を超える構成をインラインで指定することはできません。想定される JSON スキーマについては、後述する「カスタムエンティティ定義の形式」を参照してください。
`defaultLanguageCode`	(省略可能) 入力テキストのトークン化と記述に使用される入力テキストの言語コード。次の言語がサポートされます。`da, de, en, es, fi, fr, it, pt` 既定値は英語 (`en`) です。 `languagecode-countrycode` 形式を渡す場合、その形式の `languagecode` 部分のみが使用されます。
`globalDefaultCaseSensitive`	(省略可能) スキルの大文字と小文字の区別に関する既定値。エンティティの `defaultCaseSensitive` 値が指定されない場合、この値がそのエンティティの `defaultCaseSensitive` 値になります。
`globalDefaultAccentSensitive`	(省略可能) スキルのアクセントの区別に関する既定値。エンティティの `defaultAccentSensitive` 値が指定されない場合、この値がそのエンティティの `defaultAccentSensitive` 値になります。
`globalDefaultFuzzyEditDistance`	(省略可能) スキルのあいまい編集距離の既定値。エンティティの `defaultFuzzyEditDistance` 値が指定されない場合、この値がそのエンティティの `defaultFuzzyEditDistance` 値になります。

スキルの入力

入力名	説明
`text`	分析対象テキストです。
`languageCode`	省略可能。既定値は `"en"` です。

スキルの出力

出力名説明

出力名	説明
`entities`	次のフィールドが含まれる複合型の配列。 `"name"`: 最上位のエンティティ。"正規化された" 形式を表します。 `"id"`: "カスタムエンティティ定義" で定義されたエンティティの一意識別子。 `"description"`: "カスタムエンティティ定義の形式" でユーザーによって定義されたエンティティの説明。 `"type"`: "カスタムエンティティ定義の形式" でユーザーによって定義されたエンティティ型。 `"subtype"`:"カスタムエンティティ定義形式" でユーザーによって定義されたサブエンティティ型。 `"matches"`: 以下を含む複合型の配列: ソースドキュメントからの `"text"` 一致が見つかった `"offset"` の場所文字で測定されたテキストの `"length"` `"matchDistance"` または、一致とエンティティ `"name"` の間で異なる文字数。

entities

次のフィールドが含まれる複合型の配列。

"name": 最上位のエンティティ。"正規化された" 形式を表します。
"id": "カスタムエンティティ定義" で定義されたエンティティの一意識別子。
"description": "カスタムエンティティ定義の形式" でユーザーによって定義されたエンティティの説明。
"type": "カスタムエンティティ定義の形式" でユーザーによって定義されたエンティティ型。
"subtype":"カスタムエンティティ定義形式" でユーザーによって定義されたサブエンティティ型。
"matches": 以下を含む複合型の配列:
- ソースドキュメントからの "text"
- 一致が見つかった "offset" の場所
- 文字で測定されたテキストの "length"
- "matchDistance" または、一致とエンティティ "name" の間で異なる文字数。

カスタムエンティティ定義の形式

カスタムエンティティの一覧をカスタムエンティティの参照スキルに指定するには、次の 3 つの方法があります。

.CSV ファイル (UTF-8 エンコード)
.JSON ファイル (UTF-8 エンコード)
スキル定義内のインライン

定義ファイルが .CSV または .JSON ファイルである場合は、"entitiesDefinitionUri" パラメーターに完全なパスを指定します。ファイルは各インデクサーの実行の開始時にダウンロードされます。インデクサーが停止するまで、アクセス可能な状態を維持する必要があります。

インライン定義を使用している場合は、"inlineEntitiesDefinition" スキルパラメーターで指定します。

Note

インデクサーでは、JSON と CSV ファイルの特殊な解析モードがサポートされます。カスタムエンティティ参照スキルを使用する場合は、"parsingMode" を "default" に設定したままにします。このスキルでは、JSON と CSV が解析されていない状態である必要があります。

CSV 形式

検索するカスタムエンティティの定義をコンマ区切り値 (CSV) ファイルで指定するには、ファイルのパスを指定し、それを "entitiesDefinitionUri" スキルパラメーターに設定します。このパスは、https の場所にある必要があります。定義ファイルの最大サイズは 10 MB です。

CSV 形式は単純です。次に示すように、各行は一意のエンティティを表します。

Bill Gates, BillG, William H. Gates
Microsoft, MSFT
Satya Nadella

この場合、3 つのエンティティ (Bill Gates、Satya Nadella、Microsoft) が返される可能性があります。エイリアスはメインエンティティの後に続きます。エイリアスの一致は、プライマリエンティティの下にバンドルされます。たとえば、文字列 "William H. Gates" がドキュメントで見つかった場合、"Bill Gates" エンティティの一致が返されます。

JSON 形式

JSON ファイルで検索するカスタムエンティティの定義を指定することもできます。 JSON 形式では用語ごとに照合ルールを定義できるため、やや柔軟に利用できます。たとえば、各用語のあいまい一致距離 (ダメラウレーベンシュタイン距離)、または照合で大文字と小文字を区別するかどうかを指定できます。

CSV ファイルと同様に、JSON ファイルへのパスを指定し、"entitiesDefinitionUri" スキルパラメーターで設定する必要があります。このパスは、https の場所にある必要があります。定義ファイルの最大サイズは 10 MB です。

最も基本的な JSON カスタムエンティティ一覧定義としては、照合するエンティティの一覧を使用できます。

[ 
    { 
        "name" : "Bill Gates"
    }, 
    { 
        "name" : "Microsoft"
    }, 
    { 
        "name" : "Satya Nadella"
    }
]

より複雑な定義では、ユーザー定義 ID、説明、型、サブ型、エイリアスを指定できます。別名の用語が一致した場合、そのエンティティも返されます。

[ 
    { 
        "name" : "Bill Gates",
        "description" : "Microsoft founder." ,
        "aliases" : [ 
            { "text" : "William H. Gates", "caseSensitive" : false },
            { "text" : "BillG", "caseSensitive" : true }
        ]
    }, 
    { 
        "name" : "Xbox One", 
        "type": "Hardware",
        "subtype" : "Gaming Device",
        "id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
        "description" : "The Xbox One product"
    }, 
    { 
        "name" : "LinkedIn" , 
        "description" : "The LinkedIn company", 
        "id" : "differentIdentifyingScheme123", 
        "fuzzyEditDistance" : 0 
    }, 
    { 
        "name" : "Microsoft" , 
        "description" : "Microsoft Corporation", 
        "id" : "differentIdentifyingScheme987", 
        "defaultCaseSensitive" : false, 
        "defaultFuzzyEditDistance" : 1, 
        "aliases" : [ 
            { "text" : "MSFT", "caseSensitive" : true }
        ]
    } 
]

カスタムエンティティを定義するときに設定できる構成パラメーターについて、以下の表で説明します。

フィールド名	説明
`name`	最上位のエンティティ記述子。スキル出力内の一致は、この名前でグループ化されます。これは、検出されるテキストの "正規化された" 形式を表します。
`description`	(省略可能) このフィールドは、一致したテキストに関するカスタムメタデータのパススルーとして使用できます。このフィールドの値は、スキル出力内でエンティティが一致するたびに表示されます。
`type`	(省略可能) このフィールドは、一致したテキストに関するカスタムメタデータのパススルーとして使用できます。このフィールドの値は、スキル出力内でエンティティが一致するたびに表示されます。
`subtype`	(省略可能) このフィールドは、一致したテキストに関するカスタムメタデータのパススルーとして使用できます。このフィールドの値は、スキル出力内でエンティティが一致するたびに表示されます。
`id`	(省略可能) このフィールドは、一致したテキストに関するカスタムメタデータのパススルーとして使用できます。このフィールドの値は、スキル出力内でエンティティが一致するたびに表示されます。
`caseSensitive`	(省略可能) 既定値は false です。エンティティ名との比較で大文字と小文字を区別するかどうかを示すブール値。 "Microsoft" の大文字と小文字を区別しない一致の例として、microsoft、microSoft、MICROSOFT があります
`accentSensitive`	(省略可能) 既定値は false です。 "é" と "e" などアクセント記号が付いた文字と付いてない文字を同一と見なすかどうかを示すブール値。
`fuzzyEditDistance`	(省略可能) 既定値は 0 です。最大値は 5 です。エンティティ名との一致を構成する上で、許容する不一致文字の数を指定します。指定した一致に対して可能な限り最小のあいまいさが返されます。たとえば、編集距離が 3 に設定されている場合、"Windows 10" は "Windows"、"Windows10"、"windows 7" と一致します。大文字と小文字の区別が false に設定されている場合、大文字と小文字の違いはあいまいさの許容値にはカウントされませんが、それ以外の場合はカウントされます。
`defaultCaseSensitive`	(省略可能) このエンティティの既定の大文字と小文字の区別の値を変更します。すべての別名の caseSensitive 値の既定値を変更するために使用できます。
`defaultAccentSensitive`	(省略可能) このエンティティの既定のアクセントの区別の値を変更します。すべての別名の accentSensitive 値の既定値を変更するために使用できます。
`defaultFuzzyEditDistance`	(省略可能) このエンティティの既定のあいまい編集距離値を変更します。すべての別名の fuzzyEditDistance 値の既定値を変更するために使用できます。
`aliases`	(省略可能) ルートエンティティ名の代替のスペルまたは同義語を指定するために使用できる複雑なオブジェクトの配列。

別名のプロパティ	説明
`text`	一部のターゲットエンティティ名の代替のスペルまたは表現。
`caseSensitive`	(省略可能) 前述のルートエンティティ "caseSensitive" パラメーターと同じように機能しますが、この別名のみに適用されます。
`accentSensitive`	(省略可能) 前述のルートエンティティ "accentSensitive" パラメーターと同じように機能しますが、この別名のみに適用されます。
`fuzzyEditDistance`	(省略可能) 前述のルートエンティティ "fuzzyEditDistance" パラメーターと同じように機能しますが、この別名のみに適用されます。

インライン形式

場合によっては、カスタムエンティティ定義を埋め込み、スキル定義にインライン化する方が便利なことがあります。スキル定義内に含まれている点を除き、上記と同じ JSON 形式を使用できます。サイズが 10 KB (シリアル化されたサイズ) 未満の構成のみをインラインで定義できます。

サンプルスキル定義

インライン形式を使用したスキル定義例を次に示します。

  {
    "@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
    "context": "/document",
    "inlineEntitiesDefinition": 
    [
      { 
        "name" : "Bill Gates",
        "description" : "Microsoft founder." ,
        "aliases" : [ 
            { "text" : "William H. Gates", "caseSensitive" : false },
            { "text" : "BillG", "caseSensitive" : true }
        ]
      }, 
      { 
        "name" : "Xbox One", 
        "type": "Hardware",
        "subtype" : "Gaming Device",
        "id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
        "description" : "The Xbox One product"
      }
    ],    
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "entities",
        "targetName": "matchedEntities"
      }
    ]
  }

または、外部エンティティ定義ファイルをポイントすることもできます。 entitiesDefinitionUri 形式を使用したスキル定義のサンプルを以下に示します。

  {
    "@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
    "context": "/document",
    "entitiesDefinitionUri": "https://myblobhost.net/keyWordsConfig.csv",    
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "entities",
        "targetName": "matchedEntities"
      }
    ]
  }

インデックス定義のサンプル

このセクションではインデックス定義のサンプルを示します。 "エンティティ" と "一致" はどちらも複合型の配列です。ドキュメントごとに複数のエンティティ、および各エンティティに対して複数の一致を使用できます。

{
  "name": "entities",
  "type": "Collection(Edm.ComplexType)",
  "fields": [
    {
      "name": "name",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": true,
      "sortable": false,
    },
    {
      "name": "id",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "description",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": true,
      "sortable": false,
    },
    {
      "name": "type",
      "type": "Edm.String",
      "facetable": true,
      "filterable": true,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "subtype",
      "type": "Edm.String",
      "facetable": true,
      "filterable": true,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "matches",
      "type": "Collection(Edm.ComplexType)",
      "fields": [
        {
          "name": "text",
          "type": "Edm.String",
          "facetable": false,
          "filterable": false,
          "retrievable": true,
          "searchable": true,
          "sortable": false,
        },
        {
          "name": "offset",
          "type": "Edm.Int32",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        },
        {
          "name": "length",
          "type": "Edm.Int32",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        },
        {
          "name": "matchDistance",
          "type": "Edm.Double",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        }
      ]
    }
  ]
}

サンプルの入力データ

{
    "values": [
      {
        "recordId": "1",
        "data":
           {
             "text": "The company, Microsoft, was founded by Bill Gates. Microsoft's gaming console is called Xbox",
             "languageCode": "en"
           }
      }
    ]
}

サンプル出力

  { 
    "values" : 
    [ 
      { 
        "recordId": "1", 
        "data" : { 
          "entities": [
            { 
              "name" : "Microsoft", 
              "description" : "This document refers to Microsoft the company", 
              "id" : "differentIdentifyingScheme987", 
              "matches" : [ 
                { 
                  "text" : "microsoft", 
                  "offset" : 13, 
                  "length" : 9, 
                  "matchDistance" : 0 
                }, 
                { 
                  "text" : "Microsoft",
                  "offset" : 49, 
                  "length" : 9, 
                  "matchDistance" : 0
                }
              ] 
            },
            { 
              "name" : "Bill Gates",
              "description" : "William Henry Gates III, founder of Microsoft.", 
              "matches" : [
                { 
                  "text" : "Bill Gates",
                  "offset" : 37, 
                  "length" : 10,
                  "matchDistance" : 0 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  }

Warnings

"Reached maximum capacity for matches, skipping all further duplicate matches."

この警告は、検出された一致の数が許容される最大値を超えた場合に出力されます。これ以上重複する一致は返されません。より高いしきい値が必要な場合は、個々のユースケースに関するサポートチケットを提出できます。

次の方法で共有

カスタムエンティティの参照認知スキル

@odata.type

データ制限

スキルのパラメーター

スキルの入力

スキルの出力

カスタムエンティティ定義の形式

CSV 形式

JSON 形式

インライン形式

サンプルスキル定義

インデックス定義のサンプル

サンプルの入力データ

サンプル出力

Warnings

関連項目

フィードバック

その他のリソース

次の方法で共有

カスタム エンティティの参照認知スキル

@odata.type

データ制限

スキルのパラメーター

スキルの入力

スキルの出力

カスタム エンティティ定義の形式

CSV 形式

JSON 形式

インライン形式

サンプル スキル定義

インデックス定義のサンプル

サンプルの入力データ

サンプル出力

Warnings

関連項目

フィードバック

その他のリソース

カスタムエンティティの参照認知スキル

カスタムエンティティ定義の形式

サンプルスキル定義