Partilhar via

Guia de início rápido: vinculação de entidade usando a biblioteca de cliente e a API REST

  • Artigo

Documentação | de referência Mais exemplos | Pacote (NuGet) | Código fonte da biblioteca

Use este início rápido para criar um aplicativo de vinculação de entidade com a biblioteca de cliente para .NET. No exemplo a seguir, você cria um aplicativo C# que pode identificar e desambiguar entidades encontradas no texto.

Gorjeta

Você pode usar o AI Studio para tentar resumir sem precisar escrever código.

Pré-requisitos

Configuração

Criar um recurso do Azure

Para usar o exemplo de código abaixo, você precisará implantar um recurso do Azure. Este recurso conterá uma chave e um ponto de extremidade que você usará para autenticar as chamadas de API enviadas ao serviço de idiomas.

  1. Use o link a seguir para criar um recurso de idioma usando o portal do Azure. Você precisará entrar usando sua assinatura do Azure.

  2. Na tela Selecionar recursos adicionais exibida, selecione Continuar para criar seu recurso.

    Uma captura de tela mostrando opções de recursos adicionais no portal do Azure.

  3. Na tela Criar idioma, forneça as seguintes informações:

    Detalhe Description
    Subscrição A conta de subscrição à qual o seu recurso será associado. Selecione sua assinatura do Azure no menu suspenso.
    Grupo de recursos Um grupo de recursos é um contêiner que armazena os recursos criados. Selecione Criar novo para criar um novo grupo de recursos.
    País/Região A localização do seu recurso de idioma. Regiões diferentes podem introduzir latência dependendo da sua localização física, mas não têm impacto na disponibilidade de tempo de execução do seu recurso. Para este início rápido, selecione uma região disponível perto de você ou escolha Leste dos EUA.
    Nome O nome do recurso Idioma. Esse nome também será usado para criar uma URL de ponto de extremidade que seus aplicativos usarão para enviar solicitações de API.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada F0 gratuita para experimentar o serviço e atualizar mais tarde para uma camada paga para produção.

    Uma captura de tela mostrando detalhes de criação de recursos no portal do Azure.

  4. Verifique se a caixa de seleção Aviso de IA Responsável está marcada.

  5. Selecione Rever + Criar na parte inferior da página.

  6. No ecrã apresentado, certifique-se de que a validação foi aprovada e de que introduziu as suas informações corretamente. Depois, selecione Criar.

Obtenha a sua chave e o seu ponto final

Em seguida, você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo à API. Você colará sua chave e ponto de extremidade no código mais tarde no início rápido.

  1. Depois que o recurso de idioma for implantado com êxito, clique no botão Ir para recurso em Próximas etapas.

    Uma captura de tela mostrando as próximas etapas após a implantação de um recurso.

  2. Na tela do seu recurso, selecione Chaves e ponto de extremidade no menu de navegação à esquerda. Você usará uma de suas chaves e seu endpoint nas etapas abaixo.

    Uma captura de tela mostrando as chaves e a seção de ponto de extremidade de um recurso.

Criar variáveis de ambiente

Seu aplicativo deve ser autenticado para enviar solicitações de API. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Neste exemplo, você gravará suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente para sua chave de recurso de idioma, abra uma janela de console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.

  • Para definir a LANGUAGE_KEY variável de ambiente, substitua your-key por uma das chaves do seu recurso.
  • Para definir a variável de LANGUAGE_ENDPOINT ambiente, substitua your-endpoint pelo ponto de extremidade do seu recurso.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se você só precisar acessar as variáveis de ambiente no console em execução atual, poderá definir a variável de ambiente com set em vez de setx.

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler as variáveis de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Criar uma nova aplicação .NET Core

Com o IDE do Visual Studio, crie uma nova aplicação de consola .NET Core. Isto irá criar um projeto "Hello World" com um único ficheiro de origem C#: program.cs.

Instale a biblioteca de cliente, clicando com o botão direito do rato na solução no Explorador de Soluções e selecionando Gerir Pacotes NuGet. No gerenciador de pacotes que é aberto, selecione Procurar e procure Azure.AI.TextAnalytics. Selecione a versão 5.2.0 e, em seguida, Instalar. Também pode utilizar a Consola do Gestor de Pacotes.

