Guida introduttiva: Rilevamento di entità denominate (NER)

  • Articolo
  • 11 minuti per la lettura

Usare questo articolo per iniziare a rilevare le entità nel testo usando la libreria client NER e l'API REST. Seguire questi passaggi per provare il codice di esempio per attività di mining del testo:

Documentazione | di riferimento Codice sorgente | della libreria Pacchetto (NuGet) | Esempi aggiuntivi

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • L'IDE di Visual Studio
  • Dopo aver creato la sottoscrizione di Azure, nella portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • La chiave e l'endpoint saranno necessari dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Si è verificato un problema

Configurazione

Creare una nuova applicazione .NET Core

Usando l'IDE di Visual Studio, creare una nuova app console .NET Core. Verrà creato un progetto "Hello World" con un singolo file di origine C#, program.cs.

Installare la libreria client facendo clic con il pulsante destro del mouse sulla soluzione in Esplora soluzioni e scegliendo Gestisci pacchetti NuGet. Nella finestra di dialogo Gestione pacchetti visualizzata selezionare Sfoglia e cercare Azure.AI.TextAnalytics. Selezionare la versione 5.1.0, quindi Installa. È anche possibile usare la console di gestione pacchetti.

Si è verificato un problema

Esempio di codice

Copiare il codice seguente nel file program.cs . Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa.

Importante

Accedere al portale di Azure. Se la risorsa Language creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint nella pagina Chiavi ed endpoint della risorsa, in Gestione risorse.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault.

using Azure;
using System;
using Azure.AI.TextAnalytics;

namespace Example
{
    class Program
    {
        private static readonly AzureKeyCredential credentials = new AzureKeyCredential("replace-with-your-key-here");
        private static readonly Uri endpoint = new Uri("replace-with-your-endpoint-here");
        
        // Example method for extracting named entities from text 
        static void EntityRecognitionExample(TextAnalyticsClient client)
        {
            var response = client.RecognizeEntities("I had a wonderful trip to Seattle last week.");
            Console.WriteLine("Named Entities:");
            foreach (var entity in response.Value)
            {
                Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
                Console.WriteLine($"\t\tScore: {entity.ConfidenceScore:F2},\tLength: {entity.Length},\tOffset: {entity.Offset}\n");
            }
        }

        static void Main(string[] args)
        {
            var client = new TextAnalyticsClient(endpoint, credentials);
            EntityRecognitionExample(client);

            Console.Write("Press any key to exit.");
            Console.ReadKey();
        }

    }
}

Si è verificato un problema

Output

Named Entities:
        Text: trip,     Category: Event,        Sub-Category:
                Score: 0.61,    Length: 4,      Offset: 18

        Text: Seattle,  Category: Location,     Sub-Category: GPE
                Score: 0.82,    Length: 7,      Offset: 26

        Text: last week,        Category: DateTime,     Sub-Category: DateRange
                Score: 0.80,    Length: 9,      Offset: 34

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto | Esempi

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Java Development Kit (JDK) versione 8 o successiva
  • Dopo aver creato la sottoscrizione di Azure, nella portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • La chiave e l'endpoint saranno necessari dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Si è verificato un problema

Configurazione

Aggiungere la libreria client

Creare un progetto Maven nell'ambiente IDE o di sviluppo preferito. Aggiungere quindi la dipendenza seguente al file pom.xml del progetto. È possibile trovare la sintassi di implementazione per altri strumenti di compilazione online.

<dependencies>
     <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-textanalytics</artifactId>
        <version>5.1.9</version>
    </dependency>
</dependencies>

Esempio di codice

Creare un file Java denominato Example.java. Aprire il file e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa.

Importante

Accedere al portale di Azure. Se la risorsa Language creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint nella pagina Chiavi ed endpoint della risorsa, in Gestione risorse.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault.

import com.azure.core.credential.AzureKeyCredential;
import com.azure.ai.textanalytics.models.*;
import com.azure.ai.textanalytics.TextAnalyticsClientBuilder;
import com.azure.ai.textanalytics.TextAnalyticsClient;

public class Example {

    private static String KEY = "replace-with-your-key-here";
    private static String ENDPOINT = "replace-with-your-endpoint-here";

