Use o aprendizado ativo para melhorar sua base de dados de conhecimentoUse active learning to improve your knowledge base

O aprendizado ativo permite melhorar a qualidade da sua base de dados de Conhecimento, sugerindo perguntas alternativas, com base em envios de usuário, para o par de pergunta e resposta.Active learning allows you to improve the quality of your knowledge base by suggesting alternative questions, based on user-submissions, to your question and answer pair. Você examina essas sugestões, adicionando-as às perguntas existentes ou rejeitando-as.You review those suggestions, either adding them to existing questions or rejecting them.

Sua base de dados de conhecimento não é alterada automaticamente.Your knowledge base doesn't change automatically. Para que qualquer alteração entre em vigor, você deve aceitar as sugestões.In order for any change to take effect, you must accept the suggestions. Essas sugestões adicionam perguntas, mas não alteram nem removem perguntas existentes.These suggestions add questions but don't change or remove existing questions.

O que é o aprendizado ativo?What is active learning?

O QnA Maker aprende novas variações de pergunta com comentários implícitos e explícitos.QnA Maker learns new question variations with implicit and explicit feedback.

  • Comentários implícitos – o classificador entende quando uma pergunta de usuário tem várias respostas com pontuações que são muito próximas e considera isso como comentários.Implicit feedback – The ranker understands when a user question has multiple answers with scores that are very close and considers this as feedback. Você não precisa fazer nada para que isso aconteça.You don't need to do anything for this to happen.
  • Comentários explícitos – quando várias respostas com pouca variação nas pontuações são retornadas da base de dados de conhecimento, o aplicativo cliente pergunta ao usuário qual pergunta é a pergunta correta.Explicit feedback – When multiple answers with little variation in scores are returned from the knowledge base, the client application asks the user which question is the correct question. Os comentários explícitos do usuário são enviados para QnA Maker com a API de treinamento.The user's explicit feedback is sent to QnA Maker with the Train API.

Ambos os métodos fornecem o classificador com consultas semelhantes que são clusterizadas.Both methods provide the ranker with similar queries that are clustered.

Como o aprendizado ativo funcionaHow active learning works

O aprendizado ativo é disparado com base nas pontuações das primeiras respostas retornadas pelo QnA Maker.Active learning is triggered based on the scores of the top few answers returned by QnA Maker. Se as diferenças de Pontuação estiverem dentro de um intervalo pequeno, a consulta será considerada uma possível sugestão (como uma pergunta alternativa) para cada um dos possíveis pares de QnA.If the score differences lie within a small range, then the query is considered a possible suggestion (as an alternate question) for each of the possible QnA pairs. Depois de aceitar a pergunta sugerida para um par QnA específico, ele será rejeitado para os outros pares.Once you accept the suggested question for a specific QnA pair, it is rejected for the other pairs. Você precisa se lembrar de salvar e treinar, depois de aceitar sugestões.You need to remember to save and train, after accepting suggestions.

O aprendizado ativo fornece as melhores sugestões possíveis em casos em que os pontos de extremidade estão obtendo uma quantidade e variedade razoáveis de consultas de uso.Active learning gives the best possible suggestions in cases where the endpoints are getting a reasonable quantity and variety of usage queries. Quando 5 ou mais consultas semelhantes são clusterizadas, a cada 30 minutos, QnA Maker sugere as perguntas baseadas no usuário para que o designer da base de dados de conhecimento aceite ou rejeite.When 5 or more similar queries are clustered, every 30 minutes, QnA Maker suggests the user-based questions to the knowledge base designer to accept or reject. Todas as sugestões são clusterizadas por similaridade e as principais sugestões de perguntas alternativas são exibidas com base na frequência das consultas específicas por usuários finais.All the suggestions are clustered together by similarity and top suggestions for alternate questions are displayed based on the frequency of the particular queries by end users.

Quando as perguntas são sugeridas no portal de QnA Maker, você precisa revisar e aceitar ou rejeitar essas sugestões.Once questions are suggested in the QnA Maker portal, you need to review and accept or reject those suggestions. Não há uma API para gerenciar sugestões.There isn't an API to manage suggestions.

