Início Rápido: Detectando entidades nomeadas (NER)

Documentação de referência | Amostras adicionais | Pacote (NuGet) | Código-fonte da biblioteca

Use este início rápido para criar um aplicativo NER (Reconhecimento de Entidade Nomeada) com a biblioteca de clientes para .NET. No exemplo a seguir, você criará um aplicativo C# que pode identificar entidades reconhecidas no texto.

Dica

Use o Language Studio para experimentar os recursos do serviço de linguagem sem a necessidade de gravar o código.

Pré-requisitos

• Assinatura do Azure – Criar uma gratuitamente
• O IDE do Visual Studio
• Após obter sua assinatura do Azure, crie um recurso de Linguagem no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
  • Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.
• Para usar o recurso Analisar, você precisará de um recurso de Linguagem com o tipo de preço S (Standard).

Configurando

Criar um aplicativo .NET Core

Usando o IDE do Visual Studio, crie um aplicativo de console do .NET Core. Isso criará um projeto "Olá, Mundo" com um arquivo de origem C#: program.cs.

Instale a biblioteca de cliente clicando com o botão direito do mouse na solução no Gerenciador de Soluções e selecionando Gerenciar Pacotes do NuGet. No gerenciador de pacotes que é aberto, selecione Procurar e pesquise por Azure.AI.TextAnalytics. Selecione a versão 5.2.0 e, em seguida, Instalar. Você também pode usar o Console do Gerenciador de Pacotes.

Exemplo de código

Copie o código a seguir para o arquivo program.cs. Lembre-se de substituir a variável key pela chave do recurso e substituir a variável endpoint pelo ponto de extremidade do recurso. Depois, execute o código.

Importante

Vá para o portal do Azure. Se o recurso de Linguagem que você criou na seção Pré-requisitos tiver sido implantado com êxito, clique no botão Ir para o recurso em Próximas Etapas. Para encontrar a chave e o ponto de extremidade, acesse a página Chaves e Ponto de Extremidade do recurso em Gerenciamento de Recursos.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Confira o artigo sobre segurança dos serviços de IA do Azure para obter mais informações.

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();
        }

    }
}

Saída

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

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

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

Documentação de referência | Amostras adicionais | Pacote (Maven) | Código-fonte da biblioteca

Use este início rápido para criar um aplicativo NER (Reconhecimento de Entidade Nomeada) com a biblioteca de clientes para Java. No exemplo a seguir, você criará um aplicativo Java que pode identificar entidades reconhecidas no texto.

Dica

Use o Language Studio para experimentar os recursos do serviço de linguagem sem a necessidade de gravar o código.

Pré-requisitos

• Assinatura do Azure – Criar uma gratuitamente
• JDK (Java Development Kit) com a versão 8 ou superior
• Após obter sua assinatura do Azure, crie um recurso de Linguagem no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
  • Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.
• Para usar o recurso Analisar, você precisará de um recurso de Linguagem com o tipo de preço S (Standard).

Configurando

Adicionar a biblioteca de clientes

Crie um projeto Maven no IDE ou no ambiente de desenvolvimento de sua preferência. Em seguida, adicione a dependência a seguir ao arquivo pom.xml do projeto. Você pode encontrar a sintaxe de implementação para outras ferramentas de build online.

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

Exemplo de código

Crie um arquivo Java chamado Example.java. Abra o arquivo e copie o código abaixo. Lembre-se de substituir a variável key pela chave do recurso e substituir a variável endpoint pelo ponto de extremidade do recurso. Depois, execute o código.

Importante

Vá para o portal do Azure. Se o recurso de Linguagem que você criou na seção Pré-requisitos tiver sido implantado com êxito, clique no botão Ir para o recurso em Próximas Etapas. Para encontrar a chave e o ponto de extremidade, acesse a página Chaves e Ponto de Extremidade do recurso em Gerenciamento de Recursos.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Confira o artigo sobre segurança dos serviços de IA do Azure para obter mais informações.

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());
        }
    }
}

