Como usar o reconhecimento de entidade nomeada no Análise de TextoHow to use Named Entity Recognition in Text Analytics

O API de Análise de Texto permite que você assuma o texto não estruturado e retorne uma lista de entidades desambiguadas, com links para mais informações na Web.The Text Analytics API lets you takes unstructured text and returns a list of disambiguated entities, with links to more information on the web. A API dá suporte ao reconhecimento de entidade nomeada (NER) para várias categorias de entidade e vinculação de entidade.The API supports both named entity recognition (NER) for several entity categories, and entity linking.

Vinculação de IdentidadeEntity Linking

A vinculação de entidades é a capacidade de identificar e desambiguar a identidade de uma entidade encontrada em texto (por exemplo, determinar se uma ocorrência da palavra "Mars" refere-se ao planeta ou ao Deus romano de guerra).Entity linking is the ability to identify and disambiguate the identity of an entity found in text (for example, determining whether an occurrence of the word "Mars" refers to the planet, or to the Roman god of war). Esse processo requer a presença de uma base de dados de conhecimento em um idioma apropriado para vincular entidades reconhecidas em texto.This process requires the presence of a knowledge base in an appropriate language, to link recognized entities in text. A vinculação de entidades usa a Wikipédia como esta base de dados de conhecimento.Entity Linking uses Wikipedia as this knowledge base.

NER (Reconhecimento de Entidade Nomeada)Named Entity Recognition (NER)

O NER (reconhecimento de entidade nomeada) é a capacidade de identificar diferentes entidades no texto e categorizá-las em classes predefinidas ou tipos como: pessoa, local, evento, produto e organização.Named Entity Recognition (NER) is the ability to identify different entities in text and categorize them into pre-defined classes or types such as: person, location, event, product, and organization.

PII (Informações de Identificação Pessoal)Personally Identifiable Information (PII)

O recurso PII faz parte do NER e pode identificar e redação entidades confidenciais no texto associado a uma pessoa individual, como: número de telefone, endereço de email, endereço para correspondência, número do passaporte.The PII feature is part of NER and it can identify and redact sensitive entities in text that are associated with an individual person such as: phone number, email address, mailing address, passport number.

Recursos e versões de reconhecimento de entidade nomeadaNamed Entity Recognition features and versions

RecursoFeature NER v 3.0NER v3.0 NER v 3.1-Preview. 3NER v3.1-preview.3
Métodos para solicitações únicas e em loteMethods for single, and batch requests XX XX
Reconhecimento de entidade expandido em várias categoriasExpanded entity recognition across several categories XX XX
Separe os pontos de extremidade para enviar solicitações de vinculação e NER de entidade.Separate endpoints for sending entity linking and NER requests. XX XX
Reconhecimento de entidades de PII informações pessoais () e de integridade ( PHI )Recognition of personal (PII) and health (PHI) information entities XX
Edição de PIIRedaction of PII XX

Consulte suporte a idiomas para obter informações.See language support for information.

O reconhecimento de entidade nomeada v3 fornece detecção expandida entre vários tipos.Named Entity Recognition v3 provides expanded detection across multiple types. Atualmente, o NER v 3.0 pode reconhecer entidades na categoria de entidade geral.Currently, NER v3.0 can recognize entities in the general entity category.

Reconhecimento de entidade nomeada v 3.1-Preview. 3 inclui os recursos de detecção do v 3.0 e:Named Entity Recognition v3.1-preview.3 includes the detection capabilities of v3.0, and:

  • A capacidade de detectar informações pessoais ( PII ) usando o v3.1-preview.3/entities/recognition/pii ponto de extremidade.The ability to detect personal information (PII) using the v3.1-preview.3/entities/recognition/pii endpoint.
  • Um domain=phi parâmetro opcional para detectar informações de integridade confidencial ( PHI ).An optional domain=phi parameter to detect confidential health information (PHI).
  • Operação assíncrona usando o /analyze ponto de extremidade.Asynchronous operation using the /analyze endpoint.

Para obter mais informações, consulte o artigo categorias de entidade e a seção pontos de extremidade de solicitação abaixo.For more information, see the entity categories article, and request endpoints section below. Para obter mais informações sobre pontuações de confiança, consulte a análise de texto a nota de transparência.For more information on confidence scores, see the Text Analytics transparency note.