Como o comentário implícito do QnA Maker funcionaHow QnA Maker's implicit feedback works

Os comentários implícitos do QnA Maker usam um algoritmo para determinar a proximidade da pontuação e, em seguida, fazer sugestões de aprendizado ativo.QnA Maker's implicit feedback uses an algorithm to determine score proximity then make active learning suggestions. O algoritmo para determinar a proximidade não é um cálculo simples.The algorithm to determine proximity is not a simple calculation. Os intervalos no exemplo a seguir não devem ser corrigidos, mas devem ser usados como um guia para entender o impacto apenas do algoritmo.The ranges in the following example are not meant to be fixed but should be used as a guide to understand the impact of the algorithm only.

Quando a pontuação de uma pergunta tem um alto grau de confiabilidade, tal como 80%, o intervalo de pontuações que são consideradas para aprendizado ativo é amplo, dentro de aproximadamente 10%.When a question's score is highly confident, such as 80%, the range of scores that are considered for active learning are wide, approximately within 10%. Conforme a pontuação de confiança diminui, por exemplo, para 40%, o intervalo de pontuações diminui também, para dentro de aproximadamente 4%.As the confidence score decreases, such as 40%, the range of scores decreases as well, approximately within 4%.

Como você dá comentários explícitos com a API de treinamentoHow you give explicit feedback with the Train API

É importante que QnA Maker obtenha comentários explícitos sobre quais das respostas foi a melhor resposta.It is important that QnA Maker gets explicit feedback about which of the answers was the best answer. Como a melhor resposta é determinada, você pode incluir:How the best answer is determined is up to you and can include:

  • Comentários do usuário, selecionando uma das respostas.User feedback, selecting one of the answers.
  • Lógica de negócios, como determinar um intervalo de Pontuação aceitável.Business logic, such as determining an acceptable score range.
  • Uma combinação dos comentários do usuário e da lógica de negócios.A combination of both user feedback and business logic.

Atualizar sua versão de tempo de execução para usar o aprendizado ativoUpgrade your runtime version to use active learning

O aprendizado ativo é compatível com a versão de tempo de execução 4.4.0 e superior.Active Learning is supported in runtime version 4.4.0 and above. Se sua base de dados de conhecimento foi criada em uma versão anterior, atualize seu tempo de execução para usar esse recurso.If your knowledge base was created on an earlier version, upgrade your runtime to use this feature.

Ativar o aprendizado ativo para ver sugestõesTurn on active learning to see suggestions

O aprendizado ativo está desativado por padrão.Active learning is off by default. Ative-o para ver sugestões de perguntas.Turn it on to see suggested questions. Depois de ativar o aprendizado ativo, você precisa enviar informações do aplicativo cliente para QnA Maker.After you turn on active learning, you need to send information from the client app to QnA Maker. Para obter mais informações, consulte o fluxo arquitetônico para usar GenerateAnswer e treinar APIs de um bot.For more information, see Architectural flow for using GenerateAnswer and Train APIs from a bot.

  1. Selecione publicar para publicar a base de dados de conhecimento.Select Publish to publish the knowledge base. Consultas de aprendizado ativo são coletadas somente do ponto de extremidade de previsão da API GenerateAnswer.Active learning queries are collected from the GenerateAnswer API prediction endpoint only. As consultas ao painel de teste no portal de QnA Maker não afetam o aprendizado ativo.The queries to the Test pane in the QnA Maker portal do not impact active learning.

  2. Para ativar o aprendizado ativo no portal de QnA Maker, vá para o canto superior direito, selecione seu nome, vá para configurações de serviço.To turn active learning on in the QnA Maker portal, go to the top-right corner, select your Name, go to Service Settings.

    Ative as alternativas de perguntas sugeridas do aprendizado ativo na página Configurações de serviço.

  3. Localize o serviço QnA Maker e, em seguida, ative o aprendizado ativo.Find the QnA Maker service then toggle Active Learning.

    na página Configurações de serviço, alterne o recurso de aprendizado ativo. Se não for possível alternar o recurso, talvez seja necessário atualizar seu serviço.On the Service settings page, toggle on Active Learning feature. If you are not able to toggle the feature, you may need to upgrade your service.

    Observação

    A versão exata na imagem anterior é mostrada apenas como um exemplo.The exact version on the preceding image is shown as an example only. Sua versão pode ser diferente.Your version may be different.

    Quando o aprendizado ativo é habilitado, a base de dados de conhecimento sugere novas perguntas em intervalos regulares com base em perguntas enviadas pelo usuário.Once Active Learning is enabled, the knowledge base suggests new questions at regular intervals based on user-submitted questions. Você pode desabilitar o aprendizado ativo desativando a configuração novamente.You can disable Active Learning by toggling the setting again.

