Avvio rapido: collegamento delle entità usando la libreria client e l'API REST

Documentazione di riferimento | Altri esempi | Pacchetto (NuGet) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di collegamento delle entità con la libreria client per .NET. Nell'esempio seguente viene creata un'applicazione C# in grado di identificare e disambiguare le entità trovate nel testo.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• L'IDE di Visual Studio

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio Lingua.

1. Usare il collegamento seguente per creare una risorsa Lingua tramite il portale di Azure. Sarà necessario accedere usando la propria sottoscrizione di Azure.

2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

   

3. Nella schermata Crea lingua specificare le informazioni seguenti:

   Dettagli	Descrizione
   Abbonamento	Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure nell'elenco a discesa.
   Gruppo di risorse	Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
   Area	La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
   Nome	Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
   Piano tariffario	Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

   

4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

5. Selezionare Rivedi e crea nella parte inferiore della pagina.

6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

   

2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

   

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

• Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
• Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

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.2.0, quindi Installa. È anche possibile usare la console di gestione pacchetti.

Esempio di codice

Copiare il seguente codice nel file program.cs ed eseguirlo.

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

namespace EntityLinkingExample
{
    class Program
    {
        // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
        static string languageKey = Environment.GetEnvironmentVariable("LANGUAGE_KEY");
        static string languageEndpoint = Environment.GetEnvironmentVariable("LANGUAGE_ENDPOINT");

        private static readonly AzureKeyCredential credentials = new AzureKeyCredential(languageKey);
        private static readonly Uri endpoint = new Uri(languageEndpoint);
        
        // Example method for recognizing entities and providing a link to an online data source.
        static void EntityLinkingExample(TextAnalyticsClient client)
        {
            var response = client.RecognizeLinkedEntities(
                "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, " +
                "to develop and sell BASIC interpreters for the Altair 8800. " +
                "During his career at Microsoft, Gates held the positions of chairman, " +
                "chief executive officer, president and chief software architect, " +
                "while also being the largest individual shareholder until May 2014.");
            Console.WriteLine("Linked Entities:");
            foreach (var entity in response.Value)
            {
                Console.WriteLine($"\tName: {entity.Name},\tID: {entity.DataSourceEntityId},\tURL: {entity.Url}\tData Source: {entity.DataSource}");
                Console.WriteLine("\tMatches:");
                foreach (var match in entity.Matches)
                {
                    Console.WriteLine($"\t\tText: {match.Text}");
                    Console.WriteLine($"\t\tScore: {match.ConfidenceScore:F2}\n");
                }
            }
        }

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

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

    }
}

Output

Linked Entities:
    Name: Microsoft,        ID: Microsoft,  URL: https://en.wikipedia.org/wiki/Microsoft    Data Source: Wikipedia
    Matches:
            Text: Microsoft
            Score: 0.55

            Text: Microsoft
            Score: 0.55

    Name: Bill Gates,       ID: Bill Gates, URL: https://en.wikipedia.org/wiki/Bill_Gates   Data Source: Wikipedia
    Matches:
            Text: Bill Gates
            Score: 0.63

            Text: Gates
            Score: 0.63

    Name: Paul Allen,       ID: Paul Allen, URL: https://en.wikipedia.org/wiki/Paul_Allen   Data Source: Wikipedia
    Matches:
            Text: Paul Allen
            Score: 0.60

    Name: April 4,  ID: April 4,    URL: https://en.wikipedia.org/wiki/April_4      Data Source: Wikipedia
    Matches:
            Text: April 4
            Score: 0.32

    Name: BASIC,    ID: BASIC,      URL: https://en.wikipedia.org/wiki/BASIC        Data Source: Wikipedia
    Matches:
            Text: BASIC
            Score: 0.33

    Name: Altair 8800,      ID: Altair 8800,        URL: https://en.wikipedia.org/wiki/Altair_8800  Data Source: Wikipedia
    Matches:
            Text: Altair 8800
            Score: 0.88

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

