Come usare il riconoscimento delle entità denominate in Analisi del testoHow to use Named Entity Recognition in Text Analytics

Il API Analisi del testo consente di usare un testo non strutturato e restituisce un elenco di entità ambiguità, con collegamenti ad altre informazioni sul 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. L'API supporta il riconoscimento delle entità denominate (NER) per diverse categorie di entità e il collegamento di entità.The API supports both named entity recognition (NER) for several entity categories, and entity linking.

Collegamento delle entitàEntity Linking

Il collegamento di entità è la possibilità di identificare e risolvere l'ambiguità dell'identità di un'entità trovata nel testo (ad esempio, determinare se un'occorrenza della parola "Mars" si riferisce al pianeta o al Dio di guerra romano).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). Questo processo richiede la presenza di una Knowledge base in una lingua appropriata per collegare entità riconosciute nel testo.This process requires the presence of a knowledge base in an appropriate language, to link recognized entities in text. Il collegamento di entità USA Wikipedia come questa Knowledge base.Entity Linking uses Wikipedia as this knowledge base.

Riconoscimento delle entità denominate (NER)Named Entity Recognition (NER)

Il riconoscimento delle entità denominate è la possibilità di identificare entità diverse nel testo e di classificarle in classi o tipi predefiniti quali: persona, posizione, evento, prodotto e organizzazione.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.

Informazioni personaliPersonally Identifiable Information (PII)

La funzionalità informazioni personali fa parte di NER e consente di identificare e offuscare le entità riservate nel testo associate a un singolo utente, ad esempio il numero di telefono, l'indirizzo di posta elettronica, l'indirizzo postale, il numero di Passport.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.

Funzionalità e versioni di riconoscimento entità denominateNamed Entity Recognition features and versions

FunzionalitàFeature NER v 3.0NER v3.0 NER v 3.1-Preview. 3NER v3.1-preview.3
Metodi per richieste singole e batchMethods for single, and batch requests XX XX
Riconoscimento delle entità espanso tra diverse categorieExpanded entity recognition across several categories XX XX
Separare gli endpoint per l'invio di entità di collegamento e richieste NER.Separate endpoints for sending entity linking and NER requests. XX XX
Riconoscimento di entità di PII informazioni personali () e di integrità ( PHI )Recognition of personal (PII) and health (PHI) information entities XX
Redazione di PIIRedaction of PII XX

Per informazioni, vedere Supporto per le lingue .See language support for information.

Il riconoscimento delle entità denominate V3 fornisce il rilevamento espanso tra più tipi.Named Entity Recognition v3 provides expanded detection across multiple types. Attualmente, NER v 3.0 è in grado di riconoscere le entità nella categoria di entità generale.Currently, NER v3.0 can recognize entities in the general entity category.

Il riconoscimento delle entità denominato v 3.1-Preview. 3 include le funzionalità di rilevamento di v 3.0 e:Named Entity Recognition v3.1-preview.3 includes the detection capabilities of v3.0, and:

  • Possibilità di rilevare le informazioni personali ( PII ) utilizzando l' v3.1-preview.3/entities/recognition/pii endpoint.The ability to detect personal information (PII) using the v3.1-preview.3/entities/recognition/pii endpoint.
  • Parametro facoltativo domain=phi per rilevare le informazioni riservate sull'integrità ( PHI ).An optional domain=phi parameter to detect confidential health information (PHI).
  • Operazione asincrona che usa l' /analyze endpoint.Asynchronous operation using the /analyze endpoint.

Per altre informazioni, vedere l'articolo relativo alle categorie di entità e la sezione relativa agli endpoint di richiesta di seguito.For more information, see the entity categories article, and request endpoints section below. Per ulteriori informazioni sui punteggi di confidenza, vedere la Nota sulla trasparenza analisi del testo.For more information on confidence scores, see the Text Analytics transparency note.

Invio di una richiesta all'API RESTSending a REST API request

PreparazionePreparation

È necessario disporre di documenti JSON nel formato seguente: ID, testo, lingua.You must have JSON documents in this format: ID, text, language.

Ogni documento deve essere composto da un massimo di 5.120 caratteri ed è possibile avere fino a 1.000 elementi (ID) per raccolta.Each document must be under 5,120 characters, and you can have up to 1,000 items (IDs) per collection. La raccolta viene inviata nel corpo della richiesta.The collection is submitted in the body of the request.

Strutturare la richiestaStructure the request

Creare una richiesta POST.Create a POST request. È possibile usare la console di testing API o di posting nei collegamenti seguenti per strutturare rapidamente e inviarne una.You can use Postman or the API testing console in the following links to quickly structure and send one.

Nota

È possibile trovare la chiave e l'endpoint per la risorsa Analisi del testo nel portale di Azure.You can find your key and endpoint for your Text Analytics resource on the azure portal. Si trovano in Gestione risorse nella pagina Avvio rapido della risorsa.They will be located on the resource's Quick start page, under resource management.

Endpoint di richiestaRequest endpoints

Il riconoscimento delle entità denominate v3.1-preview.3 utilizza endpoint distinti per le richieste ner, pii e di collegamento di entità.Named Entity Recognition v3.1-preview.3 uses separate endpoints for NER, PII, and entity linking requests. Usare un formato URL riportato di seguito in base alla richiesta.Use a URL format below based on your request.