Exemplo de código

Copie o código a seguir para o arquivo program.cs e execute o código.

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

    }
}

Saída

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos

Documentação | de referência Mais exemplos | Pacote (Maven) | Código fonte da biblioteca

Use este início rápido para criar um aplicativo de vinculação de entidade com a biblioteca cliente para Java. No exemplo a seguir, você cria um aplicativo Java que pode identificar e desambiguar entidades encontradas no texto.

Pré-requisitos

Configuração

Criar um recurso do Azure

Para usar o exemplo de código abaixo, você precisará implantar um recurso do Azure. Este recurso conterá uma chave e um ponto de extremidade que você usará para autenticar as chamadas de API enviadas ao serviço de idiomas.

  1. Use o link a seguir para criar um recurso de idioma usando o portal do Azure. Você precisará entrar usando sua assinatura do Azure.

  2. Na tela Selecionar recursos adicionais exibida, selecione Continuar para criar seu recurso.

    Uma captura de tela mostrando opções de recursos adicionais no portal do Azure.

  3. Na tela Criar idioma, forneça as seguintes informações:

    Detalhe Description
    Subscrição A conta de subscrição à qual o seu recurso será associado. Selecione sua assinatura do Azure no menu suspenso.
    Grupo de recursos Um grupo de recursos é um contêiner que armazena os recursos criados. Selecione Criar novo para criar um novo grupo de recursos.
    País/Região A localização do seu recurso de idioma. Regiões diferentes podem introduzir latência dependendo da sua localização física, mas não têm impacto na disponibilidade de tempo de execução do seu recurso. Para este início rápido, selecione uma região disponível perto de você ou escolha Leste dos EUA.
    Nome O nome do recurso Idioma. Esse nome também será usado para criar uma URL de ponto de extremidade que seus aplicativos usarão para enviar solicitações de API.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada F0 gratuita para experimentar o serviço e atualizar mais tarde para uma camada paga para produção.

    Uma captura de tela mostrando detalhes de criação de recursos no portal do Azure.

  4. Verifique se a caixa de seleção Aviso de IA Responsável está marcada.

  5. Selecione Rever + Criar na parte inferior da página.

  6. No ecrã apresentado, certifique-se de que a validação foi aprovada e de que introduziu as suas informações corretamente. Depois, selecione Criar.

Obtenha a sua chave e o seu ponto final

Em seguida, você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo à API. Você colará sua chave e ponto de extremidade no código mais tarde no início rápido.

  1. Depois que o recurso de idioma for implantado com êxito, clique no botão Ir para recurso em Próximas etapas.

    Uma captura de tela mostrando as próximas etapas após a implantação de um recurso.

  2. Na tela do seu recurso, selecione Chaves e ponto de extremidade no menu de navegação à esquerda. Você usará uma de suas chaves e seu endpoint nas etapas abaixo.

    Uma captura de tela mostrando as chaves e a seção de ponto de extremidade de um recurso.

Criar variáveis de ambiente

Seu aplicativo deve ser autenticado para enviar solicitações de API. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Neste exemplo, você gravará suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente para sua chave de recurso de idioma, abra uma janela de console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.

  • Para definir a LANGUAGE_KEY variável de ambiente, substitua your-key por uma das chaves do seu recurso.
  • Para definir a variável de LANGUAGE_ENDPOINT ambiente, substitua your-endpoint pelo ponto de extremidade do seu recurso.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se você só precisar acessar as variáveis de ambiente no console em execução atual, poderá definir a variável de ambiente com set em vez de setx.

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler as variáveis de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Adicionar a biblioteca de cliente

Crie um projeto do Maven no IDE ou ambiente de desenvolvimento da sua preferência. Em seguida, adicione a seguinte dependência ao ficheiro pom.xml do projeto. Pode encontrar a sintaxe de implementação para outras ferramentas de criação 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 ficheiro Java com o nome Example.java. Abra o arquivo e copie o código abaixo. Em seguida, execute o código.

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

Saída

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos

Documentação | de referência Mais exemplos | Pacote (npm) | Código fonte da biblioteca

Use este início rápido para criar um aplicativo de vinculação de entidade com a biblioteca de cliente para Node.js. No exemplo a seguir, você cria um aplicativo JavaScript que pode identificar e desambiguar entidades encontradas no texto.

