“自定义实体查找”认知技能
自定义实体查找技能用于检测或识别定义的实体。 在技能组执行期间,此技能可在用户自定义的单词和短语列表中查找文本。 该技能使用此列表来标记在源文档中找到的所有匹配实体。 该技能还支持一定程度的模糊匹配,应用此匹配方法可以查找类似但不完全相同的匹配项。
注意
此技能不绑定到 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 |
复杂类型的数组,包含以下字段:
|
自定义实体定义格式
可通过三种方法向自定义实体查找技能提供自定义实体列表:
- .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."
如果检测到的匹配项数大于允许的最大值,则将发出此警告。 不会再返回重复匹配项。 如果需要更高的阈值,可以提交支持票证以获取针对个人用例的帮助。