    public static void main(String[] args) {
        TextAnalyticsClient client = authenticateClient(KEY, ENDPOINT);
        recognizeEntitiesExample(client);
    }
    // Method to authenticate the client object with your key and endpoint
    static TextAnalyticsClient authenticateClient(String key, String endpoint) {
        return new TextAnalyticsClientBuilder()
                .credential(new AzureKeyCredential(key))
                .endpoint(endpoint)
                .buildClient();
    }
    // Example method for recognizing entities in text
    static void recognizeEntitiesExample(TextAnalyticsClient client)
    {
        // The text that need be analyzed.
        String text = "I had a wonderful trip to Seattle last week.";
    
        for (CategorizedEntity entity : client.recognizeEntities(text)) {
            System.out.printf(
                "Recognized entity: %s, entity category: %s, entity sub-category: %s, score: %s, offset: %s, length: %s.%n",
                entity.getText(),
                entity.getCategory(),
                entity.getSubcategory(),
                entity.getConfidenceScore(),
                entity.getOffset(),
                entity.getLength());
        }
    }
}

Output

Recognized entity: trip, entity category: Event, entity sub-category: null, score: 0.74, offset: 18, length: 4.
Recognized entity: Seattle, entity category: Location, entity sub-category: GPE, score: 1.0, offset: 26, length: 7.
Recognized entity: last week, entity category: DateTime, entity sub-category: DateRange, score: 0.8, offset: 34, length: 9.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (NPM) | Esempi

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Versione corrente di Node.js.
  • Dopo aver creato la sottoscrizione di Azure, nella portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • La chiave e l'endpoint saranno necessari dalla risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, è necessaria una risorsa lingua con il piano tariffario standard (S).

Si è verificato un problema

Configurazione

Creare una nuova applicazione Node.js

In una finestra della console, ad esempio cmd, PowerShell o Bash, creare e passare a una nuova directory per l'app.

mkdir myapp 

cd myapp

Eseguire il comando npm init per creare un'applicazione Node con un file package.json.

npm init

Installare la libreria client

Installare il pacchetto NPM:

npm install @azure/ai-text-analytics@5.1.0

Si è verificato un problema

Esempio di codice

Aprire il file e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa.

Importante

Accedere al portale di Azure. Se la risorsa Language creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint nella pagina Chiavi ed endpoint della risorsa, in Gestione risorse.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault.

"use strict";

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const key = '<paste-your-key-here>';
const endpoint = '<paste-your-endpoint-here>';
// Authenticate the client with your key and endpoint
const textAnalyticsClient = new TextAnalyticsClient(endpoint,  new AzureKeyCredential(key));

// Example method for recognizing entities in text
async function entityRecognition(client){

    const entityInputs = [
        "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800",
        "La sede principal de Microsoft se encuentra en la ciudad de Redmond, a 21 kilómetros de Seattle."
    ];
    const entityResults = await client.recognizeEntities(entityInputs);

    entityResults.forEach(document => {
        console.log(`Document ID: ${document.id}`);
        document.entities.forEach(entity => {
            console.log(`\tName: ${entity.text} \tCategory: ${entity.category} \tSubcategory: ${entity.subCategory ? entity.subCategory : "N/A"}`);
            console.log(`\tScore: ${entity.confidenceScore}`);
        });
    });
}
entityRecognition(textAnalyticsClient);

Si è verificato un problema

Output

Document ID: 0
        Name: Microsoft         Category: Organization  Subcategory: N/A
        Score: 0.29
        Name: Bill Gates        Category: Person        Subcategory: N/A
        Score: 0.78
        Name: Paul Allen        Category: Person        Subcategory: N/A
        Score: 0.82
        Name: April 4, 1975     Category: DateTime      Subcategory: Date
        Score: 0.8
        Name: 8800      Category: Quantity      Subcategory: Number
        Score: 0.8
Document ID: 1
        Name: 21        Category: Quantity      Subcategory: Number
        Score: 0.8
        Name: Seattle   Category: Location      Subcategory: GPE
        Score: 0.25

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (PiPy) | Esempi

Prerequisiti

  • Sottoscrizione di Azure: creare un account gratuito
  • Python 3.x
  • Dopo aver ottenuto la sottoscrizione di Azure, nella portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessario che la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.
  • Per usare la funzionalità Analizza, sarà necessaria una risorsa lingua con il piano tariffario standard (S).

Configurazione

Installare la libreria client

Dopo l'installazione di Python, è possibile installare la libreria client con:

pip install azure-ai-textanalytics==5.1.0

Esempio di codice

Creare un nuovo file Python e copiare il codice seguente. Ricordarsi di sostituire la key variabile con la chiave per la risorsa e sostituire la endpoint variabile con l'endpoint per la risorsa.

Importante

Accedere al portale di Azure. Se la risorsa lingua creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai a Risorsa in Passaggi successivi. È possibile trovare la chiave e l'endpoint nella pagina Chiavi e endpoint della risorsa, in Gestione risorse.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio Azure Key Vault.

key = "paste-your-key-here"
endpoint = "paste-your-endpoint-here"