• Azure portal
• Interfaccia della riga di comando di Azure

Passaggi successivi

• Lingue supportate per il collegamento delle entità
• Come chiamare l’API di collegamento delle entità
• Documentazione di riferimento
• Ulteriori esempi

Documentazione di riferimento | Altri esempi | Pacchetto (Maven) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di collegamento delle entità con la libreria client per Java. Nell'esempio seguente viene creata un'applicazione Java in grado di identificare e disambiguare le entità trovate nel testo.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Java Development Kit (JDK) versione 8 o successiva

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio Lingua.

1. Usare il collegamento seguente per creare una risorsa Lingua tramite il portale di Azure. Sarà necessario accedere usando la propria sottoscrizione di Azure.

2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

   

3. Nella schermata Crea lingua specificare le informazioni seguenti:

   Dettagli	Descrizione
   Abbonamento	Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure nell'elenco a discesa.
   Gruppo di risorse	Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
   Area	La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
   Nome	Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
   Piano tariffario	Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

   

4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

5. Selezionare Rivedi e crea nella parte inferiore della pagina.

6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

   

2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

   

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

• Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
• Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

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.2.0</version>
    </dependency>
</dependencies>

Esempio di codice

Creare un file Java denominato Example.java. Aprire il file e copiare il codice seguente. A questo punto, eseguire il codice.

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 {

    // This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
    private static String languageKey = System.getenv("LANGUAGE_KEY");
    private static String languageEndpoint = System.getenv("LANGUAGE_ENDPOINT");

    public static void main(String[] args) {
        TextAnalyticsClient client = authenticateClient(languageKey, languageEndpoint);
        recognizeLinkedEntitiesExample(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 and providing a link to an online data source
    static void recognizeLinkedEntitiesExample(TextAnalyticsClient client)
    {
        // The text that need be analyzed.
        String text = "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, " +
                "to develop and sell BASIC interpreters for the Altair 8800. " +
                "During his career at Microsoft, Gates held the positions of chairman, " +
                "chief executive officer, president and chief software architect, " +
                "while also being the largest individual shareholder until May 2014.";

        System.out.printf("Linked Entities:%n");
        for (LinkedEntity linkedEntity : client.recognizeLinkedEntities(text)) {
            System.out.printf("Name: %s, ID: %s, URL: %s, Data Source: %s.%n",
                    linkedEntity.getName(),
                    linkedEntity.getDataSourceEntityId(),
                    linkedEntity.getUrl(),
                    linkedEntity.getDataSource());
            System.out.printf("Matches:%n");
            for (LinkedEntityMatch linkedEntityMatch : linkedEntity.getMatches()) {
                System.out.printf("Text: %s, Score: %.2f, Offset: %s, Length: %s%n",
                        linkedEntityMatch.getText(),
                        linkedEntityMatch.getConfidenceScore(),
                        linkedEntityMatch.getOffset(),
                        linkedEntityMatch.getLength());
            }
        }
    }
}

Output

Linked Entities:

Name: Microsoft, ID: Microsoft, URL: https://en.wikipedia.org/wiki/Microsoft, Data Source: Wikipedia.
Matches:
Text: Microsoft, Score: 0.55, Offset: 0, Length: 9
Text: Microsoft, Score: 0.55, Offset: 150, Length: 9
Name: Bill Gates, ID: Bill Gates, URL: https://en.wikipedia.org/wiki/Bill_Gates, Data Source: Wikipedia.
Matches:
Text: Bill Gates, Score: 0.63, Offset: 25, Length: 10
Text: Gates, Score: 0.63, Offset: 161, Length: 5
Name: Paul Allen, ID: Paul Allen, URL: https://en.wikipedia.org/wiki/Paul_Allen, Data Source: Wikipedia.
Matches:
Text: Paul Allen, Score: 0.60, Offset: 40, Length: 10
Name: April 4, ID: April 4, URL: https://en.wikipedia.org/wiki/April_4, Data Source: Wikipedia.
Matches:
Text: April 4, Score: 0.32, Offset: 54, Length: 7
Name: BASIC, ID: BASIC, URL: https://en.wikipedia.org/wiki/BASIC, Data Source: Wikipedia.
Matches:
Text: BASIC, Score: 0.33, Offset: 89, Length: 5
Name: Altair 8800, ID: Altair 8800, URL: https://en.wikipedia.org/wiki/Altair_8800, Data Source: Wikipedia.
Matches:
Text: Altair 8800, Score: 0.88, Offset: 116, Length: 11

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

• Azure portal
• Interfaccia della riga di comando di Azure

Passaggi successivi

• Lingue supportate per il collegamento delle entità
• Come chiamare l’API di collegamento delle entità
• Documentazione di riferimento *Altri esempi

Documentazione di riferimento | Altri esempi | Pacchetto (npm) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di collegamento delle entità con la libreria client per Node.js. Nell'esempio seguente viene creata un'applicazione JavaScript in grado di identificare e disambiguare le entità trovate nel testo.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Node.js v14 LTS o versione successiva

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio Lingua.

1. Usare il collegamento seguente per creare una risorsa Lingua tramite il portale di Azure. Sarà necessario accedere usando la propria sottoscrizione di Azure.

2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

   

3. Nella schermata Crea lingua specificare le informazioni seguenti:

   Dettagli	Descrizione
   Abbonamento	Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure nell'elenco a discesa.
   Gruppo di risorse	Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
   Area	La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
   Nome	Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
   Piano tariffario	Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

   

4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

5. Selezionare Rivedi e crea nella parte inferiore della pagina.

6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

   

2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

   

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

• Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
• Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

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-language-text

Esempio di codice

Aprire il file e copiare il codice seguente. A questo punto, eseguire il codice.

"use strict";

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

// This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
const key = process.env.LANGUAGE_KEY;
const endpoint = process.env.LANGUAGE_ENDPOINT;

//example sentence for recognizing entities
const documents = ["Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975."];

//example of how to use the client to perform entity linking on a document
async function main() {
    console.log("== Entity linking sample ==");
  
    const client = new TextAnalysisClient(endpoint, new AzureKeyCredential(key));
  
    const results = await client.analyze("EntityLinking", documents);
  
    for (const result of results) {
      console.log(`- Document ${result.id}`);
      if (!result.error) {
        console.log("\tEntities:");
        for (const entity of result.entities) {
          console.log(
            `\t- Entity ${entity.name}; link ${entity.url}; datasource: ${entity.dataSource}`
          );
          console.log("\t\tMatches:");
          for (const match of entity.matches) {
            console.log(
              `\t\t- Entity appears as "${match.text}" (confidence: ${match.confidenceScore}`
            );
          }
        }
      } else {
        console.error("  Error:", result.error);
      }
    }
  }

//call the main function
main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Output

== Entity linking sample ==
- Document 0
    Entities:
    - Entity Microsoft; link https://en.wikipedia.org/wiki/Microsoft; datasource: Wikipedia
            Matches:
            - Entity appears as "Microsoft" (confidence: 0.48
    - Entity Bill Gates; link https://en.wikipedia.org/wiki/Bill_Gates; datasource: Wikipedia
            Matches:
            - Entity appears as "Bill Gates" (confidence: 0.52
    - Entity Paul Allen; link https://en.wikipedia.org/wiki/Paul_Allen; datasource: Wikipedia
            Matches:
            - Entity appears as "Paul Allen" (confidence: 0.54
    - Entity April 4; link https://en.wikipedia.org/wiki/April_4; datasource: Wikipedia
            Matches:
            - Entity appears as "April 4" (confidence: 0.38

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

• Azure portal
• Interfaccia della riga di comando di Azure

Passaggi successivi

• Lingue supportate per il collegamento delle entità
• Come chiamare l’API di collegamento delle entità
• Documentazione di riferimento
• Ulteriori esempi

Documentazione di riferimento | Altri esempi | Pacchetto (PyPi) | Codice sorgente della libreria

Usare questa guida introduttiva per creare un'applicazione di collegamento delle entità con la libreria client per Python. Nell'esempio seguente viene creata un'applicazione Python in grado di identificare e disambiguare le entità trovate nel testo.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Python 3.7 o versione successiva

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio Lingua.

1. Usare il collegamento seguente per creare una risorsa Lingua tramite il portale di Azure. Sarà necessario accedere usando la propria sottoscrizione di Azure.

2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

   

3. Nella schermata Crea lingua specificare le informazioni seguenti:

   Dettagli	Descrizione
   Abbonamento	Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure nell'elenco a discesa.
   Gruppo di risorse	Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
   Area	La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
   Nome	Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
   Piano tariffario	Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

   

4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

5. Selezionare Rivedi e crea nella parte inferiore della pagina.

6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

   

2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

   

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

• Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
• Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Installare la libreria client

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

pip install azure-ai-textanalytics==5.2.0

Esempio di codice

Creare un nuovo file Python e copiare il codice seguente. A questo punto, eseguire il codice.

# This example requires environment variables named "LANGUAGE_KEY" and "LANGUAGE_ENDPOINT"
language_key = os.environ.get('LANGUAGE_KEY')
language_endpoint = os.environ.get('LANGUAGE_ENDPOINT')

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(language_key)
    text_analytics_client = TextAnalyticsClient(
            endpoint=language_endpoint, 
            credential=ta_credential)
    return text_analytics_client

client = authenticate_client()

# Example function for recognizing entities and providing a link to an online data source.
def entity_linking_example(client):

    try:
        documents = ["""Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, 
        to develop and sell BASIC interpreters for the Altair 8800. 
        During his career at Microsoft, Gates held the positions of chairman,
        chief executive officer, president and chief software architect, 
        while also being the largest individual shareholder until May 2014."""]
        result = client.recognize_linked_entities(documents = documents)[0]

        print("Linked Entities:\n")
        for entity in result.entities:
            print("\tName: ", entity.name, "\tId: ", entity.data_source_entity_id, "\tUrl: ", entity.url,
            "\n\tData Source: ", entity.data_source)
            print("\tMatches:")
            for match in entity.matches:
                print("\t\tText:", match.text)
                print("\t\tConfidence Score: {0:.2f}".format(match.confidence_score))
                print("\t\tOffset: {}".format(match.offset))
                print("\t\tLength: {}".format(match.length))
            
    except Exception as err:
        print("Encountered exception. {}".format(err))
entity_linking_example(client)

Output

Linked Entities:
    
    Name:  Microsoft        Id:  Microsoft  Url:  https://en.wikipedia.org/wiki/Microsoft
    Data Source:  Wikipedia
    Matches:
            Text: Microsoft
            Confidence Score: 0.55
            Offset: 0
            Length: 9
            Text: Microsoft
            Confidence Score: 0.55
            Offset: 168
            Length: 9
    Name:  Bill Gates       Id:  Bill Gates         Url:  https://en.wikipedia.org/wiki/Bill_Gates
    Data Source:  Wikipedia
    Matches:
            Text: Bill Gates
            Confidence Score: 0.63
            Offset: 25
            Length: 10
            Text: Gates
            Confidence Score: 0.63
            Offset: 179
            Length: 5
    Name:  Paul Allen       Id:  Paul Allen         Url:  https://en.wikipedia.org/wiki/Paul_Allen
    Data Source:  Wikipedia
    Matches:
            Text: Paul Allen
            Confidence Score: 0.60
            Offset: 40
            Length: 10
    Name:  April 4  Id:  April 4    Url:  https://en.wikipedia.org/wiki/April_4
    Data Source:  Wikipedia
    Matches:
            Text: BASIC
            Confidence Score: 0.33
            Offset: 98
            Length: 5
    Name:  Altair 8800      Id:  Altair 8800        Url:  https://en.wikipedia.org/wiki/Altair_8800
    Data Source:  Wikipedia
    Matches:
            Text: Altair 8800
            Confidence Score: 0.88
            Offset: 125
            Length: 11

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

• Azure portal
• Interfaccia della riga di comando di Azure

Passaggi successivi

• Lingue supportate per il collegamento delle entità
• Come chiamare l’API di collegamento delle entità
• Documentazione di riferimento
• Ulteriori esempi

Documentazione di riferimento

Usare questa guida introduttiva per inviare richieste di collegamento delle entità usando l'API REST. Nell'esempio seguente si userà cURL per identificare e disambiguare le entità trovate nel testo.

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito

Configurazione

Creare una risorsa di Azure

Per usare l'esempio di codice seguente, è necessario distribuire una risorsa di Azure. Questa risorsa conterrà una chiave e un endpoint che verranno usati per autenticare le chiamate API inviate al servizio Lingua.

1. Usare il collegamento seguente per creare una risorsa Lingua tramite il portale di Azure. Sarà necessario accedere usando la propria sottoscrizione di Azure.

2. Nella schermata Selezionare Funzionalità aggiuntive visualizzata selezionare Continua per creare la risorsa.

   

3. Nella schermata Crea lingua specificare le informazioni seguenti:

   Dettagli	Descrizione
   Abbonamento	Account di sottoscrizione a cui verrà associata la risorsa. Selezionare la sottoscrizione di Azure nell'elenco a discesa.
   Gruppo di risorse	Un gruppo di risorse è un contenitore in cui vengono archiviate le risorse create. Selezionare Crea nuovo per creare un nuovo gruppo di risorse.
   Area	La posizione della risorsa Lingua. Aree diverse possono introdurre latenza, in base alla posizione fisica, ma non hanno alcun impatto sulla disponibilità di runtime della risorsa. Per questo avvio rapido, selezionare un'area vicina disponibile oppure scegliere Stati Uniti orientali.
   Nome	Il nome della risorsa Lingua. Questo nome verrà usato anche per creare un URL dell'endpoint di cui le applicazioni usufruiranno per inviare richieste API.
   Piano tariffario	Il piano tariffario per la risorsa Lingua. È possibile usare il piano F0 Gratuito per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

   

4. Assicurarsi che sia selezionata la casella di controllo Informativa Intelligenza artificiale responsabile.

5. Selezionare Rivedi e crea nella parte inferiore della pagina.

6. Nella schermata visualizzata verificare che la convalida abbia avuto esito positivo e che le informazioni immesse siano corrette. Selezionare Crea.

Ottenere la chiave e l'endpoint

La chiave e l'endpoint ottenuti dalla risorsa saranno necessari per connettere l'applicazione all'API. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido.

1. Dopo aver distribuito correttamente la risorsa linguistica, fare clic sul pulsante Vai alla risorsa sotto a Passaggi successivi.

   

2. Nella schermata della risorsa selezionare Chiavi ed endpoint nel menu di spostamento a sinistra. Nei passaggi seguenti si useranno una delle chiavi e l'endpoint.

   

Creare variabili di ambiente

L'applicazione deve essere autenticata per poter inviare richieste API. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali. In questo esempio, sarà possibile scrivere le credenziali nelle variabili di ambiente nel computer locale che esegue l'applicazione.

Per impostare la variabile di ambiente per la chiave di risorsa Lingua, aprire una finestra della console e seguire le istruzioni per il sistema operativo e l'ambiente di sviluppo.

• Per impostare la variabile di ambiente LANGUAGE_KEY, sostituire your-key con una delle chiavi per la risorsa.
• Per impostare la LANGUAGE_ENDPOINTvariabile di ambiente, sostituire your-endpoint con l'endpoint della risorsa.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

export LANGUAGE_KEY=your-key

export LANGUAGE_ENDPOINT=your-endpoint

Creare un file JSON con il corpo della richiesta di esempio

In un editor di codice creare un nuovo file denominato test_entitylinking_payload.json e copiare l'esempio JSON seguente. Questa richiesta di esempio verrà inviata all'API nel passaggio successivo.

{
    "kind": "EntityLinking",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "language":"en",
                "text": "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975."
            }
        ]
    }
}

Salvare test_entitylinking_payload.json da qualche parte nel computer. Ad esempio, sul desktop.

Inviare una richiesta API di collegamento delle entità

Usare i comandi seguenti per inviare la richiesta API tramite il programma in uso. Copiare il comando nel terminale ed eseguirlo.

curl -X POST "%LANGUAGE_ENDPOINT%/language/:analyze-text?api-version=2022-05-01" ^
-H "Content-Type: application/json" ^
-H "Ocp-Apim-Subscription-Key: %LANGUAGE_KEY%" ^
-d "@C:\Users\<myaccount>\Desktop\test_entitylinking_payload.json"

curl.exe -X POST $env:LANGUAGE_ENDPOINT/language/:analyze-text?api-version=2022-05-01 `
-H "Content-Type: application/json" `
-H "Ocp-Apim-Subscription-Key: $env:LANGUAGE_KEY" `
-d "@C:\Users\<myaccount>\Desktop\test_entitylinking_payload.json"

curl -X POST $LANGUAGE_ENDPOINT/language/:analyze-text?api-version=2022-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" \
-d "@/home/mydir/test_entitylinking_payload.json"

curl -X POST $LANGUAGE_ENDPOINT/language/:analyze-text?api-version=2022-05-01 \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: $LANGUAGE_KEY" \
-d "@/home/mydir/test_entitylinking_payload.json"

Risposta JSON

{
	"kind": "EntityLinkingResults",
	"results": {
		"documents": [{
			"id": "1",
			"entities": [{
				"bingId": "a093e9b9-90f5-a3d5-c4b8-5855e1b01f85",
				"name": "Microsoft",
				"matches": [{
					"text": "Microsoft",
					"offset": 0,
					"length": 9,
					"confidenceScore": 0.48
				}],
				"language": "en",
				"id": "Microsoft",
				"url": "https://en.wikipedia.org/wiki/Microsoft",
				"dataSource": "Wikipedia"
			}, {
				"bingId": "0d47c987-0042-5576-15e8-97af601614fa",
				"name": "Bill Gates",
				"matches": [{
					"text": "Bill Gates",
					"offset": 25,
					"length": 10,
					"confidenceScore": 0.52
				}],
				"language": "en",
				"id": "Bill Gates",
				"url": "https://en.wikipedia.org/wiki/Bill_Gates",
				"dataSource": "Wikipedia"
			}, {
				"bingId": "df2c4376-9923-6a54-893f-2ee5a5badbc7",
				"name": "Paul Allen",
				"matches": [{
					"text": "Paul Allen",
					"offset": 40,
					"length": 10,
					"confidenceScore": 0.54
				}],
				"language": "en",
				"id": "Paul Allen",
				"url": "https://en.wikipedia.org/wiki/Paul_Allen",
				"dataSource": "Wikipedia"
			}, {
				"bingId": "52535f87-235e-b513-54fe-c03e4233ac6e",
				"name": "April 4",
				"matches": [{
					"text": "April 4",
					"offset": 54,
					"length": 7,
					"confidenceScore": 0.38
				}],
				"language": "en",
				"id": "April 4",
				"url": "https://en.wikipedia.org/wiki/April_4",
				"dataSource": "Wikipedia"
			}],
			"warnings": []
		}],
		"errors": [],
		"modelVersion": "2021-06-01"
	}
}

Pulire le risorse

Se si vuole pulire e rimuovere una sottoscrizione a Servizi di Azure AI, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.

• Azure portal
• Interfaccia della riga di comando di Azure

Passaggi successivi

• Lingue supportate per il collegamento delle entità
• Come chiamare l’API di collegamento delle entità
• Documentazione di riferimento