Conectores de conhecimento

Beta

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Os conectores de conhecimento complementam as intents definidas. Eles analisam documentos de conhecimento, como perguntas frequentes ou artigos, para localizar respostas automatizadas. Para configurá-los, defina uma ou mais bases de conhecimento, que são conjuntos de documentos de conhecimento.

É possível ativar as bases de conhecimento no seu agente para que todas as solicitações de detecção de intent possam localizar as respostas automatizadas usando essas bases. Como alternativa, é possível especificar uma ou mais bases de conhecimento em suas solicitações de intent de detecção individuais.

Um agente que usa conectores de conhecimento também costuma usar intents definidas. Os conectores de conhecimento oferecem menos precisão e controle de resposta do que as intents. Defina suas intents para processar solicitações complexas de usuários e permitir que conectores de conhecimento processem solicitações simples.

Para ver uma lista de idiomas com suporte, consulte a coluna Conectores de conhecimento na referência de linguagens.

Limitações

O recurso de conectores de conhecimento está disponível apenas para a região global.

Ativar recursos Beta

Verifique se os recursos Beta estão ativados:

1. Acesse o Console do Dialogflow ES.
2. Selecione um agente.
3. Clique no botão de configurações ao lado do nome do agente.
4. Na guia General, role a tela para baixo e verifique se Beta Features está ativado.
5. Se você tiver feito alterações, clique em Save.

Criar uma base de conhecimento e um documento

Siga as instruções nas instruções de base de conhecimento para criar uma base de conhecimento e um documento.

Configurações dos conectores de conhecimento

Cuidado: no momento, as configurações do conector de conhecimento não são incluídas durante a exportação, importação ou restauração de agentes.

É possível ativar ou desativar as bases de conhecimento para seu agente. As bases de conhecimento ativadas serão consideradas para todas as solicitações de correspondência de intents que não especificam bases de conhecimento. Para ativar ou desativar bases de conhecimento:

1. Acesse o Console do Dialogflow ES.
2. Selecione um agente.
3. Clique em Knowledge no menu da barra lateral esquerda.
4. Selecione uma ou mais bases de conhecimento na lista.
5. Clique em Enable ou Disable.

Quando uma expressão de usuário final também corresponde a uma intent, é possível especificar o nível de preferência dos resultados de conhecimento:

1. Desça até a seção Adjust Knowledge Results Preference.
2. Ajuste o controle deslizante de mais fraco (preferência dada à intent) para mais forte (preferência dada ao conhecimento). Para mais informações, consulte Detectar respostas de intent abaixo.

Configurar respostas

Por padrão, uma base de conhecimento é configurada com uma única resposta de texto padrão preenchida com a melhor resposta de conhecimento correspondente. É possível alterar essa resposta e adicionar mensagens de resposta ricas. As respostas de conhecimento podem conter até três respostas por base de conhecimento, e é possível referenciá-las nas suas respostas configuradas. Para adicionar respostas:

1. Na página Knowledge, clique no nome da base de conhecimento.
2. Role para baixo até a seção Responses (Respostas) e adicione as respostas como você quiser:
   1. Ao definir a primeira resposta, use $Knowledge.Question[1] e $Knowledge.Answer[1] onde você quer que a pergunta e a resposta sejam fornecidas.
   2. O índice de $Knowledge.Question e $Knowledge.Answer começa em 1, por isso, aumente esse índice ao adicionar mais respostas.
3. Clique em Save quando terminar de editar.

Ao definir as respostas, considere os seguintes pontos:

• Se o número de respostas definidas for maior que N correspondências de respostas do conector de conhecimento, somente N respostas serão retornadas.
• Como a precisão pode ser menor que a correspondência de intents explicitamente definidas, recomendamos retornar três respostas aos usuários quando possível.

Cuidado: o comportamento atual ao definir múltiplas variantes de resposta é um problema conhecido. Depois de corrigido, o comportamento será o seguinte:

• Se houver múltiplas variantes de resposta definidas em uma única caixa de Resposta de texto ou de Resposta simples do Google Assistente, o Dialogflow escolherá uma aleatoriamente.
• Se houver várias caixas definidas de resposta avançada, o Dialogflow escolherá uma variante de resposta de cada caixa.

Exemplo:

Detectar intent com base de conhecimento

Ao fazer uma solicitação de detecção de intent, é possível especificar uma ou mais bases de conhecimento para uma possível resposta. O fornecimento explícito de bases de conhecimento em uma solicitação modifica as configurações de bases de conhecimento ativados e desativados.