Saída

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.

Documentação de referência | Amostras adicionais | Pacote (npm) | Código-fonte da biblioteca

Use este início rápido para criar um aplicativo NER (Reconhecimento de Entidade Nomeada) com a biblioteca de clientes para Node.js. No exemplo a seguir, você criará um aplicativo JavaScript que pode identificar entidades reconhecidas no texto.

Dica

Use o Language Studio para experimentar os recursos do serviço de linguagem sem a necessidade de gravar o código.

Pré-requisitos

• Assinatura do Azure – Criar uma gratuitamente
• Node.js v14 LTS ou posterior
• Após obter sua assinatura do Azure, crie um recurso de Linguagem no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
  • Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.
• Para usar o recurso Analisar, você precisará de um recurso de Linguagem com o tipo de preço S (Standard).

Configurando

Criar um novo aplicativo do Node.js

Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para seu aplicativo e navegue até ele.

mkdir myapp 

cd myapp

Execute o comando npm init para criar um aplicativo do Node com um arquivo package.json.

npm init

Instalar a biblioteca de clientes

Instale o pacote npm:

npm install @azure/ai-language-text

Exemplo de código

Abra o arquivo e copie o código abaixo. Lembre-se de substituir a variável key pela chave do recurso e substituir a variável endpoint pelo ponto de extremidade do recurso. Depois, execute o código.

Importante

Vá para o portal do Azure. Se o recurso de Linguagem que você criou na seção Pré-requisitos tiver sido implantado com êxito, clique no botão Ir para o recurso em Próximas Etapas. Para encontrar a chave e o ponto de extremidade, acesse a página Chaves e Ponto de Extremidade do recurso em Gerenciamento de Recursos.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Confira o artigo sobre segurança dos serviços de IA do Azure para obter mais informações.

"use strict";

const { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");;
const key = '<paste-your-key-here>';
const endpoint = '<paste-your-endpoint-here>';

//an example document for entity recognition
const documents = [ "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800"];

//example of how to use the client library to recognize entities in a document.
async function main() {
    console.log("== NER sample ==");
  
    const client = new TextAnalysisClient(endpoint, new AzureKeyCredential(key));
  
    const results = await client.analyze("EntityRecognition", documents);
  
    for (const result of results) {
      console.log(`- Document ${result.id}`);
      if (!result.error) {
        console.log("\tRecognized Entities:");
        for (const entity of result.entities) {
          console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
        }
      } else console.error("\tError:", result.error);
    }
  }

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

Saída

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

Documentação de referência | Amostras adicionais | Pacote (PyPi) | Código-fonte da biblioteca

Use este início rápido para criar um aplicativo NER (Reconhecimento de Entidade Nomeada) com a biblioteca de clientes para Python. No exemplo a seguir, você criará um aplicativo Python que pode identificar entidades reconhecidas no texto.

Dica

Use o Language Studio para experimentar os recursos do serviço de linguagem sem a necessidade de gravar o código.

Pré-requisitos

• Assinatura do Azure – Criar uma gratuitamente
• Python 3.8 ou posterior
• Após obter sua assinatura do Azure, crie um recurso de Linguagem no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
  • Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.
• Para usar o recurso Analisar, você precisará de um recurso de Linguagem com o tipo de preço S (Standard).

Configurando

Instalar a biblioteca de clientes

Depois de instalar o Python, você pode instalar a biblioteca de clientes com:

pip install azure-ai-textanalytics==5.2.0

Exemplo de código

Crie um novo arquivo Python e copie o código abaixo. Lembre-se de substituir a variável key pela chave do recurso e substituir a variável endpoint pelo ponto de extremidade do recurso. Depois, execute o código.

Importante

Vá para o portal do Azure. Se o recurso de Linguagem que você criou na seção Pré-requisitos tiver sido implantado com êxito, clique no botão Ir para o recurso em Próximas Etapas. Para encontrar a chave e o ponto de extremidade, acesse a página Chaves e Ponto de Extremidade do recurso em Gerenciamento de Recursos.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Confira o artigo sobre segurança dos serviços de IA do Azure para obter mais informações.

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)