Pré-requisitos

Configuração

Criar um recurso do Azure

Para usar o exemplo de código abaixo, você precisará implantar um recurso do Azure. Este recurso conterá uma chave e um ponto de extremidade que você usará para autenticar as chamadas de API enviadas ao serviço de idiomas.

  1. Use o link a seguir para criar um recurso de idioma usando o portal do Azure. Você precisará entrar usando sua assinatura do Azure.

  2. Na tela Selecionar recursos adicionais exibida, selecione Continuar para criar seu recurso.

    Uma captura de tela mostrando opções de recursos adicionais no portal do Azure.

  3. Na tela Criar idioma, forneça as seguintes informações:

    Detalhe Description
    Subscrição A conta de subscrição à qual o seu recurso será associado. Selecione sua assinatura do Azure no menu suspenso.
    Grupo de recursos Um grupo de recursos é um contêiner que armazena os recursos criados. Selecione Criar novo para criar um novo grupo de recursos.
    País/Região A localização do seu recurso de idioma. Regiões diferentes podem introduzir latência dependendo da sua localização física, mas não têm impacto na disponibilidade de tempo de execução do seu recurso. Para este início rápido, selecione uma região disponível perto de você ou escolha Leste dos EUA.
    Nome O nome do recurso Idioma. Esse nome também será usado para criar uma URL de ponto de extremidade que seus aplicativos usarão para enviar solicitações de API.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada F0 gratuita para experimentar o serviço e atualizar mais tarde para uma camada paga para produção.

    Uma captura de tela mostrando detalhes de criação de recursos no portal do Azure.

  4. Verifique se a caixa de seleção Aviso de IA Responsável está marcada.

  5. Selecione Rever + Criar na parte inferior da página.

  6. No ecrã apresentado, certifique-se de que a validação foi aprovada e de que introduziu as suas informações corretamente. Depois, selecione Criar.

Obtenha a sua chave e o seu ponto final

Em seguida, você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo à API. Você colará sua chave e ponto de extremidade no código mais tarde no início rápido.

  1. Depois que o recurso de idioma for implantado com êxito, clique no botão Ir para recurso em Próximas etapas.

    Uma captura de tela mostrando as próximas etapas após a implantação de um recurso.

  2. Na tela do seu recurso, selecione Chaves e ponto de extremidade no menu de navegação à esquerda. Você usará uma de suas chaves e seu endpoint nas etapas abaixo.

    Uma captura de tela mostrando as chaves e a seção de ponto de extremidade de um recurso.

Criar variáveis de ambiente

Seu aplicativo deve ser autenticado para enviar solicitações de API. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Neste exemplo, você gravará suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente para sua chave de recurso de idioma, abra uma janela de console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.

  • Para definir a LANGUAGE_KEY variável de ambiente, substitua your-key por uma das chaves do seu recurso.
  • Para definir a variável de LANGUAGE_ENDPOINT ambiente, substitua your-endpoint pelo ponto de extremidade do seu recurso.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se você só precisar acessar as variáveis de ambiente no console em execução atual, poderá definir a variável de ambiente com set em vez de setx.

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler as variáveis de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Criar uma nova aplicação Node.js

Numa janela de consola (como cmd, PowerShell ou Bash), crie um novo diretório para a sua aplicação e navegue para a mesma.

mkdir myapp 

cd myapp

Execute o comando npm init para criar uma aplicação de nó com um ficheiro package.json.

npm init

Instalar a biblioteca de cliente

Instale o pacote npm:

npm install @azure/ai-language-text

Exemplo de código

Abra o arquivo e copie o código abaixo. Em seguida, execute o código.

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

Saída

== 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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos

Documentação | de referência Mais exemplos | Pacote (PyPi) | Código fonte da biblioteca

Use este início rápido para criar um aplicativo de vinculação de entidade com a biblioteca de cliente para Python. No exemplo a seguir, você cria um aplicativo Python que pode identificar e desambiguar entidades encontradas no texto.

Pré-requisitos

Configuração

Criar um recurso do Azure