Collegamento di entitàEntity linking

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

Informazioni di riferimento sul riconoscimento entità denominato versione 3,1-Preview per LinkingNamed Entity Recognition version 3.1-preview reference for Linking

Riconoscimento di entità denominateNamed Entity Recognition

  • Entità generali- 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

Informazioni di riferimento sul riconoscimento entità denominato versione 3,1-Preview per GeneralNamed Entity Recognition version 3.1-preview reference for General

Informazioni personaliPersonally Identifiable Information (PII)

  • Informazioni personali ( 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

È anche possibile usare il domain=phi parametro facoltativo per rilevare PHI le informazioni sull'integrità () nel testo.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 partire da v3.1-preview.3 , la risposta JSON include una redactedText proprietà che contiene il testo di input modificato in cui le entità pii rilevate vengono sostituite da un * per ogni carattere nelle entità.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.

Informazioni di riferimento sul riconoscimento entità denominato versione 3,1-Preview per PIINamed Entity Recognition version 3.1-preview reference for PII

Operazione asincronaAsynchronous operation

A partire da v3.1-preview.3 , è possibile inviare richieste ner in modo asincrono usando l' /analyze endpoint.Starting in v3.1-preview.3, You can send NER requests asynchronously using the /analyze endpoint.

  • Operazione asincrona- 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

Per informazioni sull'invio di richieste asincrone, vedere come chiamare il API analisi del testo .See How to call the Text Analytics API for information on sending asynchronous requests.

Impostare un'intestazione della richiesta per includere la chiave dell'API Analisi del testo.Set a request header to include your Text Analytics API key. Nel corpo della richiesta fornire i documenti JSON preparati.In the request body, provide the JSON documents you prepared.

Richieste di esempioExample requests

Esempio di richiesta NER sincronaExample synchronous NER request

Il codice JSON seguente è un esempio di contenuto che è possibile inviare all'API.The following JSON is an example of content you might send to the API. Il formato della richiesta è identico per entrambe le versioni dell'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."
    }
  ]
}

Richiesta NER di esempio asincronaExample asynchronous NER request

Se si usa l' /analyze endpoint per l' operazione asincrona, si otterrà una risposta contenente le attività inviate all'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"
            }
        }]
    }
}

Pubblicare la richiestaPost the request

Al momento della ricezione della richiesta viene eseguita l'analisi.Analysis is performed upon receipt of the request. Vedere la sezione relativa ai limiti dei data nella panoramica per informazioni sulle dimensioni e il numero di richieste che è possibile inviare al minuto e al secondo.See the data limits section in the overview for information on the size and number of requests you can send per minute and second.

L'API Analisi del testo è senza stato.The Text Analytics API is stateless. Non vengono archiviati dati nell'account e i risultati vengono restituiti immediatamente nella risposta.No data is stored in your account, and results are returned immediately in the response.

Visualizzazione dei risultatiView results

Tutte le richieste POST restituiscono una risposta in formato JSON con gli ID e le proprietà dell'entità rilevata.All POST requests return a JSON formatted response with the IDs and detected entity properties.

L'output viene restituito immediatamente.Output is returned immediately. Si possono trasmettere i risultati a un'applicazione che accetta JSON o salvare l'output in un file nel sistema locale e quindi importarlo in un'applicazione che consente di ordinare, cercare e modificare i dati.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. A causa del supporto multilingue e emoji, la risposta può contenere offset di testo.Due to multilingual and emoji support, the response may contain text offsets. Per ulteriori informazioni, vedere come elaborare gli offset di testo.For more information, see how to process text offsets.

Risposte di esempioExample responses

La versione 3 fornisce endpoint distinti per il collegamento generale di NER, PII ed entità.Version 3 provides separate endpoints for general NER, PII, and entity linking. La versione 3,1-pareview include una modalità di analisi asincrona.Version 3.1-pareview includes an asynchronous Analyze mode. Di seguito sono riportate le risposte per queste operazioni.The responses for these operations are below.

Risultati di esempio sincroniSynchronous example results

Esempio di risposta NER generale: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"
}

Esempio di risposta 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"
}

Esempio di risposta di collegamento di un'entità: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"
}

Risultato asincrono di esempioExample 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"
              }
          }
      ]
  }
}

RiepilogoSummary

In questo articolo si sono appresi i concetti e il flusso di lavoro per il collegamento delle entità usando Analisi del testo nei Servizi cognitivi.In this article, you learned concepts and workflow for entity linking using Text Analytics in Cognitive Services. In sintesi:In summary:

  • I documenti JSON nel corpo della richiesta includono un ID, il testo e il codice della lingua.JSON documents in the request body include an ID, text, and language code.
  • Le richieste POST vengono inviate a uno o più endpoint, usando una chiave di accesso personalizzata e un endpoint valido per la sottoscrizione.POST requests are sent to one or more endpoints, using a personalized access key and an endpoint that is valid for your subscription.
  • L'output di risposta, che consiste di entità collegate (inclusi punteggi di attendibilità, offset e collegamenti Web per ogni ID di documento) può essere usato in qualsiasi applicazioneResponse output, which consists of linked entities (including confidence scores, offsets, and web links, for each document ID) can be used in any application

Passaggi successiviNext steps