Compartilhar via


Adicionar o reconhecimento de idioma natural ao seu bot

APLICA-SE A: SDK v4

Observação

O reconhecimento de linguagem (LUIS) será desativado em 1º de outubro de 2025. A partir de 1º de abril de 2023, você não poderá criar recursos do LUIS. Uma versão mais recente do reconhecimento de linguagem já está disponível como parte da Linguagem de IA do Azure.

A compreensão da linguagem coloquial (CLU), um recurso da Linguagem de IA do Azure, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte ao reconhecimento de linguagem no SDK do Bot Framework, confira Reconhecimento de linguagem natural.

A capacidade de entender o que seu usuário quer dizer contextualmente e em conversas pode ser uma tarefa difícil, mas pode dar ao seu bot uma sensação de conversa mais natural. O LUIS (Reconhecimento vocal) é um serviço de API baseado em nuvem que permite que você faça exatamente isso, para que o seu bot possa reconhecer a intenção das mensagens do usuário, permitir uma linguagem mais natural do seu usuário e direcionar melhor o fluxo de conversação.

Este tópico explica como adicionar LUIS a um aplicativo de reservas de voo para reconhecer intenções e entidades diferentes contidas na entrada do usuário.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copiloto certa.

Para obter mais informações, confira O futuro da criação de bots.

Pré-requisitos

Sobre este exemplo

Essa amostra de bot básico mostra um exemplo de um aplicativo de reservas de voo em aeroportos. Ele usa um serviço do LUIS para reconhecer a entrada do usuário e retornar a melhor intenção reconhecida pelo LUIS.

O modelo de linguagem contém três intenções: Book Flight, Cancel e None. O LUIS usará essas intenções para entender o que o usuário pretendia ao enviar uma mensagem ao bot. O modelo de linguagem também define as entidades que o LUIS pode extrair da entrada do usuário, como o aeroporto de origem ou de destino.

Após cada processamento da entrada do usuário, DialogBot salva o estado atual de UserState e ConversationState. Depois que todas as informações necessárias forem coletadas, o exemplo de código cria uma reserva “Reservar voo” de demonstração. Neste artigo, abordaremos os aspectos do LUIS para esta amostra. No entanto, o fluxo geral da amostra é:

  • OnMembersAddedAsync é chamado quando um novo usuário é conectado e exibe um cartão de boas-vindas.
  • OnMessageActivityAsync é chamado em cada entrada de usuário recebida.

Diagrama de classes que descreve a estrutura do exemplo C#.

O módulo OnMessageActivityAsync executa o diálogo apropriado por meio do método de extensão de diálogo Run. Em seguida, a caixa de diálogo principal chama o auxiliar do LUIS para localizar a intenção do usuário com melhor pontuação. Se a intenção principal para a entrada do usuário retornar "BookFlight", o auxiliar preencherá as informações do usuário retornadas pelo LUIS. Depois disso, a caixa de diálogo principal inicia o BookingDialog, que adquire informações adicionais do usuário conforme necessário, tais como:

  • Origin a cidade de origem
  • TravelDate a data da reserva do voo
  • Destination a cidade de destino

Este artigo aborda como adicionar o LUIS a um bot. Para obter informações sobre como usar diálogos ou estado, consulte como coletar entradas do usuário usando um prompt de diálogo ou como salvar dados do usuário e da conversa, respectivamente.

Criar um aplicativo LUIS no portal do LUIS

  1. Inicie a sessão no portal do LUIS e, se necessário, crie uma conta e um recurso de criação.
  2. Na página Aplicativos de conversação no LUIS, escolha Importar e, em seguida, Importar como JSON.
  3. No diálogo Importar novo aplicativo:
    1. Escolha o arquivo FlightBooking.json na pasta CognitiveModels da amostra.
    2. Insira FlightBooking como o nome opcional do aplicativo e escolha Concluído.
  4. O site pode exibir os diálogos Como criar um aplicativo do LUIS efetivo e Atualizar as entidades de composição. Você pode ignorar esses diálogos e continuar.
  5. Treine o aplicativo e, em seguida, publique-o no ambiente de produção. Para obter mais informações, confira a documentação do LUIS sobre como treinar e publicar um aplicativo.

Por que usar entidades?

As entidades do LUIS possibilitam que o seu bot tenha reconhecimento de eventos além das intenções padrão. Isso permite que você colete informações adicionais dos usuários, para que seu bot possa fazer perguntas e responder de forma mais inteligente. Em conjunto com as definições para as três intenções do LUIS “Reservar voo”, “Cancelar” e “Nenhum”, o arquivo FlightBooking.json também contém um conjunto de entidades, como “From.Airport” e “To.Airport”. Essas entidades permitem que o LUIS detecte e retorne informações adicionais contidas na entrada original do usuário, quando ele solicitar uma nova reserva de viagem.

Obter valores para conectar ao seu aplicativo LUIS

Após a publicação de seu aplicativo LUIS, acesse-o no bot. Será necessário registrar vários valores para acessar o aplicativo do LUIS no bot. Você pode recuperar essas informações usando o portal do LUIS.

Recuperar informações do aplicativo do portal LUIS.ai

