Compartir a través de

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

  • Artículo

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

注意

此技能不绑定到 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" 之间不同的字符数。

自定义实体定义格式

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

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

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

另请参阅