“自定义实体查找”认知技能

项目
12/11/2023

自定义实体查找技能用于检测或识别定义的实体。在技能组执行期间，此技能可在用户自定义的单词和短语列表中查找文本。该技能使用此列表来标记在源文档中找到的所有匹配实体。该技能还支持一定程度的模糊匹配，应用此匹配方法可以查找类似但不完全相同的匹配项。

注意

此技能不绑定到 Azure AI 服务 API，但需要 Azure AI 服务密钥才能允许超过 20 个事务。此技能按 Azure AI 搜索进行计量。

@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" 之间不同的字符数。

自定义实体定义格式

可通过三种方法向自定义实体查找技能提供自定义实体列表：

.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

在这种情况下，可以返回三个实体（Bill Gates、Satya Nadella、Microsoft）。别名跟在主实体之后。别名上的匹配项捆绑在主实体下。例如，如果在文档中找到字符串“William H. Gates”，则会返回“Bill Gates”实体的匹配项。

JSON 格式

还可以提供自定义实体的定义，以查找 JSON 文件中的内容。 JSON 格式提供的灵活性要大一些，因为它允许按字词定义匹配规则。例如，可为每个字词指定模糊匹配距离（Damerau-Levenshtein 距离），或者匹配是否要区分大小写。

与 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. Azure's gaming console is called Xbox",
             "languageCode": "en"
           }
      }
    ]
}

示例输出

  { 
    "values" : 
    [ 
      { 
        "recordId": "1", 
        "data" : { 
          "entities": [
            { 
              "name" : "Microsoft", 
              "description" : "This document refers to Azure 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."

如果检测到的匹配项数大于允许的最大值，则将发出此警告。不会再返回重复匹配项。如果需要更高的阈值，可以提交支持票证以获取针对个人用例的帮助。