Como enviar uma solicitação da API RESTSending a REST API request

PreparaçãoPreparation

Você deve ter documentos JSON neste formato: ID, texto, idioma.You must have JSON documents in this format: ID, text, language.

Cada documento deve ter menos de 5.120 caracteres, e você pode ter até 1.000 itens (IDs) por coleção.Each document must be under 5,120 characters, and you can have up to 1,000 items (IDs) per collection. A coleção é enviada no corpo da solicitação.The collection is submitted in the body of the request.

Estruturar a solicitaçãoStructure the request

Crie uma solicitação POST.Create a POST request. Você pode usar o postmaster ou o console de teste de API nos links a seguir para estruturar e enviar rapidamente um.You can use Postman or the API testing console in the following links to quickly structure and send one.

Observação

Você pode encontrar sua chave e ponto de extremidade para o recurso da Análise de Texto no portal do Azure.You can find your key and endpoint for your Text Analytics resource on the azure portal. Eles estarão localizados na página de Início rápido do recurso, em Gerenciamento de recursos.They will be located on the resource's Quick start page, under resource management.

Pontos de extremidade de solicitaçãoRequest endpoints

O reconhecimento de entidade nomeada v3.1-preview.3 usa pontos de extremidade separados para Ner, PII e solicitações de vinculação de entidade.Named Entity Recognition v3.1-preview.3 uses separate endpoints for NER, PII, and entity linking requests. Use um formato de URL abaixo com base em sua solicitação.Use a URL format below based on your request.

Vinculação de entidadeEntity linking

  • https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/linking

Versão de reconhecimento de entidade nomeada 3,1-referência de visualização para LinkingNamed Entity Recognition version 3.1-preview reference for Linking

Reconhecimento de entidade nomeadaNamed Entity Recognition

  • Entidades gerais- https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/generalGeneral entities - https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/general

Versão de reconhecimento de entidade nomeada 3,1-referência de visualização para GeneralNamed Entity Recognition version 3.1-preview reference for General

PII (Informações de Identificação Pessoal)Personally Identifiable Information (PII)

  • Informações pessoais ( PII )- https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/piiPersonal (PII) information - https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/pii

Você também pode usar o domain=phi parâmetro opcional para detectar PHI informações de integridade () em texto.You can also use the optional domain=phi parameter to detect health (PHI) information in text.

https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/entities/recognition/pii?domain=phi

A partir do v3.1-preview.3 , a resposta JSON inclui uma redactedText propriedade, que contém o texto de entrada modificado em que as entidades PII detectadas são substituídas por um * para cada caractere nas entidades.Starting in v3.1-preview.3, The JSON response includes a redactedText property, which contains the modified input text where the detected PII entities are replaced by an * for each character in the entities.

Versão de reconhecimento de entidade nomeada 3,1-referência de visualização para PIINamed Entity Recognition version 3.1-preview reference for PII

Operação assíncronaAsynchronous operation

A partir do v3.1-preview.3 , você pode enviar solicitações Ner de forma assíncrona usando o /analyze ponto de extremidade.Starting in v3.1-preview.3, You can send NER requests asynchronously using the /analyze endpoint.

  • Operação assíncrona- https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/analyzeAsynchronous operation - https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1-preview.3/analyze

Consulte como chamar o API de análise de texto para obter informações sobre como enviar solicitações assíncronas.See How to call the Text Analytics API for information on sending asynchronous requests.

Defina um cabeçalho de solicitação para incluir sua chave de API de Análise de Texto.Set a request header to include your Text Analytics API key. No corpo da solicitação, forneça os documentos JSON que você preparou.In the request body, provide the JSON documents you prepared.

Solicitações de exemploExample requests

Exemplo de solicitação síncrona de NERExample synchronous NER request

O JSON a seguir é um exemplo de conteúdo que você pode enviar para a API.The following JSON is an example of content you might send to the API. O formato da solicitação é o mesmo para as duas versões da API.The request format is the same for both versions of the API.