from azure.ai.textanalytics import TextAnalyticsClient
from azure.core.credentials import AzureKeyCredential

# Authenticate the client using your key and endpoint 
def authenticate_client():
    ta_credential = AzureKeyCredential(key)
    text_analytics_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=ta_credential)
    return text_analytics_client

client = authenticate_client()

# Example function for recognizing entities from text
def entity_recognition_example(client):

    try:
        documents = ["I had a wonderful trip to Seattle last week."]
        result = client.recognize_entities(documents = documents)[0]

        print("Named Entities:\n")
        for entity in result.entities:
            print("\tText: \t", entity.text, "\tCategory: \t", entity.category, "\tSubCategory: \t", entity.subcategory,
                    "\n\tConfidence Score: \t", round(entity.confidence_score, 2), "\tLength: \t", entity.length, "\tOffset: \t", entity.offset, "\n")

    except Exception as err:
        print("Encountered exception. {}".format(err))
entity_recognition_example(client)

Output

Named Entities:

        Text:    trip   Category:        Event  SubCategory:     None
        Confidence Score:        0.61   Length:          4      Offset:          18

        Text:    Seattle        Category:        Location       SubCategory:     GPE
        Confidence Score:        0.82   Length:          7      Offset:          26

        Text:    last week      Category:        DateTime       SubCategory:     DateRange
        Confidence Score:        0.8    Length:          9      Offset:          34

Documentazione di riferimento

Prerequisiti

  • La versione corrente di cURL.
  • Dopo aver ottenuto la sottoscrizione di Azure, nella portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
    • È necessario che la chiave e l'endpoint della risorsa creata per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
    • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Nota

  • Negli esempi BASH seguenti viene usato il carattere di continuazione riga \. Se la console o il terminale usa un carattere di continuazione riga diverso, usare questo carattere.
  • È possibile trovare esempi specifici del linguaggio in GitHub.
  • Passare alla portale di Azure e trovare la chiave e l'endpoint per la risorsa language creata nei prerequisiti. Si trovano nella pagina Chiave ed endpoint della risorsa, in Gestione risorse. Sostituire quindi le stringhe nel codice seguente con la chiave e l'endpoint. Per chiamare l'API, sono necessarie le informazioni seguenti:
parametro Descrizione
-X POST <endpoint> Specifica l'endpoint per l'accesso all'API.
-H Content-Type: application/json Il tipo di contenuto per l'invio di dati JSON.
-H "Ocp-Apim-Subscription-Key:<key> Specifica la chiave per l'accesso all'API.
-d <documents> Il codice JSON contenente i documenti da inviare.

I comandi cURL seguenti vengono eseguiti da una shell BASH. Modificare questi comandi con il nome e la chiave della risorsa e con i valori del file JSON.

Si è verificato un problema

Estrazione di entità denominata (NER)

  1. Copiare il comando in un editor di testo.
  2. Apportare le modifiche seguenti al comando, dove necessario:
    1. Sostituire il valore <your-text-analytics-key-here> con la propria chiave.
    2. Sostituire la prima parte dell'URL della richiesta <your-text-analytics-endpoint-here> con il testo dell'URL dell'endpoint.
  3. Aprire una finestra del prompt dei comandi.
  4. Incollare il comando dall'editor di testo nella finestra del prompt dei comandi e quindi eseguire il comando.
curl -i -X POST https://<your-language-resource-endpoint>/language/:analyze-text?api-version=2022-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key:<your-language-resource-key>" \
-d \
'
{
    "kind": "EntityRecognition",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "language": "en",
                "text": "I had a wonderful trip to Seattle last week."
            }
        ]
    }
}
'

Risposta JSON

{
	"kind": "EntityRecognitionResults",
	"results": {
		"documents": [{
			"id": "1",
			"entities": [{
				"text": "trip",
				"category": "Event",
				"offset": 18,
				"length": 4,
				"confidenceScore": 0.74
			}, {
				"text": "Seattle",
				"category": "Location",
				"subcategory": "GPE",
				"offset": 26,
				"length": 7,
				"confidenceScore": 1.0
			}, {
				"text": "last week",
				"category": "DateTime",
				"subcategory": "DateRange",
				"offset": 34,
				"length": 9,
				"confidenceScore": 0.8
			}],
			"warnings": []
		}],
		"errors": [],
		"modelVersion": "2021-06-01"
	}
}

Si è verificato un problema

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi cognitivi, è possibile eliminare la risorsa o il gruppo di risorse. Eliminando il gruppo di risorse vengono eliminate anche tutte le altre risorse associate.

Si è verificato un problema

Passaggi successivi