Habilidade cognitiva de Pesquisa de Entidade Personalizada

A habilidade Pesquisa de Entidade Personalizada é usada para detetar ou reconhecer entidades definidas por você. Durante a execução do conjunto de habilidades, a habilidade procura texto a partir de uma lista personalizada e definida pelo usuário de palavras e frases. A habilidade usa essa lista para rotular quaisquer entidades correspondentes encontradas em documentos de origem. A habilidade também suporta um grau de correspondência difusa que pode ser aplicada para encontrar correspondências que são semelhantes, mas não exatas.

Nota

Essa habilidade não está vinculada 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 é medida pelo Azure AI Search.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Limites de dados

• O tamanho máximo de registro de entrada suportado é de 256 MB. Se você precisar dividir seus dados antes de enviá-los para a habilidade de pesquisa de entidade personalizada, considere usar a habilidade Divisão de texto. 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 é de 10 MB se for fornecido como um arquivo externo, especificado através do parâmetro "entitiesDefinitionUri".
• Se as entidades forem definidas em linha usando o parâmetro "inlineEntitiesDefinition", o tamanho máximo será de 10 KB.

Parâmetros de habilidade

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

Nome do parâmetro	Description
entitiesDefinitionUri	Caminho para um arquivo JSON ou CSV externo contendo todo o texto de destino a ser correspondido. Esta definição de entidade é lida no início de uma execução de indexador; Quaisquer atualizações para este arquivo no meio da execução não serão realizadas até execuções subsequentes. Este ficheiro tem de estar acessível através de HTTPS. Consulte Formato de definição de entidade personalizada abaixo para obter o esquema CSV ou JSON esperado.
inlineEntitiesDefinition	Definições de entidade JSON embutidas. Este parâmetro substitui o parâmetro entitiesDefinitionUri, se presente. Não mais do que 10 KB de configuração podem ser fornecidos em linha. Consulte Definição de entidade personalizada abaixo para obter o esquema JSON esperado.
defaultLanguageCode	(Opcional) Código de idioma do texto de entrada usado para tokenizar e delinear o texto de entrada. Os seguintes idiomas são suportados: da, de, en, es, fi, fr, it, pt. O padrão é inglês (en). Se você passar um languagecode-countrycode formato, apenas a languagecode parte do formato será usada.
globalDefaultCaseSensitive	(Opcional) Valor padrão sensível a maiúsculas e minúsculas para a habilidade. Se defaultCaseSensitive o valor de uma entidade não for especificado, esse valor se tornará o defaultCaseSensitive valor dessa entidade.
globalDefaultAccentSensitive	(Opcional) Valor sensível ao acento padrão para a habilidade. Se defaultAccentSensitive o valor de uma entidade não for especificado, esse valor se tornará o defaultAccentSensitive valor dessa entidade.
globalDefaultFuzzyEditDistance	(Opcional) Valor de distância de edição difusa padrão para a habilidade. Se defaultFuzzyEditDistance o valor de uma entidade não for especificado, esse valor se tornará o defaultFuzzyEditDistance valor dessa entidade.

Contributos para as competências

Nome de entrada	Description
text	O texto a analisar.
languageCode	Opcional. A predefinição é "en".

Resultados em termos de competências

Nome da saída

Description

entities

Uma matriz de tipos complexos que contém os seguintes campos: "name": A entidade de nível superior; representa a forma "normalizada". "id": Um identificador exclusivo para a entidade, conforme definido na "Definição de entidade personalizada". "description": Descrição da entidade conforme definido pelo usuário no "Custom Entity Definition Format". "type": Tipo de entidade conforme definido pelo usuário no "Formato de definição de entidade personalizada". "subtype": 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 Pesquisa de Entidade Personalizada:

• . Arquivo CSV (codificado em UTF-8)
• . Arquivo JSON (codificado em UTF-8)
• Inline 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 sob o parâmetro de habilidade "inlineEntitiesDefinition".

Nota

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

Formato CSV

Você pode fornecer a definição das entidades personalizadas a serem procuradas em um arquivo CSV (Comma-Separated Value) 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 única, como mostrado abaixo:

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

Neste caso, há 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 sob a entidade principal. Por exemplo, se a cadeia de caracteres "William H. Gates" for encontrada em um documento, uma correspondência para a entidade "Bill Gates" será retornada.

