Usar o Dispatch (preterido) para a resolução de intenção

APLICA-SE A: SDK v4

Se um bot usa vários modelos luis e bases de dados de conhecimento do QnA Maker (bases de dados de conhecimento), você pode usar a ferramenta Dispatch para determinar qual modelo luis ou QnA Maker base de dados de conhecimento melhor corresponde à entrada do usuário. A ferramenta Dispatch faz isso criando um aplicativo LUIS individual a fim de encaminhar a entrada do usuário para o modelo correto. Para obter mais informações sobre o Dispatch, incluindo os comandos da CLI, consulte o README de Expedição.

Importante

Dispatch está no caminho a ser preterido e substituído pelo Bot Framework Orchestrator. Para obter informações sobre como migrar seu bot do LUIS Dispatch para o Orchestrator, consulte Exemplo de migração do LUIS Dispatch para o Orchestrator.

Pré-requisitos

Observação

  • O exemplo 14.nlp-with-orchestrator (C# ou JavaScript) demonstra como usar o Orchestrator para expedição. O processo para usar o LUIS Dispatch é semelhante.
  • O exemplo 14.nlp-with-dispatch (Java ou Python) demonstra como usar o LUIS Dispatch.

Sobre as amostras

Os exemplos são baseados em um conjunto predefinido de aplicativos LUIS e QnA Maker, com base em arquivos em uma subpasta de modelos cognitivos .

  • QnAMaker.tsv – para perguntas frequentes sobre bot.
  • Weather.json: para consultas de previsão do tempo.
  • homeAutomation.json: para comandos de iluminação doméstica.

Nesse cenário, o manipulador de atividade de mensagem usa um modelo de linguagem combinado para determinar qual aplicativo corresponde melhor à mensagem do usuário. Em seguida, o bot encaminha o controle para o manipulador apropriado.

OnMessageActivityAsync é chamado em cada entrada do usuário recebida. Este módulo localiza a intenção do usuário de pontuação superior e passa esse resultado para DispatchToTopIntentAsync, o que, por sua vez, chama o manipulador de aplicativo apropriado.

O manipulador chama o serviço LUIS ou QnA Maker e retorna o resultado gerado para o usuário.

Criar aplicativos LUIS e base de dados de conhecimento do QnA

Antes de criar o modelo do Dispatch, você precisará ter seus aplicativos LUIS e bases de dados de conhecimento do QnA criados e publicados. Neste artigo, publicaremos os seguintes modelos que foram incluídos no exemplo NLP com Dispatch na pasta \CognitiveModels:

Nome Descrição
HomeAutomation Um aplicativo LUIS que reconhece uma intenção de automação residencial com dados de entidade associados.
Clima Um aplicativo LUIS que reconhece intenções relacionadas ao clima com os dados de localização.
QnAMaker Uma base de dados de conhecimento do QnA Maker que fornece respostas a perguntas simples sobre o bot.

Crie o LUIS aplicativos

  1. Crie um aplicativo LUIS a partir do arquivo JSON de automação residencial no diretório de modelos cognitivos do exemplo.
    1. Treine e publique o aplicativo no ambiente de produção.
    2. Registre a ID do aplicativo, o nome de exibição, a chave de criação e o local.
  2. Repita estas etapas para o arquivo JSON do tempo .

Para obter mais informações, confira como criar um aplicativo LUIS no portal do LUIS e obter valores para se conectar ao seu aplicativo LUIS em Adicionar compreensão de linguagem natural ao seu bot e à documentação do LUIS sobre como treinar e publicar um aplicativo no ambiente de produção.

Criar o QnA Maker base de dados de conhecimento

O primeiro passo para definir uma base de dados de conhecimento do QnA Maker é configurar um serviço do QnA Maker no Azure. Para fazer isso, siga as instruções passo a passo que encontraram o artigo de configuração do serviço qnamaker .

Depois que o serviço QnA Maker é criado no Azure, você precisa registrar a Chave 1 dos Serviços Cognitivos fornecida por seu serviço QnA Maker. Isso será usado como <azure-qna-service-key1> ao adicionar o aplicativo QnA Maker ao aplicativo de expedição.

Saiba mais sobre os dois tipos diferentes de chaves usadas com o QnA Maker.

As etapas a seguir fornecem essa chave:

Select Cognitive Service

  1. No portal do Azure, selecione seu serviço cognitivo do QnA Maker.

    Select Cognitive Service Keys

  2. Selecione o ícone Chaves encontrado sob a seção Gerenciamento de Recursos, no menu à esquerda.

    Select Cognitive Service Key1

  3. Copie o valor da Chave 1 para a área de transferência e salve-a localmente. isso será usado posteriormente para o valor <de chave (-k) azure-qna-service-key1> ao adicionar o aplicativo QnA Maker ao seu aplicativo de expedição.

  4. Agora entre no portal da Web do QnA Maker.

  5. Na etapa 2, selecione o seguinte:

    • Sua conta do Azure AD.
    • Seu nome da assinatura do Azure.
    • O nome que você criou para seu serviço QnA Maker. (Se o seu serviço QnA do Azure não for exibido inicialmente nessa lista suspensa, tente atualizar a página).

    Create QnA Step 2

  6. Na etapa 3, forneça um nome para sua base de dados de conhecimento do QnA Maker. Para este exemplo, use o nome 'sample-qna'.

    Create QnA Step 3

  7. Na etapa 4, selecione a opção + Adicionar Arquivo, navegue até a pasta CognitiveModel do código de exemplo e selecione o arquivo 'QnAMaker.tsv'. Há uma seleção adicional para adicionar uma personalidade de Bate-papo à sua base de dados de conhecimento, mas nosso exemplo não inclui essa opção.

    Create QnA Step 4

  8. Na etapa 5, selecione Criar sua base de dados de conhecimento.

  9. Depois que a base de dados de conhecimento for criada com base no arquivo carregado, selecione Salvar e treinar e, quando terminar, selecione a guia PUBLICAR e publique o aplicativo.

  10. Depois que seu aplicativo do QnA Maker for publicado, selecione a guia CONFIGURAÇÕES e role para baixo até os “Detalhes da implantação”. Registre os seguintes valores da solicitação HTTP de exemplo, Carteiro.

    POST /knowledge bases/<knowledge-base-id>/generateAnswer
    Host: <your-hostname>  // NOTE - this is a URL.
    Authorization: EndpointKey <qna-maker-resource-key>
    

    A cadeia de caracteres de URL completa para seu nome de host será semelhante https://<host-id>.azure.net/qnamaker. Esses valores serão usados posteriormente no seu arquivo appsettings.json ou .env.

O aplicativo Dispatch precisa ter acesso de leitura aos aplicativos existentes

A ferramenta Dispatch precisa de acesso de criação para ler os aplicativos existentes do LUIS e do QnA Maker para criar um aplicativo do LUIS pai que expede para os aplicativos do LUIS e do QnA Maker. Esse acesso é fornecido as IDs do aplicativo e as chaves de criação.

Chaves de criação de serviço

A chave de criação é usada apenas para criar e editar os modelos. É necessário ter uma ID e uma chave para cada um dos dois aplicativos do LUIS e o aplicativo do QnA Maker.

  • para LUIS
    • A ID do aplicativo é encontrada no portal do LUIS para cada aplicativo, Gerenciar > Configurações > Aplicativo Configurações
    • A Chave de Criação é encontrada no portal do LUIS, no canto superior direito, selecione seu próprio Usuário e, em seguida, Configurações.
  • para o Qna Maker
    • A ID do aplicativo é encontrada no portal do QnA Maker na página Configurações após a publicação do aplicativo. Esta é a ID encontrada na primeira parte do comando POST após a base de dados de conhecimento. Um exemplo de onde encontrar a ID do aplicativo é POST /knowledgebases/<APP-ID>/generateAnswer.
    • A Chave de Criação é encontrada no portal do Azure, para o recurso do QnA Maker, nas Chaves. Você precisa apenas de uma das chaves.

A chave de criação não é usada para obter uma pontuação de previsão nem uma pontuação de confiança do aplicativo publicado. Você precisa das chaves do ponto de extremidade para esta ação. As chaves do ponto de extremidade são encontradas e usadas posteriormente neste tutorial.

Saiba mais sobre os dois tipos diferentes de chaves usadas com o QnA Maker.

Criar o modelo de expedição

A interface da CLI para a ferramenta Dispatch cria o modelo para expedição para o aplicativo correto do LUIS ou do QnA Maker.

  1. Abra um prompt de comando ou janela de terminal e alterne para o diretório CognitiveModels

  2. Verifique se você tem a versão atual do npm e a ferramenta Dispatch.

    npm i -g npm
    npm i -g botdispatch
    
  3. Use dispatch init para inicializar a criação de um arquivo .dispatch para seu modelo do Dispatch. Crie-o usando um nome de arquivo que você consiga reconhecer depois.

    dispatch init -n <filename-to-create> --luisAuthoringKey "<your-luis-authoring-key>" --luisAuthoringRegion <your-region>
    
  4. Use dispatch add para adicionar seus aplicativos do LUIS e bases de dados de conhecimento do QnA Maker ao arquivo .dispatch.

    dispatch add -t luis -i "<app-id-for-weather-app>" -n "<name-of-weather-app>" -v <app-version-number> -k "<your-luis-authoring-key>" --intentName l_Weather
    dispatch add -t luis -i "<app-id-for-home-automation-app>" -n "<name-of-home-automation-app>" -v <app-version-number> -k "<your-luis-authoring-key>" --intentName l_HomeAutomation
    dispatch add -t qna -i "<knowledge-base-id>" -n "<knowledge-base-name>" -k "<azure-qna-service-key1>" --intentName q_sample-qna
    
  5. Use dispatch create para gerar um modelo do Dispatch baseado no arquivo .dispatch.

    dispatch create
    
  6. Publique o aplicativo Dispatch do LUIS, que acaba de ser criado.

Usar o aplicativo Dispatch do LUIS

O aplicativo do LUIS gerado define as intenções para cada um dos aplicativos filho e bases de dados de conhecimento, bem como uma intenção none para quando o enunciado não tem uma opção adequada.

  • l_HomeAutomation
  • l_Weather
  • None
  • q_sample-qna

Esses serviços precisam ser publicados com os nomes corretos para que o bot seja executado corretamente. O bot precisa de informações sobre os serviços publicados para poder acessar esses serviços.

Chaves do ponto de extremidade de serviço

O bot precisa dos pontos de extremidade de previsão de consulta para os três aplicativos do LUIS (Dispatch, Clima e HomeAutomation) e única base de dados de conhecimento do QnA Maker. Localize as chaves de ponto de extremidade nos portais LUIS e QnA Maker:

  • No portal do LUIS, para cada aplicativo do LUIS, na seção Gerenciar, selecione Configurações de chaves e ponto de extremidade para localizar as chaves associadas a cada aplicativo. Se você estiver seguindo este tutorial, a chave do ponto de extremidade será a mesma chave que o <your-luis-authoring-key>. A chave de criação permite 1000 ocorrências de ponto de extremidade e, em seguida, expira.
  • No portal do QnA Maker, para a base de dados de conhecimento, em Gerenciar configurações, use o valor de chave mostrado nas configurações do Postman para o cabeçalho Autorização, sem o texto de EndpointKey.

Esses valores são usados no arquivo de configuração do exemplo: appsettings.json (C#), .env (JavaScript) ou config.py (Python).

Instalar Pacotes

Antes de executar esse aplicativo pela primeira vez, verifique se vários pacotes NuGet estão instalados:

  • Microsoft.Bot.Builder
  • Microsoft.Bot.Builder.AI.Luis
  • Microsoft.Bot.Builder.AI.QnA

Atualizar manualmente o arquivo appsettings.json

Depois que todos os aplicativos de serviço forem criados, as informações para cada um precisarão ser adicionadas ao arquivo “appsettings.json”.

Para cada uma das entidades mostradas abaixo, adicione os valores que você registrou anteriormente nas instruções:

appsettings.json

"QnAKnowledgebaseId": "<knowledge-base-id>",
"QnAEndpointKey": "<qna-maker-resource-key>",
"QnAEndpointHostName": "<your-hostname>",

"LuisAppId": "<app-id-for-dispatch-app>",
"LuisAPIKey": "<your-luis-endpoint-key>",
"LuisAPIHostName": "<your-dispatch-app-region>",

Quando todas as alterações tiverem sido concluídas, salve esse arquivo.

Conectar-se aos serviços do seu bot

Para se conectar aos serviços Dispatch, LUIS e QnA Maker, seu bot obtém informações do arquivo de configurações por pull.

Em BotServices.cs, use as informações de appsettings.json para conectar seu bot de expedição aos serviços e SampleQnA aos Dispatch serviços. Use os valores de configuração nos construtores para se conectar a esses serviços.

Observação

Por padrão, o includeApiResults parâmetro é definido como false, o que significa que o reconhecedor retornará apenas informações básicas sobre entidades e intenções. Se você precisar da resposta completa do LUIS (como o ConnectedServiceResult usado posteriormente neste tutorial), defina esse parâmetro como true. Isso adicionará a resposta completa do serviço LUIS à coleção de propriedades no RecognizerResult.

Chamar os serviços do seu bot

Para cada entrada do usuário, a lógica do bot verifica a entrada do usuário em relação ao modelo de Expedição combinado, localiza a intenção retornada superior e usa essas informações para chamar o serviço apropriado para a entrada.

No arquivo DispatchBot.cs, sempre que o método OnMessageActivityAsync é chamado, verificamos a mensagem da entrada do usuário com base no modelo do Dispatch. Em seguida, passamos o Modelo de topIntent Expedição e recognizerResult o método correto para chamar o serviço e retornar o resultado.

Trabalhar com os resultados de reconhecimento

Quando o modelo produz um resultado, ele indica qual serviço pode processar mais adequadamente a declaração. O código neste bot encaminha a solicitação para o serviço correspondente e, então, resume a resposta do serviço chamado. Dependendo da intenção retornada pelo Dispatch, esse código usa a intenção retornada para encaminhar para o modelo LUIS ou serviço QnA correto.

Se o método ou ProcessWeatherAsync o ProcessHomeAutomationAsync método for invocado, ele será passado os resultados do modelo de expedição em luisResult.ConnectedServiceResult. O método especificado fornece comentários do usuário mostrando a principal intenção do modelo de expedição, além de uma lista classificada de todas as intenções e entidades que foram detectadas.

Se o q_sample-qna método for invocado, ele usará a entrada do usuário contida no contexto de turno para gerar uma resposta do base de dados de conhecimento e exibir esse resultado para o usuário.

Observação

Se fosse um aplicativo de produção, aqui é onde os métodos LUIS selecionados se conectariam ao serviço especificado, transmitiriam a entrada do usuário e processariam a intenção do LUIS e os dados de entidade retornados.

Testar seu bot

  1. Usando o ambiente de desenvolvimento, inicie o código de exemplo. Observe o endereço localhost mostrado na barra de endereços da janela do navegador aberta pelo aplicativo: "https://localhost:<Port_Number>".

  2. Abra Bot Framework Emulator e selecione Create a new bot configuration. Um .bot arquivo permite que você use o Inspetor no Emulator para ver o JSON retornado do LUIS e do QnA Maker.

  3. Na caixa de diálogo Nova configuração de bot, digite o nome do bot e a URL do ponto de extremidade, como http://localhost:3978/api/messages. Salve o arquivo na raiz de seu projeto de código de amostra do bot.

  4. Abra o arquivo de bot e adicione seções para seus aplicativos do LUIS e do QnA Maker. Use este arquivo de exemplo como modelo para as configurações. Salve as alterações.

  5. Selecione o nome do bot na lista Meus Bots para acessar o bot em execução. Para sua referência, aqui estão algumas das perguntas e dos comandos cobertos pelos serviços criados para o bot:

    • QnA Maker
      • hi, good morning
      • what are you, what do you do
    • LUIS (automação doméstica)
      • turn on bedroom light
      • turn off bedroom light
      • make some coffee
    • LUIS (clima)
      • whats the weather in redmond washington
      • what's the forecast for london
      • show me the forecast for nebraska

Expedição do enunciado do usuário para o QnA Maker

  1. No Bot Framework Emulator, insira o texto hi e envie o enunciado. O bot envia essa consulta para o aplicativo Dispatch do LUIS e recebe uma resposta que indica qual aplicativo filho deve receber esse enunciado para processamento adicional.

  2. Ao selecionar a LUIS Trace linha no log, você pode ver a resposta luis no Emulator . O resultado no LUIS do aplicativo Dispatch do LUIS é exibido no Inspetor.

    {
      "luisResponse": {
        "entities": [],
        "intents": [
          {
            "intent": "q_sample-qna",
            "score": 0.9489713
          },
          {
            "intent": "l_HomeAutomation",
            "score": 0.0612499453
          },
          {
            "intent": "None",
            "score": 0.008567564
          },
          {
            "intent": "l_Weather",
            "score": 0.0025761195
          }
        ],
        "query": "Hi",
        "topScoringIntent": {
          "intent": "q_sample-qna",
          "score": 0.9489713
        }
      }
    }
    

    Como o enunciado, hi, faz parte da intenção q_sample-qna do aplicativo Dispatch do LUIS e é selecionado como o topScoringIntent, o bot fará uma segunda solicitação, desta vez para o aplicativo do QnA Maker, com o mesmo enunciado.

  3. Selecione a QnAMaker Trace linha no log Emulator. O resultado do QnA Maker é exibido no Inspetor.

{
    "questions": [
        "hi",
        "greetings",
        "good morning",
        "good evening"
    ],
    "answer": "Hello!",
    "score": 1,
    "id": 96,
    "source": "QnAMaker.tsv",
    "metadata": [],
    "context": {
        "isContextOnly": false,
        "prompts": []
    }
}

Resolvendo intenção incorreta no Dispatch

Depois que seu bot estiver em execução, é possível melhorar o desempenho do bot removendo declarações semelhantes ou sobrepostas entre os aplicativos expedidos. Você pode usar a ferramenta de linha de comando Dispatch para testar e avaliar seu modelo de expedição.

Para atualizar ou criar um novo modelo do LUIS

Este exemplo é baseado em um modelo predefinido do LUIS. Informações adicionais para ajudá-lo a atualizar esse modelo ou criar um novo modelo LUIS podem ser encontradas no design do aplicativo Iterativo do artigo para LUIS.

Depois de atualizar os modelos subjacentes (QnA ou LUIS), execute dispatch refresh para atualizar seu aplicativo de Expedição do LUIS. dispatch refresh é basicamente o mesmo comando que dispatch create, exceto pelo fato de que nenhuma nova ID do aplicativo do LUIS é criada.

Observe que os enunciados que foram adicionados diretamente no LUIS não serão mantidos ao executar dispatch refresh. Para manter esses enunciados extras no aplicativo de expedição, adicione-os em um arquivo de texto (um enunciado por linha) e, em seguida, adicione o arquivo à Expedição executando o comando:

dispatch add -t file -f <file path> --intentName <target intent name, ie l_General>

Quando o arquivo com enunciados extras for adicionado à Expedição, os enunciados permanecerão após cada atualização.

Para excluir recursos

Este exemplo cria vários aplicativos e recursos que você pode excluir usando as etapas listadas abaixo, mas você não deve excluir os recursos dos quais outros aplicativos ou serviços dependam.

Para excluir recursos do LUIS:

  1. Entre no portal luis.ai.
  2. Acesse a página Meus Aplicativos.
  3. Selecione os aplicativos criados por este exemplo.
    • Home Automation
    • Weather
    • NLP-With-Dispatch-BotDispatch
  4. Clique em Excluir e clique em OK para confirmar.

Para excluir recursos do QnA Maker:

  1. Entre no portal qnamaker.ai.
  2. Acesse a página My knowledge bases (Minhas bases de conhecimento).
  3. Clique no botão de exclusão da base de conhecimento Sample QnA e clique em Delete (Excluir) para confirmar.

Melhor prática

Para melhorar os serviços usados neste exemplo, confira a prática recomendada para LUIS e QnA Maker.