Para usar o exemplo de código abaixo, você precisará implantar um recurso do Azure. Este recurso conterá uma chave e um ponto de extremidade que você usará para autenticar as chamadas de API enviadas ao serviço de idiomas.

  1. Use o link a seguir para criar um recurso de idioma usando o portal do Azure. Você precisará entrar usando sua assinatura do Azure.

  2. Na tela Selecionar recursos adicionais exibida, selecione Continuar para criar seu recurso.

    Uma captura de tela mostrando opções de recursos adicionais no portal do Azure.

  3. Na tela Criar idioma, forneça as seguintes informações:

    Detalhe Description
    Subscrição A conta de subscrição à qual o seu recurso será associado. Selecione sua assinatura do Azure no menu suspenso.
    Grupo de recursos Um grupo de recursos é um contêiner que armazena os recursos criados. Selecione Criar novo para criar um novo grupo de recursos.
    País/Região A localização do seu recurso de idioma. Regiões diferentes podem introduzir latência dependendo da sua localização física, mas não têm impacto na disponibilidade de tempo de execução do seu recurso. Para este início rápido, selecione uma região disponível perto de você ou escolha Leste dos EUA.
    Nome O nome do recurso Idioma. Esse nome também será usado para criar uma URL de ponto de extremidade que seus aplicativos usarão para enviar solicitações de API.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada F0 gratuita para experimentar o serviço e atualizar mais tarde para uma camada paga para produção.

    Uma captura de tela mostrando detalhes de criação de recursos no portal do Azure.

  4. Verifique se a caixa de seleção Aviso de IA Responsável está marcada.

  5. Selecione Rever + Criar na parte inferior da página.

  6. No ecrã apresentado, certifique-se de que a validação foi aprovada e de que introduziu as suas informações corretamente. Depois, selecione Criar.

Obtenha a sua chave e o seu ponto final

Em seguida, você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo à API. Você colará sua chave e ponto de extremidade no código mais tarde no início rápido.

  1. Depois que o recurso de idioma for implantado com êxito, clique no botão Ir para recurso em Próximas etapas.

    Uma captura de tela mostrando as próximas etapas após a implantação de um recurso.

  2. Na tela do seu recurso, selecione Chaves e ponto de extremidade no menu de navegação à esquerda. Você usará uma de suas chaves e seu endpoint nas etapas abaixo.

    Uma captura de tela mostrando as chaves e a seção de ponto de extremidade de um recurso.

Criar variáveis de ambiente

Seu aplicativo deve ser autenticado para enviar solicitações de API. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Neste exemplo, você gravará suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente para sua chave de recurso de idioma, abra uma janela de console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.

  • Para definir a LANGUAGE_KEY variável de ambiente, substitua your-key por uma das chaves do seu recurso.
  • Para definir a variável de LANGUAGE_ENDPOINT ambiente, substitua your-endpoint pelo ponto de extremidade do seu recurso.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se você só precisar acessar as variáveis de ambiente no console em execução atual, poderá definir a variável de ambiente com set em vez de setx.

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler as variáveis de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Instalar a biblioteca de cliente

Depois de instalar o Python, pode instalar a biblioteca de cliente com:

pip install azure-ai-textanalytics==5.2.0

Exemplo de código

Crie um novo arquivo Python e copie o código abaixo. Em seguida, execute o código.

# 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)

Saída

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos

Documentação de referência

Use este início rápido para enviar solicitações de vinculação de entidade usando a API REST. No exemplo a seguir, você usará cURL para identificar e desambiguar entidades encontradas no texto.

Pré-requisitos

Configuração

Criar um recurso do Azure