Aceitar uma sugestão de aprendizado ativo na base de dados de conhecimentoAccept an active learning suggestion in the knowledge base

O aprendizado ativo altera a base de dados de conhecimento ou Serviço de Pesquisa depois que você aprova a sugestão, em seguida, salva e treina.Active Learning alters the Knowledge Base or Search Service after you approve the suggestion, then save and train. Se você aprovar a sugestão, ela será adicionada como uma pergunta alternativa.If you approve the suggestion it will be added as an alternate question.

  1. Para ver as perguntas sugeridas, na página Editar base de dados de conhecimento, selecione Opções de exibiçãoe, em seguida, selecione Mostrar sugestões de aprendizado ativo.In order to see the suggested questions, on the Edit knowledge base page, select View Options, then select Show active learning suggestions.

    na seção editar do portal, selecione Mostrar sugestões para ver as novas alternativas de pergunta do aprendizado ativo.On the Edit section of the portal, select Show Suggestions in order to see the active learning's new question alternatives.

  2. Filtre a base de dados de conhecimento com pares de perguntas e respostas para mostrar apenas sugestões selecionando Filtrar por sugestões.Filter the knowledge base with question and answer pairs to show only suggestions by selecting Filter by Suggestions.

    use a alternância filtrar por sugestões para exibir apenas as alternativas de perguntas sugeridas do aprendizado ativo.Use the Filter by suggestions toggle to view only the active learning's suggested question alternatives.

  3. Cada par de QnA sugere a nova pergunta alternativas com uma marca de seleção, , para aceitar a pergunta ou uma x para rejeitar as sugestões.Each QnA pair suggests the new question alternatives with a check mark, , to accept the question or an x to reject the suggestions. Selecione a marca de seleção para adicionar a pergunta.Select the check mark to add the question.

    selecionar ou rejeitar as alternativas de pergunta sugeridas do aprendizado ativo, selecionando a marca de seleção verde ou de exclusão vermelha.Select or reject active learning's suggested question alternatives by selecting the green check mark or red delete mark.

    Você pode adicionar ou excluir todas as sugestões selecionando Adicionar tudo ou rejeitar tudo na barra de ferramentas contextual.You can add or delete all suggestions by selecting Add all or Reject all in the contextual toolbar.

  4. Selecione Salvar e Treinar para salvar as alterações à base de dados de conhecimento.Select Save and Train to save the changes to the knowledge base.

  5. Selecione publicar para permitir que as alterações estejam disponíveis na API GenerateAnswer.Select Publish to allow the changes to be available from the GenerateAnswer API.

    Quando 5 ou mais consultas semelhantes são clusterizadas, a cada 30 minutos, QnA Maker sugere as perguntas alternativas para que você aceite ou rejeite.When 5 or more similar queries are clustered, every 30 minutes, QnA Maker suggests the alternate questions for you to accept or reject.

Fluxo de arquitetura para usar GenerateAnswer e treinar APIs de um botArchitectural flow for using GenerateAnswer and Train APIs from a bot

Um bot ou outro aplicativo cliente deve usar o seguinte fluxo de arquitetura para usar o aprendizado ativo:A bot or other client application should use the following architectural flow to use active learning:

Use a propriedade Top na solicitação GenerateAnswer para obter várias respostas correspondentesUse the top property in the GenerateAnswer request to get several matching answers

Ao enviar uma pergunta para QnA Maker para uma resposta, a propriedade top do corpo JSON define o número de respostas a serem retornadas.When submitting a question to QnA Maker for an answer, the top property of the JSON body sets the number of answers to return.

