Habilidade cognitiva de Pesquisa de Entidade Personalizada

A habilidade de Pesquisa de Entidade Personalizada é usada para detectar ou reconhecer entidades que você define. Durante a execução do conjunto de habilidades, a habilidade procura o texto de uma lista personalizada e definida pelo usuário de palavras e frases. A habilidade usa essa lista para rotular todas as entidades correspondentes encontradas em documentos de origem. A habilidade também dá suporte a um grau de correspondência difusa que pode ser aplicado para localizar correspondências semelhantes, mas não exatas.

Observação

Essa habilidade não está associada a uma API de serviços de IA do Azure, mas requer uma chave de serviços de IA do Azure para permitir mais de 20 transações. Essa habilidade é limitada pelo Azure AI Search.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Limites de dados

• O tamanho máximo do registro de entrada com suporte é de 256 MB. Se você precisar dividir seus dados antes de enviá-los para a habilidade de pesquisa de entidade personalizada, considere o uso da habilidade de Texto Dividido. Se você usar uma habilidade de divisão de texto, defina o comprimento da página como 5000 para obter o melhor desempenho.
• O tamanho máximo da definição de entidade personalizada será de 10 MB se for fornecido como um arquivo externo, especificado por meio do parâmetro "entitiesDefinitionUri".
• Se as entidades são definidas em linha usando o parâmetro "inlineEntitiesDefinition", o tamanho máximo com suporte é de 10 KB.

Parâmetros de habilidades

Os parâmetros diferenciam maiúsculas de minúsculas.

Nome do parâmetro	Descrição
entitiesDefinitionUri	Caminho para um arquivo JSON ou CSV externo que contém todo o texto de destino para correspondência. Essa definição de entidade é lida no início de uma execução do indexador. Todas as atualizações nesse arquivo durante a execução não serão realizadas até que as execuções subsequentes. Esse arquivo deve estar acessível por HTTPS. Confira o Formato da Definição de Entidade Personalizada abaixo para o esquema CSV ou JSON esperado.
inlineEntitiesDefinition	Definições de entidade JSON embutida. Esse parâmetro substitui o parâmetro entitiesDefinitionUri, se presente. Não podem ser fornecidos embutidos mais do que 10 KB de configuração. Confira Definição de Entidade Personalizada abaixo para o esquema JSON esperado.
defaultLanguageCode	(Opcional) Código de linguagem do texto de entrada usado para criar tokens e delinear o texto de entrada. Há suporte para vários idiomas: da, de, en, es, fi, fr, it, pt. O padrão é inglês (en). Se você passar um formato languagecode-countrycode, apenas a parte languagecode do formato é usada.
globalDefaultCaseSensitive	(Opcional) Valor padrão que diferencia maiúsculas e minúsculas para a habilidade. Se o valor defaultCaseSensitive de uma entidade não for especificado, esse valor se tornará o valor defaultCaseSensitive dessa entidade.
globalDefaultAccentSensitive	(Opcional) Valor padrão que diferencia acentos para a habilidade. Se o valor defaultAccentSensitive de uma entidade não for especificado, esse valor se tornará o valor defaultAccentSensitive dessa entidade.
globalDefaultFuzzyEditDistance	(Opcional) Valor de distância de edição difusa padrão para a habilidade. Se o valor defaultFuzzyEditDistance de uma entidade não for especificado, esse valor se tornará o valor defaultFuzzyEditDistance dessa entidade.

Entradas de habilidades

Nome de entrada	Descrição
text	O texto para analisar.
languageCode	Opcional. O padrão é "en".

Saídas de habilidades

Nome de saída

Descrição

entities

Uma matriz de tipos complexos que contêm os seguintes campos: "name": a entidade de nível superior; representa o formulário "normalizado". "id": um identificador exclusivo para a entidade, conforme definido na "Definição de Entidade Personalizada". "description": a descrição da entidade, conforme definido pelo usuário no "Formato de Definição de Entidade Personalizada". "type": o tipo de entidade, conforme definido pelo usuário no "Formato de Definição de Entidade Personalizada". "subtype": o subtipo de entidade, conforme definido pelo usuário no "Formato de Definição de Entidade Personalizada". "matches": uma matriz de tipos complexos que contém: "text" do documento de origem "offset" local onde a correspondência foi encontrada, "length" do texto medido em caracteres "matchDistance" ou o número de caracteres que diferem entre a correspondência e a entidade "name".