Para usar o exemplo de código abaixo, você precisará implantar um recurso do Azure. Este recurso conterá uma chave e um ponto de extremidade que você usará para autenticar as chamadas de API enviadas ao serviço de idiomas.

  1. Use o link a seguir para criar um recurso de idioma usando o portal do Azure. Você precisará entrar usando sua assinatura do Azure.

  2. Na tela Selecionar recursos adicionais exibida, selecione Continuar para criar seu recurso.

    Uma captura de tela mostrando opções de recursos adicionais no portal do Azure.

  3. Na tela Criar idioma, forneça as seguintes informações:

    Detalhe Description
    Subscrição A conta de subscrição à qual o seu recurso será associado. Selecione sua assinatura do Azure no menu suspenso.
    Grupo de recursos Um grupo de recursos é um contêiner que armazena os recursos criados. Selecione Criar novo para criar um novo grupo de recursos.
    País/Região A localização do seu recurso de idioma. Regiões diferentes podem introduzir latência dependendo da sua localização física, mas não têm impacto na disponibilidade de tempo de execução do seu recurso. Para este início rápido, selecione uma região disponível perto de você ou escolha Leste dos EUA.
    Nome O nome do recurso Idioma. Esse nome também será usado para criar uma URL de ponto de extremidade que seus aplicativos usarão para enviar solicitações de API.
    Escalão de preço A camada de preço para seu recurso de idioma. Você pode usar a camada F0 gratuita para experimentar o serviço e atualizar mais tarde para uma camada paga para produção.

    Uma captura de tela mostrando detalhes de criação de recursos no portal do Azure.

  4. Verifique se a caixa de seleção Aviso de IA Responsável está marcada.

  5. Selecione Rever + Criar na parte inferior da página.

  6. No ecrã apresentado, certifique-se de que a validação foi aprovada e de que introduziu as suas informações corretamente. Depois, selecione Criar.

Obtenha a sua chave e o seu ponto final

Em seguida, você precisará da chave e do ponto de extremidade do recurso para conectar seu aplicativo à API. Você colará sua chave e ponto de extremidade no código mais tarde no início rápido.

  1. Depois que o recurso de idioma for implantado com êxito, clique no botão Ir para recurso em Próximas etapas.

    Uma captura de tela mostrando as próximas etapas após a implantação de um recurso.

  2. Na tela do seu recurso, selecione Chaves e ponto de extremidade no menu de navegação à esquerda. Você usará uma de suas chaves e seu endpoint nas etapas abaixo.

    Uma captura de tela mostrando as chaves e a seção de ponto de extremidade de um recurso.

Criar variáveis de ambiente

Seu aplicativo deve ser autenticado para enviar solicitações de API. Para produção, use uma maneira segura de armazenar e acessar suas credenciais. Neste exemplo, você gravará suas credenciais em variáveis de ambiente na máquina local que executa o aplicativo.

Para definir a variável de ambiente para sua chave de recurso de idioma, abra uma janela de console e siga as instruções para seu sistema operacional e ambiente de desenvolvimento.

  • Para definir a LANGUAGE_KEY variável de ambiente, substitua your-key por uma das chaves do seu recurso.
  • Para definir a variável de LANGUAGE_ENDPOINT ambiente, substitua your-endpoint pelo ponto de extremidade do seu recurso.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

setx LANGUAGE_KEY your-key

setx LANGUAGE_ENDPOINT your-endpoint

Nota

Se você só precisar acessar as variáveis de ambiente no console em execução atual, poderá definir a variável de ambiente com set em vez de setx.

Depois de adicionar as variáveis de ambiente, talvez seja necessário reiniciar todos os programas em execução que precisarão ler as variáveis de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Criar um arquivo JSON com o corpo da solicitação de exemplo

Em um editor de códigos, crie um novo arquivo chamado test_entitylinking_payload.json e copie o exemplo JSON a seguir. Esta solicitação de exemplo será enviada para a API na próxima etapa.

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

Guarde test_entitylinking_payload.json algures no seu computador. Por exemplo, o seu ambiente de trabalho.

Enviar uma solicitação de API de vinculação de entidade

Use os comandos a seguir para enviar a solicitação de API usando o programa que você está usando. Copie o comando para o terminal e execute-o.

parâmetro Description
-X POST <endpoint> Especifica seu ponto de extremidade para acessar a API.
-H Content-Type: application/json O tipo de conteúdo para enviar dados JSON.
-H "Ocp-Apim-Subscription-Key:<key> Especifica a chave para acessar a API.
-d <documents> O JSON que contém os documentos que você deseja enviar.

Substitua C:\Users\<myaccount>\Desktop\test_entitylinking_payload.json pelo local do arquivo de solicitação JSON de exemplo criado na etapa anterior.

Linha de comandos

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"

PowerShell

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"

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

Clean up resources (Limpar recursos)

Se quiser limpar e remover uma assinatura de serviços do Azure AI, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.

Próximos passos