O arquivo de configurações (appsettings.json, .env ou config.py) age como um único local para reunir todas as referências de serviço. As informações que você recupera serão adicionadas a esse arquivo na próxima seção.

  1. Marque seu aplicativo LUIS publicado em luis.ai.

  2. Com o aplicativo LUIS publicado aberto, escolha a guia GERENCIAR.

  3. Selecione a guia Configurações no lado esquerdo e registre o valor mostrado para ID do Aplicativo como <YOUR_APP_ID>.

    Captura de tela da página Gerenciar exibindo a ID do aplicativo.

  4. Selecione Recursos do Azure e, em seguida, Recurso de Previsão. Registre o valor mostrado para Localização como <YOUR_REGION> e Chave Primária como <YOUR_AUTHORING_KEY>.

    Captura de tela da página Gerenciar exibindo sua localização e chave primária.

    Como alternativa, é possível usar a região e a chave primária para seu recurso de criação.

Atualizar o arquivo de configurações

Adicione as informações necessárias para acessar o aplicativo do LUIS, incluindo a ID do aplicativo, a chave de criação e a região, no arquivo appsettings.json. Na etapa anterior, esses valores foram recuperados do aplicativo do LUIS publicado. O nome do host da API deve estar no formato <your region>.api.cognitive.microsoft.com.

appsetting.json

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "LuisAppId": "",
  "LuisAPIKey": "",
  "LuisAPIHostName": ""
}

Configure seu bot para usar seu aplicativo LUIS

Verifique se o pacote do NuGet Microsoft.Bot.Builder.AI.Luis está instalado para o seu projeto.

Para se conectar ao serviço do LUIS, o bot transfere as informações que você adicionou ao arquivo appsetting.json. A classe FlightBookingRecognizer contém código com as configurações do arquivo appsetting.json e consulta o serviço do LUIS chamando o método RecognizeAsync.

FlightBookingRecognizer.cs

public class FlightBookingRecognizer : IRecognizer
{
    private readonly LuisRecognizer _recognizer;

    public FlightBookingRecognizer(IConfiguration configuration)
    {
        var luisIsConfigured = !string.IsNullOrEmpty(configuration["LuisAppId"]) && !string.IsNullOrEmpty(configuration["LuisAPIKey"]) && !string.IsNullOrEmpty(configuration["LuisAPIHostName"]);
        if (luisIsConfigured)
        {
            var luisApplication = new LuisApplication(
                configuration["LuisAppId"],
                configuration["LuisAPIKey"],
                "https://" + configuration["LuisAPIHostName"]);
            // Set the recognizer options depending on which endpoint version you want to use.
            // More details can be found in https://docs.microsoft.com/en-gb/azure/cognitive-services/luis/luis-migration-api-v3
            var recognizerOptions = new LuisRecognizerOptionsV3(luisApplication)
            {
                PredictionOptions = new Bot.Builder.AI.LuisV3.LuisPredictionOptions
                {
                    IncludeInstanceData = true,
                }
            };

            _recognizer = new LuisRecognizer(recognizerOptions);
        }
    }

    // Returns true if luis is configured in the appsettings.json and initialized.
    public virtual bool IsConfigured => _recognizer != null;

    public virtual async Task<RecognizerResult> RecognizeAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        => await _recognizer.RecognizeAsync(turnContext, cancellationToken);

    public virtual async Task<T> RecognizeAsync<T>(ITurnContext turnContext, CancellationToken cancellationToken)
        where T : IRecognizerConvert, new()
        => await _recognizer.RecognizeAsync<T>(turnContext, cancellationToken);
}

O FlightBookingEx.cs contém a lógica para extrair From, To e TravelDate; ela estende a classe parcial FlightBooking.cs usada para armazenar os resultados do LUIS ao chamar FlightBookingRecognizer.RecognizeAsync<FlightBooking> do MainDialog.cs.

CognitiveModels\FlightBookingEx.cs

// Extends the partial FlightBooking class with methods and properties that simplify accessing entities in the luis results
public partial class FlightBooking
{
    public (string From, string Airport) FromEntities
    {
        get
        {
            var fromValue = Entities?._instance?.From?.FirstOrDefault()?.Text;
            var fromAirportValue = Entities?.From?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (fromValue, fromAirportValue);
        }
    }

    public (string To, string Airport) ToEntities
    {
        get
        {
            var toValue = Entities?._instance?.To?.FirstOrDefault()?.Text;
            var toAirportValue = Entities?.To?.FirstOrDefault()?.Airport?.FirstOrDefault()?.FirstOrDefault();
            return (toValue, toAirportValue);
        }
    }

    // This value will be a TIMEX. And we are only interested in a Date so grab the first result and drop the Time part.
    // TIMEX is a format that represents DateTime expressions that include some ambiguity. e.g. missing a Year.
    public string TravelDate
        => Entities.datetime?.FirstOrDefault()?.Expressions.FirstOrDefault()?.Split('T')[0];
}

Agora, o LUIS está configurado e conectado ao seu bot.

Testar o bot

Baixe e instale o Bot Framework Emulator mais recente

  1. Execute o exemplo localmente em seu computador. Se precisar de instruções, veja o arquivo README para a amostra de C#, amostra de JS ou amostra de Python.

  2. No Emulator, digite uma mensagem, como “viagem para Paris” ou “viajar de Paris para Berlim”. Use qualquer enunciado encontrado no arquivo FlightBooking.json para treinar a intenção "Reservar voo".

Se a intenção principal retornada do LUIS for “Reservar voo”, o bot fará mais perguntas até ter informações suficientes armazenadas para criar uma reserva de viagem. Nesse ponto, ele retornará essas informações de reserva para o usuário.

Neste ponto, a lógica do bot de código será restaurada e você poderá continuar a criar mais reservas.

Informações adicionais

Para obter mais informações sobre o LUIS, consulte a documentação dele:

Dica

Diferentes partes do SDK definem classes ou elementos de entidade separados. Para entidades de mensagens, confira Entidades e tipos de atividades.