Когнитивный навык поиска настраиваемых сущностей

Статья
10/20/2023

Навык поиска пользовательских сущностей используется для обнаружения или распознавания определенных сущностей. Во время выполнения набора навыков навык ищет текст из пользовательского пользовательского списка слов и фраз. Навык использует этот список для метки любых соответствующих сущностей, найденных в исходных документах. Кроме того, этот навык поддерживает определенный уровень нечеткого соответствия, что позволяет искать похожие, но не точно совпадающие фрагменты.

Примечание.

Этот навык не привязан к API служб искусственного интеллекта Azure, но требует ключа служб ИИ Azure, чтобы разрешить более 20 транзакций. Этот навык измеряется поиском ИИ Azure.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Ограничения данных

Максимальный поддерживаемый размер входной записи составляет 256 МБ. Если вам нужно разбить данные перед отправкой, воспользуйтесь навыком разделения текста. Если вы используете навык разделения текста, задайте длину страницы равным 5000 для оптимальной производительности.
Максимальный размер определения пользовательской сущности составляет 10 МБ, если он предоставляется как внешний файл, указанный в параметре EntityDefinitionUri.
Если сущности определены встроенными с помощью параметра inlineEntitiesDefinition, максимальный размер составляет 10 КБ.

Параметры навыков

Параметры зависят от регистра.

Наименование параметра	Description
`entitiesDefinitionUri`	Путь к внешнему JSON-файлу или CSV-файлу, который содержит весь целевой текст для сопоставления. Это определение сущности считывается в начале работы индексатора. Если внести изменения в файл, когда индексатор уже запущен, они будут реализованы только после следующего запуска. Этот файл должен быть доступен по протоколу HTTPS. Дополнительные сведения о ожидаемой схеме CSV или JSON см . в формате определения пользовательской сущности ниже.
`inlineEntitiesDefinition`	Встроенные в JSON-файл определения сущностей. Этот параметр заменяет параметр entitiesDefinitionUri при его наличии. Объем встроенных данных не должен превышать 10 КБ. Схему JSON-файла можно посмотреть в разделе Определение настраиваемых сущностей ниже.
`defaultLanguageCode`	(Необязательно) Параметр для определения кода языка входного текста, который используется для его токенизации и разделения. Поддерживаются следующие языки: `da, de, en, es, fi, fr, it, pt`. По умолчанию установлен английский язык (`en`). При передаче `languagecode-countrycode` формата используется только `languagecode` часть формата.
`globalDefaultCaseSensitive`	(Необязательно) Значение навыка по умолчанию для учета регистра. Если `defaultCaseSensitive` значение сущности не указано, это значение станет значением `defaultCaseSensitive` для этой сущности.
`globalDefaultAccentSensitive`	(Необязательно) Значение навыка по умолчанию для учета диакритических знаков. Если `defaultAccentSensitive` значение сущности не указано, это значение станет значением `defaultAccentSensitive` для этой сущности.
`globalDefaultFuzzyEditDistance`	(Необязательно) Значение нечеткого редакционного расстояния по умолчанию. Если `defaultFuzzyEditDistance` значение сущности не указано, это значение станет значением `defaultFuzzyEditDistance` для этой сущности.

Входные данные навыков

Ввод имени	Description
`text`	Текст для анализа.
`languageCode`	Необязательно. По умолчанию — `"en"`.

Выходные данные навыка

Имя вывода Description

Имя вывода	Description
`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 МБ.

CSV — это простой формат. Каждая строка представляет собой уникальную сущность, как показано ниже:

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

В этом случае есть три сущности, которые можно вернуть (Билл Гейтс, Сатья Наделла, Майкрософт). Псевдонимы следуют после основной сущности. Совпадение с псевдонимом упаковается в основную сущность. Например, если строка "Уильям H. Гейтс" найдена в документе, будет возвращено соответствие сущности "Билл Гейтс".

Формат JSON

Вы также можете определять настраиваемые сущности в JSON-файле. Формат JSON обеспечивает более высокую гибкость, так как позволяет определять правила сопоставления для каждого термина. Например, вы можете указывать расстояние нечеткого соответствия (расстояние Дамерау — Левенштейна) для каждого термина или определять, следует ли учитывать регистр.

Как и в CSV-файлах, необходимо указать путь к JSON-файлу и задать его в параметре навыка entitiesDefinitionUri. Следует использовать HTTPS-адрес. Максимальный размер файла для определения — 10 МБ.

Самое простое определение списка настраиваемых сущностей в формате 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 }
        ]
    } 
]

В таблицах ниже описаны параметры конфигурации, которые можно задать при определении пользовательских сущностей:

Имя поля	Description
`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`	(Необязательно) Массив из сложных объектов, который позволяет указывать альтернативное написание или синонимы для изначального названия сущности.

Свойства псевдонимов	Description
`text`	Альтернативное написание или представление названия целевой сущности.
`caseSensitive`	(Необязательно) Играет ту же роль, что и параметр caseSensitive изначальной сущности, описанный выше, однако применяется только к одному псевдониму.
`accentSensitive`	(Необязательно) Играет ту же роль, что и параметр accentSensitive изначальной сущности, описанный выше, однако применяется только к одному псевдониму.
`fuzzyEditDistance`	(Необязательно) Играет ту же роль, что и параметр uzzyEditDistance изначальной сущности, описанный выше, однако применяется только к одному псевдониму.

Встроенный формат

В некоторых случаях может быть удобнее внедрить определение пользовательской сущности, чтобы оно соответствовало определению навыка. Вы можете использовать тот же формат JSON, что и описанный выше формат, за исключением того, что он включен в определение навыка. Встраивать можно конфигурации размером меньше 10 КБ (сериализованный размер).

Пример определения навыка

Ниже приведен пример определения навыка с использованием встроенного формата.

  {
    "@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."

Это предупреждение появится, если количество найденных сопоставлений превысит разрешенный лимит. Больше повторяющихся совпадений не будет возвращено. Если вам нужен более высокий порог, вы можете отправить запрос в службу поддержки для получения помощи в вашем индивидуальном варианте использования.