自定義實體查閱認知技能

發行項
03/11/2024

自定義 實體查閱 技能可用來偵測或辨識您定義的實體。在技能集執行期間，技能會從自定義的使用者定義單字和片語清單尋找文字。技能會使用此清單來標記來源檔內找到的任何相符實體。技能也支援一定程度的模糊比對，可套用以尋找類似但並非完全相符的相符專案。

注意

此技能不會系結至 Azure AI 服務 API，但需要 Azure AI 服務密鑰，才能允許超過 20 筆交易。此技能是由 Azure AI 搜尋計量。

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

資料限制

支援的輸入記錄大小上限為 256 MB。如果您需要在將數據傳送至自定義實體查閱技能之前中斷數據，請考慮使用文字分割技能。如果您使用文字分割技能，請將頁面長度設定為 5000 以獲得最佳效能。
如果自定義實體定義是以外部檔案的形式提供，則自定義實體定義的大小上限為 10 MB，透過 “entitiesDefinitionUri” 參數指定。
如果使用「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"之間的差異字元數。

自定義實體定義格式

提供自訂實體清單給自定義實體查閱技能的方法有三種：

.CSV 檔案（UTF-8 編碼）
.JSON 檔案（UTF-8 編碼）
技能定義內的內嵌

如果定義檔位於中，則為。CSV 或。JSON 檔案，提供「entitiesDefinitionUri」參數中的完整路徑。檔案會在每個索引器執行開始時下載。它必須保持可存取性，直到索引器停止為止。

如果您使用內嵌定義，請在「inlineEntitiesDefinition」技能參數下指定它。

注意

索引器支援 JSON 和 CSV 檔案的特殊剖析模式。使用自定義實體查閱技能時，請將「parsingMode」設定為「default」。。技能預期 JSON 和 CSV 處於未剖析的狀態。

CSV 格式

您可以提供自定義實體的定義，以在逗號分隔值（CSV）檔案中尋找，方法是提供檔案的路徑，並將其設定為 “entitiesDefinitionUri” 技能參數。路徑應該位於 HTTPs 位置。定義檔的大小上限為 10 MB。

CSV 格式很簡單。每一行都代表唯一的實體，如下所示：

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

在此情況下，有三個實體可以傳回（比爾·蓋茨、Satya Nadella、Microsoft）。別名會跟在主要實體之後。別名上的相符項目會組合在主要實體之下。例如，如果在檔中找到「William H. Gates」字串，則會傳回「Bill Gates」實體的相符專案。

JSON 格式

您也可以提供自定義實體的定義，以在 JSON 檔案中尋找。 JSON 格式可讓您有更多的彈性，因為它可讓您定義每個詞彙的比對規則。例如，您可以為每個字詞指定模糊比對距離（Damerau-Levenshtein distance），或比對是否應該區分大小寫。

就像 CSV 檔案一樣，您必須提供 JSON 檔案的路徑，並在 “entitiesDefinitionUri” 技能參數中加以設定。路徑應該位於 HTTPs 位置。定義檔的大小上限為 10 MB。

最基本的 JSON 自定義實體清單定義可以是符合的實體清單：

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

更複雜的定義可以提供使用者定義的標識碼、描述、類型、子類型和別名。如果符合別名字詞，也會傳回實體：

[ 
    { 
        "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`	（選擇性）變更此實體的預設腔調敏感度值。它可以用來變更所有別名的預設值不區分值。
`defaultFuzzyEditDistance`	（選擇性）變更此實體的預設模糊編輯距離值。它可以用來變更所有別名模糊EditDistance 值的預設值。
`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 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  }

警告

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

如果偵測到的相符項目數目大於允許的最大值，就會發出此警告。不會再傳回重複的相符專案。如果您需要較高的閾值，您可以提出支援票證，以取得個別使用案例的協助。