{
    "question": "wi-fi",
    "isTest": false,
    "top": 3
}

Use a propriedade Score junto com a lógica de negócios para obter a lista de respostas para mostrar o usuárioUse the score property along with business logic to get list of answers to show user

Quando o aplicativo cliente (como um bot de chat) recebe a resposta, as três principais perguntas são retornadas.When the client application (such as a chat bot) receives the response, the top 3 questions are returned. Use a propriedade score para analisar a proximidade entre as pontuações.Use the score property to analyze the proximity between scores. Esse intervalo de proximidade é determinado pela sua própria lógica de negócios.This proximity range is determined by your own business logic.

{
    "answers": [
        {
            "questions": [
                "Wi-Fi Direct Status Indicator"
            ],
            "answer": "**Wi-Fi Direct Status Indicator**\n\nStatus bar icons indicate your current Wi-Fi Direct connection status:  \n\nWhen your device is connected to another device using Wi-Fi Direct, '$  \n\n+ •+ ' Wi-Fi Direct is displayed in the Status bar.",
            "score": 74.21,
            "id": 607,
            "source": "Bugbash KB.pdf",
            "metadata": []
        },
        {
            "questions": [
                "Wi-Fi - Connections"
            ],
            "answer": "**Wi-Fi**\n\nWi-Fi is a term used for certain types of Wireless Local Area Networks (WLAN). Wi-Fi communication requires access to a wireless Access Point (AP).",
            "score": 74.15,
            "id": 599,
            "source": "Bugbash KB.pdf",
            "metadata": []
        },
        {
            "questions": [
                "Turn Wi-Fi On or Off"
            ],
            "answer": "**Turn Wi-Fi On or Off**\n\nTurning Wi-Fi on makes your device able to discover and connect to compatible in-range wireless APs.  \n\n1.  From a Home screen, tap ::: Apps > e Settings .\n2.  Tap Connections > Wi-Fi , and then tap On/Off to turn Wi-Fi on or off.",
            "score": 69.99,
            "id": 600,
            "source": "Bugbash KB.pdf",
            "metadata": []
        }
    ]
}

Acompanhamento do aplicativo cliente quando perguntas têm pontuações semelhantesClient application follow-up when questions have similar scores

O aplicativo cliente exibe as perguntas com uma opção para que o usuário selecione a única pergunta que mais representa sua intenção.Your client application displays the questions with an option for the user to select the single question that most represents their intention.

Depois que o usuário seleciona uma das perguntas existentes, o aplicativo cliente envia a opção do usuário como comentários usando a API de treinamento do QnA Maker.Once the user selects one of the existing questions, the client application sends the user's choice as feedback using QnA Maker's Train API. Este comentário conclui o loop de comentários do aprendizado ativo.This feedback completes the active learning feedback loop.

API de treinamentoTrain API

Os comentários do aprendizado ativo são enviados para QnA Maker com a solicitação Train API POST.Active learning feedback is sent to QnA Maker with the Train API POST request. A assinatura de API é:The API signature is:

POST https://<QnA-Maker-resource-name>.azurewebsites.net/qnamaker/knowledgebases/<knowledge-base-ID>/train
Authorization: EndpointKey <endpoint-key>
Content-Type: application/json
{"feedbackRecords": [{"userId": "1","userQuestion": "<question-text>","qnaId": 1}]}
Propriedade de solicitação HTTPHTTP request property NomeName TipoType FinalidadePurpose
Parâmetro de rota de URLURL route parameter ID da base de dados de conhecimentoKnowledge base ID stringstring o GUID da base de dados de conhecimento.The GUID for your knowledge base.
Subdomínio personalizadoCustom subdomain Nome do recurso QnAMakerQnAMaker resource name stringstring O nome do recurso é usado como o subdomínio personalizado para seu QnA Maker.The resource name is used as the custom subdomain for your QnA Maker. Isso estará disponível na página configurações depois que você publicar a base de dados de conhecimento.This is available on the Settings page after you publish the knowledge base. Ele é listado como o host.It is listed as the host.
CabeçalhoHeader Tipo de conteúdoContent-Type stringstring o tipo de mídia do corpo enviado para a API.The media type of the body sent to the API. O valor padrão é: application/jsonDefault value is: application/json
CabeçalhoHeader AutorizaçãoAuthorization stringstring sua chave de ponto de extremidade (EndpointKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).Your endpoint key (EndpointKey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Corpo da postagemPost Body Objeto JSONJSON object JSONJSON Os comentários de treinamentoThe training feedback

O corpo JSON tem várias configurações:The JSON body has several settings:

Propriedade de corpo JSONJSON body property TipoType FinalidadePurpose
feedbackRecords arrayarray Lista de comentários.List of feedback.
userId stringstring A ID de usuário da pessoa que está aceitando as perguntas sugeridas.The user ID of the person accepting the suggested questions. O formato da ID de usuário cabe a você.The user ID format is up to you. Por exemplo, um endereço de email pode ser uma ID de usuário válida em sua arquitetura.For example, an email address can be a valid user ID in your architecture. Opcional.Optional.
userQuestion stringstring Texto exato da consulta do usuário.Exact text of the user's query. Obrigatório.Required.
qnaID númeronumber ID de pergunta, encontrada na resposta de GenerateAnswer.ID of question, found in the GenerateAnswer response.

Um exemplo de corpo JSON é semelhante a:An example JSON body looks like:

{
    "feedbackRecords": [
        {
            "userId": "1",
            "userQuestion": "<question-text>",
            "qnaId": 1
        }
    ]
}

Uma resposta bem-sucedida retorna um status de 204 e nenhum corpo de resposta JSON.A successful response returns a status of 204 and no JSON response body.

Lote de muitos registros de comentários em uma única chamadaBatch many feedback records into a single call

No aplicativo do lado do cliente, como um bot, você pode armazenar os dados e, em seguida, enviar vários registros em um único corpo JSON na matriz de feedbackRecords.In the client-side application, such as a bot, you can store the data, then send many records in a single JSON body in the feedbackRecords array.

Um exemplo de corpo JSON é semelhante a:An example JSON body looks like:

{
    "feedbackRecords": [
        {
            "userId": "1",
            "userQuestion": "How do I ...",
            "qnaId": 1
        },
        {
            "userId": "2",
            "userQuestion": "Where is ...",
            "qnaId": 40
        },
        {
            "userId": "3",
            "userQuestion": "When do I ...",
            "qnaId": 33
        }
    ]
}

Código de exemplo do bot FrameworkBot framework sample code

O código do bot Framework precisa chamar a API de treinamento se a consulta do usuário deve ser usada para o aprendizado ativo.Your bot framework code needs to call the Train API, if the user's query should be used for active learning. Há duas partes de código para escrever:There are two pieces of code to write:

  • Determinar se a consulta deve ser usada para o aprendizado ativoDetermine if query should be used for active learning
  • Enviar consulta de volta para a API de treinamento do QnA Maker para aprendizagem ativaSend query back to QnA Maker's Train API for active learning

No exemplo de bot do Azure, ambas as atividades foram programadas.In the Azure Bot sample, both of these activities have been programmed.

Código C# de exemplo para a API de treinamento com o bot Framework 4. xExample C# code for Train API with Bot Framework 4.x

O código a seguir ilustra como enviar informações de volta para QnA Maker com a API de treinamento.The following code illustrates how to send information back to QnA Maker with the Train API. Este exemplo de código completo está disponível no github.This complete code sample is available on GitHub.

public class FeedbackRecords
{
    // <summary>
    /// List of feedback records
    /// </summary>
    [JsonProperty("feedbackRecords")]
    public FeedbackRecord[] Records { get; set; }
}

/// <summary>
/// Active learning feedback record
/// </summary>
public class FeedbackRecord
{
    /// <summary>
    /// User id
    /// </summary>
    public string UserId { get; set; }

    /// <summary>
    /// User question
    /// </summary>
    public string UserQuestion { get; set; }

    /// <summary>
    /// QnA Id
    /// </summary>
    public int QnaId { get; set; }
}

/// <summary>
/// Method to call REST-based QnAMaker Train API for Active Learning
/// </summary>
/// <param name="endpoint">Endpoint URI of the runtime</param>
/// <param name="FeedbackRecords">Feedback records train API</param>
/// <param name="kbId">Knowledgebase Id</param>
/// <param name="key">Endpoint key</param>
/// <param name="cancellationToken"> Cancellation token</param>
public async static void CallTrain(string endpoint, FeedbackRecords feedbackRecords, string kbId, string key, CancellationToken cancellationToken)
{
    var uri = endpoint + "/knowledgebases/" + kbId + "/train/";

    using (var client = new HttpClient())
    {
        using (var request = new HttpRequestMessage())
        {
            request.Method = HttpMethod.Post;
            request.RequestUri = new Uri(uri);
            request.Content = new StringContent(JsonConvert.SerializeObject(feedbackRecords), Encoding.UTF8, "application/json");
            request.Headers.Add("Authorization", "EndpointKey " + key);

            var response = await client.SendAsync(request, cancellationToken);
            await response.Content.ReadAsStringAsync();
        }
    }
}

Código do node. js de exemplo para a API de treinamento com o bot Framework 4. xExample Node.js code for Train API with Bot Framework 4.x

O código a seguir ilustra como enviar informações de volta para QnA Maker com a API de treinamento.The following code illustrates how to send information back to QnA Maker with the Train API. Este exemplo de código completo está disponível no github.This complete code sample is available on GitHub.

async callTrain(stepContext){

    var trainResponses = stepContext.values[this.qnaData];
    var currentQuery = stepContext.values[this.currentQuery];

    if(trainResponses.length > 1){
        var reply = stepContext.context.activity.text;
        var qnaResults = trainResponses.filter(r => r.questions[0] == reply);

        if(qnaResults.length > 0){

            stepContext.values[this.qnaData] = qnaResults;

            var feedbackRecords = {
                FeedbackRecords:[
                    {
                        UserId:stepContext.context.activity.id,
                        UserQuestion: currentQuery,
                        QnaId: qnaResults[0].id
                    }
                ]
            };

            // Call Active Learning Train API
            this.activeLearningHelper.callTrain(this.qnaMaker.endpoint.host, feedbackRecords, this.qnaMaker.endpoint.knowledgeBaseId, this.qnaMaker.endpoint.endpointKey);
            
            return await stepContext.next(qnaResults);
        }
        else{

            return await stepContext.endDialog();
        }
    }

    return await stepContext.next(stepContext.result);
}

O aprendizado ativo é salvo na base de dados de conhecimento exportadaActive learning is saved in the exported knowledge base

Quando seu aplicativo tiver o aprendizado ativo habilitado e você exportar o aplicativo, a coluna SuggestedQuestions no arquivo TSV manterá os dados de aprendizado ativos.When your app has active learning enabled, and you export the app, the SuggestedQuestions column in the tsv file retains the active learning data.

A coluna SuggestedQuestions é um objeto JSON de informações de comentários implícitos, autosuggestede explícitos usersuggested.The SuggestedQuestions column is a JSON object of information of implicit, autosuggested, and explicit, usersuggested feedback. Um exemplo desse objeto JSON para uma única pergunta de help enviada pelo usuário é:An example of this JSON object for a single user-submitted question of help is:

[
    {
        "clusterHead": "help",
        "totalAutoSuggestedCount": 1,
        "totalUserSuggestedCount": 0,
        "alternateQuestionList": [
            {
                "question": "help",
                "autoSuggestedCount": 1,
                "userSuggestedCount": 0
            }
        ]
    }
]

Você também pode usar a API de alterações de download para examinar essas alterações, usando REST ou qualquer um dos SDKs baseados em linguagem:You can also use the download alterations API to review these alterations, using REST or any of the language-based SDKs:

Quando você Reimporta esse aplicativo, o aprendizado ativo continua a coletar informações e recomendar sugestões para sua base de dados de conhecimento.When you reimport this app, the active learning continues to collect information and recommend suggestions for your knowledge base.

Práticas recomendadasBest practices

Para as práticas recomendadas ao usar o aprendizado ativo, veja Práticas recomendadas.For best practices when using active learning, see Best practices.

Próximas etapasNext steps