Formato JSON

Você também pode fornecer a definição das entidades personalizadas a serem procuradas em um arquivo JSON. O formato JSON dá-lhe um pouco mais de flexibilidade, uma vez que lhe permite definir 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 diferenciar maiúsculas de minúsculas ou não.

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 mais básica da lista de entidades personalizadas JSON pode ser uma lista de entidades a serem correspondidas:

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

Definições mais complexas podem fornecer um ID, descrição, tipo, subtipo e aliases definidos pelo usuário. Se um termo de alias for correspondido, 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	Description
name	O descritor de entidade de nível superior. As correspondências na saída de habilidade serão agrupadas por este nome, e ele deve representar a forma "normalizada" do texto que está sendo encontrado.
description	(Opcional) Este campo pode ser usado como uma passagem para metadados personalizados sobre o(s) texto(s) correspondente(s). O valor deste campo aparecerá com cada correspondência de sua entidade na saída de habilidade.
type	(Opcional) Este campo pode ser usado como uma passagem para metadados personalizados sobre o(s) texto(s) correspondente(s). O valor deste campo aparecerá com cada correspondência de sua entidade na saída de habilidade.
subtype	(Opcional) Este campo pode ser usado como uma passagem para metadados personalizados sobre o(s) texto(s) correspondente(s). O valor deste campo aparecerá com cada correspondência de sua entidade na saída de habilidade.
id	(Opcional) Este campo pode ser usado como uma passagem para metadados personalizados sobre o(s) texto(s) correspondente(s). O valor deste campo aparecerá com cada correspondência de sua entidade na saída de habilidade.
caseSensitive	(Opcional) O padrão é false. Valor booleano que indica se as comparações com o nome da entidade devem ser sensíveis à caixa de caracteres. Exemplos de correspondências que não diferenciam maiúsculas de minúsculas de "Microsoft" podem ser: microsoft, microSoft, MICROSOFT
accentSensitive	(Opcional) O padrão é false. Valor booleano que indica se letras acentuadas e não acentuadas, como 'é' e 'e', devem ser idênticas.
fuzzyEditDistance	(Opcional) O padrão é 0. Valor máximo de 5. Indica o número aceitável de caracteres divergentes que ainda constituiriam uma correspondência com o nome da entidade. A menor imprecisão possível para qualquer partida é devolvida. Por exemplo, se a distância de edição estiver definida como 3, "Windows 10" ainda corresponderia a "Windows", "Windows10" e "windows 7". Quando a diferenciação de maiúsculas e minúsculas é definida como falsa, as diferenças entre maiúsculas e minúsculas NÃO contam para a tolerância difusa, mas de outra forma contam.
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 aliases valores caseSensi.
defaultAccentSensitive	(Opcional) Altera o valor de sensibilidade de acento padrão para esta entidade. Ele pode ser usado para alterar o valor padrão de todos os aliases accentSensitive valores.
defaultFuzzyEditDistance	(Opcional) Altera o valor de distância de edição difusa padrão 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 podem ser usados para especificar grafias alternativas ou sinônimos para o nome da entidade raiz.

Propriedades de alias	Description
text	A ortografia alternativa ou representação de algum nome de entidade de destino.
caseSensitive	(Opcional) Atua da mesma forma que o parâmetro "caseSensitive" da entidade raiz acima, mas se aplica apenas a este alias.
accentSensitive	(Opcional) Atua 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 a entidade raiz "fuzzyEditDistance" parâmetro acima, mas se aplica apenas a este alias.

Formato embutido

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

Definição de habilidade de amostra

Um exemplo de definição de habilidade 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. Um exemplo de definição de habilidade usando o entitiesDefinitionUri formato é 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 do índice da amostra

Esta seção fornece uma definição de índice de exemplo. Tanto "entidades" quanto "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 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  } 

Avisos

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

Este aviso será emitido se o número de correspondências detetadas for superior ao máximo permitido. Não serão devolvidas mais partidas duplicadas. Se precisar de um limite mais alto, você pode registrar um tíquete de suporte para obter assistência com seu caso de uso individual.

Consulte também

• Competências incorporadas
• Como definir um conjunto de competências
• Habilidade de Reconhecimento de Entidades (para procurar entidades conhecidas)