Os exemplos abaixo mostram como usar o Console do Dialogflow, a API REST (incluindo a linha de comando) ou bibliotecas de clientes para detectar uma intent. Para usar a API, chame o método detectIntent no tipo Sessions.

IU da Web

É possível interagir com o agente e receber as respostas do conector de conhecimento por meio do simulador do Dialogflow:

1. Siga as etapas acima para ativar uma base de conhecimento.
2. Siga as etapas acima para definir respostas.
3. Digite "Como me inscrevo?" no simulador.

REST

Chame o método detectIntent no tipo Sessions e especifique a base de conhecimento no campo queryParams.

Antes de usar os dados da solicitação, faça as substituições a seguir:

• PROJECT_ID: ID do projeto do GCP
• KNOWLEDGE_BASE_ID: código da base de conhecimento

Método HTTP e URL:

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent

Corpo JSON da solicitação:

{
 "queryInput": {
   "text": {
     "text": "How do I sign up?",
     "languageCode": "en-US"
   }
 },
 "queryParams": {
   "knowledgeBaseNames": ["projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"]
 }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent"

PowerShell (Windows)

Observação: O comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent" | Select-Object -Expand Content

APIs Explorer (navegador)

Copie o corpo da solicitação e abra a página de referência do método. O painel "APIs Explorer" é aberto no lado direito da página. Interaja com essa ferramenta para enviar solicitações. Cole o corpo da solicitação nessa ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Você receberá uma resposta JSON semelhante a esta:

{
  ...
  "queryResult": {
    "queryText": "How do I sign up?",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
    "intent": {
      "name": "projects/my-gcp-project/agent/intents/487c7242-a769-408a-a339-47b95e10dac4",
      "displayName": "Knowledge.KnowledgeBase.MzkzNTAyMDE3NDQxNDk3MDg4MA"
    },
    "intentDetectionConfidence": 0.99371547,
    "languageCode": "en-us",
    "knowledgeAnswers": {
      "answers": [
        {
          "answer": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
          "matchConfidenceLevel": "HIGH",
          "matchConfidence": 0.99371547
        },
        {
          "answer": "Certain types of content are not allowed on this service; please refer to the Terms of Services and Platform Policies for details. If you believe a piece of content is in violation of our policies, report it here (select See more products, then Google Cloud Storage and Cloud Bigtable).",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0012244871
        },
        {
          "answer": "From the Cloud Storage documentation click \"Send feedback\" near the top right of the page. This will open a feedback form. Your comments will be reviewed by the Cloud Storage team.",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0011537358
        }
      ]
    }
  }
}

Java

Para autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.v2beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers.Answer;
import com.google.cloud.dialogflow.v2beta1.QueryInput;
import com.google.cloud.dialogflow.v2beta1.QueryParameters;
import com.google.cloud.dialogflow.v2beta1.QueryResult;
import com.google.cloud.dialogflow.v2beta1.SessionName;
import com.google.cloud.dialogflow.v2beta1.SessionsClient;
import com.google.cloud.dialogflow.v2beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntentKnowledge {

  // DialogFlow API Detect Intent sample with querying knowledge connector.
  public static Map<String, KnowledgeAnswers> detectIntentKnowledge(
      String projectId,
      String knowledgeBaseName,
      String sessionId,
      String languageCode,
      List<String> texts)
      throws IOException, ApiException {
    // Instantiates a client
    Map<String, KnowledgeAnswers> allKnowledgeAnswers = Maps.newHashMap();
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);
        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

        QueryParameters queryParameters =
            QueryParameters.newBuilder().addKnowledgeBaseNames(knowledgeBaseName).build();

        DetectIntentRequest detectIntentRequest =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .setQueryParams(queryParameters)
                .build();
        // Performs the detect intent request
        DetectIntentResponse response = sessionsClient.detectIntent(detectIntentRequest);

        // Display the query result
        QueryResult queryResult = response.getQueryResult();

        System.out.format("Knowledge results:\n");
        System.out.format("====================\n");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");
        KnowledgeAnswers knowledgeAnswers = queryResult.getKnowledgeAnswers();
        for (Answer answer : knowledgeAnswers.getAnswersList()) {
          System.out.format(" - Answer: '%s'\n", answer.getAnswer());
          System.out.format(" - Confidence: '%s'\n", answer.getMatchConfidence());
        }

        KnowledgeAnswers answers = queryResult.getKnowledgeAnswers();
        allKnowledgeAnswers.put(text, answers);
      }
    }
    return allKnowledgeAnswers;
  }
}