{
  "documents": [
    {
        "id": "1",
        "language": "en",
        "text": "Our tour guide took us up the Space Needle during our trip to Seattle last week."
    }
  ]
}

Exemplo de solicitação assíncrona de NERExample asynchronous NER request

Se você usar o /analyze ponto de extremidade para a operação assíncrona, receberá uma resposta que contém as tarefas que você enviou para a API.If you use the /analyze endpoint for asynchronous operation, you will get a response containing the tasks you sent to the API.

{
    "displayName": "My Job",
    "analysisInput": {
        "documents": [
            {
                "id": "doc1",
                "text": "It's incredibly sunny outside! I'm so happy"
            },
            {
                "id": "doc2",
                "text": "Pike place market is my favorite Seattle attraction."
            }
        ]
    },
    "tasks": {
        "entityRecognitionTasks": [
            {
                "parameters": {
                    "model-version": "latest",
                    "stringIndexType": "TextElements_v8"
                }
            }
        ],
        "entityRecognitionPiiTasks": [{
            "parameters": {
                "model-version": "latest"
            }
        }]
    }
}

Postar a solicitaçãoPost the request

A análise é executada após o recebimento da solicitação.Analysis is performed upon receipt of the request. Consulte a seção limites de dados na visão geral para obter informações sobre o tamanho e o número de solicitações que você pode enviar por minuto e segundo.See the data limits section in the overview for information on the size and number of requests you can send per minute and second.

A API de Análise de Texto é sem estado.The Text Analytics API is stateless. Nenhum dado é armazenado em sua conta e os resultados são retornados imediatamente na resposta.No data is stored in your account, and results are returned immediately in the response.

Exibir os resultadosView results

Todas as solicitações POST retornam uma resposta formatada em JSON com as IDs e as propriedades de entidade detectadas.All POST requests return a JSON formatted response with the IDs and detected entity properties.

A saída é retornada imediatamente.Output is returned immediately. Você pode transmitir os resultados para um aplicativo que aceita JSON ou salvar a saída em um arquivo no sistema local e, em seguida, importá-lo para um aplicativo que permite que você classifique, pesquise e manipule os dados.You can stream the results to an application that accepts JSON or save the output to a file on the local system, and then import it into an application that allows you to sort, search, and manipulate the data. Devido ao suporte multilíngue e a emojis, a resposta pode conter deslocamentos de texto.Due to multilingual and emoji support, the response may contain text offsets. Para obter mais informações, consulte como processar deslocamentos de texto.For more information, see how to process text offsets.

Respostas de exemploExample responses

A versão 3 fornece pontos de extremidade separados para NER geral, PII e vinculação de entidade.Version 3 provides separate endpoints for general NER, PII, and entity linking. A versão 3,1-pareview inclui um modo de análise assíncrona.Version 3.1-pareview includes an asynchronous Analyze mode. As respostas para essas operações estão abaixo.The responses for these operations are below.

Resultados de exemplo síncronoSynchronous example results

Exemplo de uma resposta geral do NER:Example of a general NER response:

{
  "documents": [
    {
      "id": "1",
      "entities": [
        {
          "text": "tour guide",
          "category": "PersonType",
          "offset": 4,
          "length": 10,
          "confidenceScore": 0.45
        },
        {
          "text": "Space Needle",
          "category": "Location",
          "offset": 30,
          "length": 12,
          "confidenceScore": 0.38
        },
        {
          "text": "trip",
          "category": "Event",
          "offset": 54,
          "length": 4,
          "confidenceScore": 0.78
        },
        {
          "text": "Seattle",
          "category": "Location",
          "subcategory": "GPE",
          "offset": 62,
          "length": 7,
          "confidenceScore": 0.78
        },
        {
          "text": "last week",
          "category": "DateTime",
          "subcategory": "DateRange",
          "offset": 70,
          "length": 9,
          "confidenceScore": 0.8
        }
      ],
      "warnings": []
    }
  ],
  "errors": [],
  "modelVersion": "2020-04-01"
}

Exemplo de uma resposta de PII:Example of a PII response:

{
  "documents": [
    {
    "redactedText": "You can even pre-order from their online menu at *************************, call ************ or send email to ***************************!",
    "id": "0",
    "entities": [
        {
        "text": "www.contososteakhouse.com",
        "category": "URL",
        "offset": 49,
        "length": 25,
        "confidenceScore": 0.8
        }, 
        {
        "text": "312-555-0176",
        "category": "Phone Number",
        "offset": 81,
        "length": 12,
        "confidenceScore": 0.8
        }, 
        {
        "text": "order@contososteakhouse.com",
        "category": "Email",
        "offset": 111,
        "length": 27,
        "confidenceScore": 0.8
        }
      ],
    "warnings": []
    }
  ],
  "errors": [],
  "modelVersion": "2020-07-01"
}

Exemplo de uma resposta de vinculação de entidade:Example of an Entity linking response:

{
  "documents": [
    {
      "id": "1",
      "entities": [
        {
          "bingId": "f8dd5b08-206d-2554-6e4a-893f51f4de7e", 
          "name": "Space Needle",
          "matches": [
            {
              "text": "Space Needle",
              "offset": 30,
              "length": 12,
              "confidenceScore": 0.4
            }
          ],
          "language": "en",
          "id": "Space Needle",
          "url": "https://en.wikipedia.org/wiki/Space_Needle",
          "dataSource": "Wikipedia"
        },
        {
          "bingId": "5fbba6b8-85e1-4d41-9444-d9055436e473",
          "name": "Seattle",
          "matches": [
            {
              "text": "Seattle",
              "offset": 62,
              "length": 7,
              "confidenceScore": 0.25
            }
          ],
          "language": "en",
          "id": "Seattle",
          "url": "https://en.wikipedia.org/wiki/Seattle",
          "dataSource": "Wikipedia"
        }
      ],
      "warnings": []
    }
  ],
  "errors": [],
  "modelVersion": "2020-02-01"
}

Exemplo de resultado assíncronoExample asynchronous result

{
  "displayName": "My Analyze Job",
  "jobId": "dbec96a8-ea22-4ad1-8c99-280b211eb59e_637408224000000000",
  "lastUpdateDateTime": "2020-11-13T04:01:14Z",
  "createdDateTime": "2020-11-13T04:01:13Z",
  "expirationDateTime": "2020-11-14T04:01:13Z",
  "status": "running",
  "errors": [],
  "tasks": {
      "details": {
          "name": "My Analyze Job",
          "lastUpdateDateTime": "2020-11-13T04:01:14Z"
      },
      "completed": 1,
      "failed": 0,
      "inProgress": 2,
      "total": 3,
      "keyPhraseExtractionTasks": [
          {
              "name": "My Analyze Job",
              "lastUpdateDateTime": "2020-11-13T04:01:14.3763516Z",
              "results": {
                  "inTerminalState": true,
                  "documents": [
                      {
                          "id": "doc1",
                          "keyPhrases": [
                              "sunny outside"
                          ],
                          "warnings": []
                      },
                      {
                          "id": "doc2",
                          "keyPhrases": [
                              "favorite Seattle attraction",
                              "Pike place market"
                          ],
                          "warnings": []
                      }
                  ],
                  "errors": [],
                  "modelVersion": "2020-07-01"
              }
          }
      ]
  }
}

ResumoSummary

Neste artigo, você aprendeu os conceitos e fluxo de trabalho para detecção de idioma usando a Análise de Texto em Serviços Cognitivos.In this article, you learned concepts and workflow for entity linking using Text Analytics in Cognitive Services. Em resumo:In summary:

  • Documentos JSON no corpo da solicitação incluem um código de idioma, texto e ID.JSON documents in the request body include an ID, text, and language code.
  • As solicitações POST são enviadas para um ou mais pontos de extremidade, usando uma chave de acesso personalizada e um ponto de extremidade válido para sua assinatura.POST requests are sent to one or more endpoints, using a personalized access key and an endpoint that is valid for your subscription.
  • A saída da resposta, composta por entidades vinculadas (incluindo pontuações de confiança, deslocamentos e links da Web, para cada ID de documento) pode ser usada em qualquer aplicativoResponse output, which consists of linked entities (including confidence scores, offsets, and web links, for each document ID) can be used in any application

Próximas etapasNext steps