Formato de definição de entidade personalizada

Há três abordagens para fornecer a lista de entidades personalizadas para a habilidade de Pesquisa de Entidade Personalizada:

• Arquivo .CSV (codificado em UTF-8)
• Arquivo .JSON (codificado em UTF-8)
• Embutido dentro da definição de habilidade

Se o arquivo de definição estiver em um arquivo .CSV ou .JSON, forneça o caminho completo no parâmetro "entitiesDefinitionUri". O arquivo é baixado no início de cada execução do indexador. Ele deve permanecer acessível até que o indexador pare.

Se você estiver usando uma definição embutida, especifique-a no parâmetro de habilidade "inlineEntitiesDefinition".

Observação

Os indexadores dão suporte a modos de análise especializados para arquivos JSON e CSV. Ao usar a habilidade de pesquisa de entidade personalizada, mantenha "parsingMode" definido como "padrão". A habilidade espera JSON e CSV em um estado não preparado.

Formato CSV

Você pode fornecer a definição das entidades personalizadas para procurar em um arquivo CSV (valor separado por vírgula) fornecendo o caminho para o arquivo e definindo-o no parâmetro de habilidade "entitiesDefinitionUri". O caminho deve estar em um local https. O arquivo de definição pode ter até 10 MB de tamanho.

O formato CSV é simples. Cada linha representa uma entidade exclusiva, conforme mostrado abaixo:

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

Neste caso, existem três entidades que podem ser devolvidas (Bill Gates, Satya Nadella, Microsoft). Os aliases seguem após a entidade principal. Uma correspondência em um alias é agrupada na entidade primária. Por exemplo, se a cadeia de caracteres "William H. Gates" for encontrada em um documento, será devolvida uma correspondência à entidade "Bill Gates".

Formato JSON

Você também pode fornecer a definição das entidades personalizadas que serão procurada em um arquivo JSON. O formato JSON oferece um pouco mais de flexibilidade, pois permite definir as regras de correspondência por termo. Por exemplo, você pode especificar a distância de correspondência difusa (distância Damerau-Levenshtein) para cada termo ou se a correspondência deve ou não diferenciar maiúsculas de minúsculas.

Assim como nos arquivos CSV, você precisa fornecer o caminho para o arquivo JSON e defini-lo no parâmetro de habilidade "entitiesDefinitionUri". O caminho deve estar em um local https. O arquivo de definição pode ter até 10 MB de tamanho.

A definição de lista de entidades personalizadas JSON mais básica pode ser uma lista de entidades para corresponder:

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

Definições mais complexas podem fornecer uma ID, descrição, tipo, subtipo e aliases definidos pelo usuário. Se houver correspondência de um termo de alias, a entidade também será retornada:

[ 
    { 
        "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 }
        ]
    } 
] 

As tabelas abaixo descrevem os parâmetros de configuração que você pode definir ao definir entidades personalizadas:

Nome do campo	Descrição
name	O descritor de entidade de nível superior. As correspondências na saída da habilidade serão agrupadas por esse nome e deverão representar a forma "normalizada" do texto que está sendo encontrado.
description	(Opcional) Esse campo pode ser usado como uma passagem para metadados personalizados sobre os textos correspondentes. O valor desse campo será exibido com cada correspondência de sua entidade na saída da habilidade.
type	(Opcional) Esse campo pode ser usado como uma passagem para metadados personalizados sobre os textos correspondentes. O valor desse campo será exibido com cada correspondência de sua entidade na saída da habilidade.
subtype	(Opcional) Esse campo pode ser usado como uma passagem para metadados personalizados sobre os textos correspondentes. O valor desse campo será exibido com cada correspondência de sua entidade na saída da habilidade.
id	(Opcional) Esse campo pode ser usado como uma passagem para metadados personalizados sobre os textos correspondentes. O valor desse campo será exibido com cada correspondência de sua entidade na saída da habilidade.
caseSensitive	(Opcional) Os padrões são falso. Valor booliano que indica se as comparações com o nome da entidade devem conseguir diferenciar os caracteres maiúsculos de minúsculos. Exemplos de correspondências que não diferenciam maiúsculas e minúsculas em "Microsoft" podem ser: microsoft, microSoft, MICROSOFT
accentSensitive	(Opcional) Os padrões são falso. Valor booliano indicando se as letras acentuadas ou não, como "é" e "e", devem ser idênticas.
fuzzyEditDistance	(Opcional) Os padrões para 0. Valor máximo de 5. Denota o número aceitável de caracteres divergentes que ainda constituem uma correspondência com o nome da entidade. A menor possibilidade de difusão possível para qualquer correspondência fornecida é retornada. Por exemplo, se a distância de edição fosse definida como 3, "Windows 10" ainda corresponderia a "Windows", "Windows10" e "windows 7". Quando a diferenciação de maiúsculas e minúsculas estiver definida como false, as diferenças de maiúsculas e minúsculas NÃO contarão na tolerância de difusão, caso contrário, contarão.
defaultCaseSensitive	(Opcional) Altera o valor padrão de diferenciação de maiúsculas e minúsculas para esta entidade. Ele pode ser usado para alterar o valor padrão de todos os valores de aliases caseSensitive.
defaultAccentSensitive	(Opcional) Altera o valor padrão de diferenciação de acentuação para esta entidade. Ele pode ser usado para alterar o valor padrão de todos os valores de aliases accentSensitive.
defaultFuzzyEditDistance	(Opcional) Altera o valor padrão de distância de edição difusa para esta entidade. Ele pode ser usado para alterar o valor padrão de todos os valores de aliases fuzzyEditDistance.
aliases	(Opcional) Uma matriz de objetos complexos que pode ser usada para especificar grafias alternativas ou sinônimos para o nome da entidade raiz.

Propriedades do alias	Descrição
text	A grafia alternativa ou a representação de algum nome de entidade de destino.
caseSensitive	(Opcional) Age da mesma forma que o parâmetro "caseSensitive" da entidade raiz acima, mas se aplica apenas a este alias.
accentSensitive	(Opcional) Age da mesma forma que o parâmetro "accentSensitive" da entidade raiz acima, mas se aplica apenas a este alias.
fuzzyEditDistance	(Opcional) Age da mesma forma que o parâmetro "fuzzyEditDistance" da entidade raiz acima, mas se aplica apenas a este alias.

Formato embutido

Em alguns casos, pode ser mais conveniente inserir a definição de entidade personalizada para que ela esteja embutida com a definição de habilidade. Você pode usar o mesmo formato JSON que o descrito acima, exceto que ele está incluído na definição de habilidade. Somente as configurações com menos de 10 KB de tamanho (tamanho serializado) podem ser definidas embutidas.

Exemplo de definição de habilidade

Uma definição de habilidade de amostra usando um formato embutido é mostrado abaixo:

  {
    "@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"
      }
    ]
  }

Como alternativa, você pode apontar para um arquivo de definição de entidades externas. Uma definição de habilidade de amostra usando o formato entitiesDefinitionUri é mostrado abaixo:

  {
    "@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"
      }
    ]
  }

Definição de índice de exemplo

Esta seção fornece uma definição de índice de exemplo. As "entidades" e as "correspondências" são matrizes de tipos complexos. Você pode ter várias entidades por documento e várias correspondências para cada entidade.

{
  "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,
        }
      ]
    }
  ]
}

Dados de entrada de exemplo

{
    "values": [
      {
        "recordId": "1",
        "data":
           {
             "text": "The company, Microsoft, was founded by Bill Gates. Microsoft's gaming console is called Xbox",
             "languageCode": "en"
           }
      }
    ]
}

Saída de exemplo

  { 
    "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 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  } 

Warnings

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

Esse aviso será emitido se o número de correspondências detectadas for maior que o máximo permitido. Não serão retornadas mais correspondências duplicadas. Se você precisar de um limite mais alto, poderá registrar um tíquete de suporte para obter assistência com seu caso de uso individual.

Confira também

• Habilidades internas
• Como definir um conjunto de qualificações
• Habilidade de Reconhecimento de Entidade (para pesquisar entidades conhecidas)