Node.js

Para autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

// Imports the Dialogflow client library
const dialogflow = require('@google-cloud/dialogflow').v2beta1;
// Instantiate a DialogFlow client.
const sessionClient = new dialogflow.SessionsClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const sessionId = `user specific ID of session, e.g. 12345`;
// const languageCode = 'BCP-47 language code, e.g. en-US';
// const knowledgeBaseId = `the ID of your KnowledgeBase`;
// const query = `phrase(s) to pass to detect, e.g. I'd like to reserve a room for six people`;

// Define session path
const sessionPath = sessionClient.projectAgentSessionPath(
  projectId,
  sessionId
);
const knowledgeBasePath =
  'projects/' + projectId + '/knowledgeBases/' + knowledgeBaseId + '';

// The audio query request
const request = {
  session: sessionPath,
  queryInput: {
    text: {
      text: query,
      languageCode: languageCode,
    },
  },
  queryParams: {
    knowledgeBaseNames: [knowledgeBasePath],
  },
};

const responses = await sessionClient.detectIntent(request);
const result = responses[0].queryResult;
console.log(`Query text: ${result.queryText}`);
console.log(`Detected Intent: ${result.intent.displayName}`);
console.log(`Confidence: ${result.intentDetectionConfidence}`);
console.log(`Query Result: ${result.fulfillmentText}`);
if (result.knowledgeAnswers && result.knowledgeAnswers.answers) {
  const answers = result.knowledgeAnswers.answers;
  console.log(`There are ${answers.length} answer(s);`);
  answers.forEach(a => {
    console.log(`   answer: ${a.answer}`);
    console.log(`   confidence: ${a.matchConfidence}`);
    console.log(`   match confidence level: ${a.matchConfidenceLevel}`);
  });
}

Python

Para autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

def detect_intent_knowledge(
    project_id, session_id, language_code, knowledge_base_id, texts
):
    """Returns the result of detect intent with querying Knowledge Connector.

    Args:
    project_id: The GCP project linked with the agent you are going to query.
    session_id: Id of the session, using the same `session_id` between requests
              allows continuation of the conversation.
    language_code: Language of the queries.
    knowledge_base_id: The Knowledge base's id to query against.
    texts: A list of text queries to send.
    """
    from google.cloud import dialogflow_v2beta1 as dialogflow

    session_client = dialogflow.SessionsClient()

    session_path = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session_path))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

        knowledge_base_path = dialogflow.KnowledgeBasesClient.knowledge_base_path(
            project_id, knowledge_base_id
        )

        query_params = dialogflow.QueryParameters(
            knowledge_base_names=[knowledge_base_path]
        )

        request = dialogflow.DetectIntentRequest(
            session=session_path, query_input=query_input, query_params=query_params
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))
        print("Knowledge results:")
        knowledge_answers = response.query_result.knowledge_answers
        for answers in knowledge_answers.answers:
            print(" - Answer: {}".format(answers.answer))
            print(" - Confidence: {}".format(answers.match_confidence))

Detectar respostas de intent

A resposta para o método detectIntent do tipo Sessions é um DetectIntentResponse. Vários fatores afetam como os campos de resposta são preenchidos.

Se a base de conhecimento e a intent definidas forem correspondentes em potencial, a confiança de correspondência de cada um e a preferência de resultados de conhecimento (consulte Configurações dos conectores de conhecimento) serão usadas para determinar qual correspondência será a selecionada. A correspondência selecionada é preenchida no campo DetectIntentResponse.queryResult, e outras possíveis correspondências são preenchidas no campo DetectIntentResponse.alternativeQueryResults. Ambos os campos contêm mensagens QueryResult.

Se uma base de conhecimento apresentar uma possível correspondência:

• QueryResult.knowledgeAnswers será preenchido com uma lista de possíveis respostas de conhecimento em ordem decrescente de confiança na correspondência.
• Se as respostas avançadas tiverem sido definidas para a base de conhecimento, QueryResult.fulfillmentMessages será preenchido com mensagens de resposta avançadas.

Ao executar uma solicitação de detecção de intent, é possível que a consulta de conhecimento falhe. Quando isso acontece, as intents definidas são selecionadas para que a solicitação geral de detecção de intent não falhe. Para informações de erro de consulta de conhecimento, veja o campo DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo.

Gerenciar bases de conhecimento

Para saber mais sobre como gerenciar bases de conhecimento, consulte Gerenciar bases de conhecimento.