Saída

Named Entities:

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

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

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

Documentação de referência

Use este início rápido para enviar o NER (Reconhecimento de Entidade Nomeada) usando a API REST. No exemplo a seguir, você usará o cURL para identificar entidades reconhecidas no texto.

Dica

Use o Language Studio para experimentar os recursos do serviço de linguagem sem a necessidade de gravar o código.

Pré-requisitos

• A versão atual do cURL.
• Após obter sua assinatura do Azure, crie um recurso de Linguagem no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisa da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API. Cole a chave e o ponto de extremidade no código mais adiante no início rápido.
  • Use o tipo de preço gratuito (Free F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Observação

• Os exemplos de BASH a seguir usam o caractere de continuação de linha \. Se o console ou o terminal usar um caractere de continuação de linha diferente, use aquele caractere.
• Você pode encontrar exemplos específicos de cada linguagem de programação no GitHub.
• Acesse o portal do Azure e localize a chave e o ponto de extremidade do recurso de Linguagem criados nos pré-requisitos. Eles estão localizados na página de chave e ponto de extremidade do recurso, em gerenciamento de recursos. Em seguida, substitua as cadeias de caracteres no código pela chave e o ponto de extremidade. Para chamar a API, você precisará das seguintes informações:

parâmetro	Descrição
-X POST <endpoint>	Especifica o ponto de extremidade para acessar a API.
-H Content-Type: application/json	Tipo de conteúdo para enviar dados JSON.
-H "Ocp-Apim-Subscription-Key:<key>	Especifica a chave para acessar a API.
-d <documents>	JSON contendo os documentos que você deseja enviar.

Os comandos cURL a seguir são executados por meio de um shell BASH. Edite esses comandos com o nome do recurso, a chave do recurso e os valores de JSON desejados.

Extração de Entidade Nomeada (NER)

1. Copie o comando para um editor de texto.
2. Faça as alterações a seguir no comando quando necessário:
   1. Substitua o valor <your-language-resource-key> pela chave.
   2. Substitua a primeira parte da URL de solicitação <your-language-resource-endpoint> pela sua URL do ponto de extremidade.
3. Abra una janela de prompt de comando.
4. Cole o comando do editor de texto na janela do prompt de comando e, em seguida, execute-o.

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."
            }
        ]
    }
}
'

Resposta JSON

Observação

• A API em disponibilidade geral e a API de visualização atual têm formatos de resposta diferentes. Consulte o artigo de mapeamento de API em disponibilidade para API de visualização.
• A API de visualização está disponível a partir da versão de API 2023-04-15-preview.

API em disponibilidade geral

{
	"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"
	}
}

API de visualização

{
	"kind": "EntityRecognitionResults",
	"results": {
		"documents": [{
			"id": "1",
			"entities": [{
				"text": "trip",
				"type": "Event",
				"offset": 18,
				"length": 4,
				"score": 0.74,
				"tags": ["Event"]
			}, {
				"text": "Seattle",
				"type": "Location",
				"offset": 26,
				"length": 7,
				"score": 1.0,
				"tags": ["Location", "GPE", "City"]
			}, {
				"text": "last week",
				"type": "Temporal",
				"offset": 34,
				"length": 9,
				"score": 0.8,
				"tags": ["Temporal", "DateRange"],
				"metadata": {
					"begin": "2022-01-03 00:00:00",
					"end": "2022-01-10 00:00:00"
				}
			}],
			"warnings": []
		}],
		"errors": [],
		"modelVersion": "2023-04-01"
	}
}

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de IA do Azure, você poderá excluir o recurso ou grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.

• Portal
• CLI do Azure

Próximas etapas

• Visão geral do NER