Gerenciar bases de conhecimento

Uma base de conhecimento representa uma coleção de documentos de conhecimento fornecidos ao Dialogflow. Seus documentos de conhecimento contêm informações que podem ser úteis em conversas com usuários finais. Alguns recursos do Dialogflow usam bases de conhecimento ao procurar uma resposta para a expressão de um usuário final. Este guia descreve como criar e gerenciar as bases de conhecimento.

Uma base de conhecimento é aplicada no nível do agente.

Antes de começar

Faça o seguinte antes de ler este guia:

  1. Leia os Conceitos básicos do Dialogflow.
  2. Execute as etapas de configuração.

Criar uma base de conhecimento

Veja nos exemplos abaixo como usar o Console do Dialogflow, a API REST (incluindo a linha de comando) ou bibliotecas de cliente para criar uma base de conhecimento. Para usar a API, chame o método create no tipo KnowledgeBase.

IU da Web

Use o console do Dialogflow para criar uma base de conhecimento:

  1. Acessar o Console do Dialogflow ES
  2. Select an agent
  3. Clique em Conhecimento no menu da barra lateral esquerda.
  4. Clique em Criar base de conhecimento.
  5. Digite o nome de uma base de conhecimento.
  6. Clique em Salvar.

REST

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

  • PROJECT_ID: ID do projeto do GCP
  • KNOWLEDGE_BASE_DISPLAY_NAME: nome desejado para a base de conhecimento

Método HTTP e URL: 

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases

Corpo JSON da solicitação: 

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/knowledgeBases/NDA4MTM4NzE2MjMwNDUxMjAwMA",
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Anote o valor do campo name. Esse é o nome da nova base de conhecimento. O segmento de caminho após knowledgeBases é o novo ID da base de conhecimento. Salve este ID para as solicitações abaixo.

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.v2.KnowledgeBase;
import com.google.cloud.dialogflow.v2.KnowledgeBasesClient;
import com.google.cloud.dialogflow.v2.LocationName;
import java.io.IOException;

public class KnowledgeBaseManagement {

  public static void main(String[] args) throws ApiException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String location = "my-location";

    // Set display name of the new knowledge base
    String knowledgeBaseDisplayName = "my-knowledge-base-display-name";

    // Create a knowledge base
    createKnowledgeBase(projectId, location, knowledgeBaseDisplayName);
  }

  // Create a Knowledge base
  public static void createKnowledgeBase(String projectId, String location, String displayName)
      throws ApiException, IOException {
    // Instantiates a client
    try (KnowledgeBasesClient knowledgeBasesClient = KnowledgeBasesClient.create()) {
      KnowledgeBase targetKnowledgeBase =
          KnowledgeBase.newBuilder().setDisplayName(displayName).build();
      LocationName parent = LocationName.of(projectId, location);
      KnowledgeBase createdKnowledgeBase =
          knowledgeBasesClient.createKnowledgeBase(parent, targetKnowledgeBase);
      System.out.println("====================");
      System.out.format("Knowledgebase created:\n");
      System.out.format("Display Name: %s\n", createdKnowledgeBase.getDisplayName());
      System.out.format("Name: %s\n", createdKnowledgeBase.getName());
    }
  }
}

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 client = new dialogflow.KnowledgeBasesClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const displayName = `your knowledge base display name, e.g. myKnowledgeBase`;

const formattedParent = 'projects/' + projectId;
const knowledgeBase = {
  displayName: displayName,
};
const request = {
  parent: formattedParent,
  knowledgeBase: knowledgeBase,
};

const [result] = await client.createKnowledgeBase(request);
console.log(`Name: ${result.name}`);
console.log(`displayName: ${result.displayName}`);

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 create_knowledge_base(project_id, display_name):
    """Creates a Knowledge base.

    Args:
        project_id: The GCP project linked with the agent.
        display_name: The display name of the Knowledge base."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

    client = dialogflow.KnowledgeBasesClient()
    project_path = client.common_project_path(project_id)

    knowledge_base = dialogflow.KnowledgeBase(display_name=display_name)

    response = client.create_knowledge_base(
        parent=project_path, knowledge_base=knowledge_base
    )

    print("Knowledge Base created:\n")
    print("Display Name: {}\n".format(response.display_name))
    print("Name: {}\n".format(response.name))

Adicionar um documento à base de conhecimento

Sua nova base de conhecimento não tem documentos, por isso você deve adicionar um documento a ela. Veja abaixo na seção Conteúdo compatível uma descrição de todas as opções de conteúdo compatíveis. Você pode usar o documento das Perguntas frequentes do Cloud Storage para este exemplo.

Os exemplos abaixo mostram como usar o Console do Dialogflow, a API REST (incluindo a linha de comando) ou bibliotecas cliente para criar um documento de conhecimento. Para usar a API, chame o método create no tipo Document.

IU da Web

Use o console do Dialogflow para criar um documento de conhecimento:

  1. Se você não estiver seguindo as etapas acima, navegue até as configurações da base de conhecimento:
    1. Acessar o Console do Dialogflow ES
    2. Select an agent
    3. Clique em Conhecimento no menu da barra lateral esquerda.
    4. Clique no nome da base de conhecimento.
  2. Clique em Novo documento ou crie o primeiro.
  3. Digite o nome do documento.
  4. Selecione text/html em Tipo MIME.
  5. Selecione Perguntas frequentes em Tipo de conhecimento.
  6. Selecione URL como Fonte de dados.
  7. Insira https://cloud.google.com/storage/docs/faq no campo URL.
  8. Clique em CRIAR.

REST

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: o código da base de conhecimento retornado pela solicitação anterior
  • DOCUMENT_DISPLAY_NAME: nome do documento de conhecimento desejado

Método HTTP e URL: 

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID/documents

Corpo JSON da solicitação: 

{
  "displayName": "DOCUMENT_DISPLAY_NAME",
  "mimeType": "text/html",
  "knowledgeTypes": "FAQ",
  "contentUri": "https://cloud.google.com/storage/docs/faq"
}

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

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/operations/ks-add_document-MzA5NTY2MTc5Mzg2Mzc5NDY4OA"
}

O segmento de caminho após operations é o ID da operação.

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.longrunning.OperationFuture;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2.CreateDocumentRequest;
import com.google.cloud.dialogflow.v2.Document;
import com.google.cloud.dialogflow.v2.Document.KnowledgeType;
import com.google.cloud.dialogflow.v2.DocumentsClient;
import com.google.cloud.dialogflow.v2.KnowledgeOperationMetadata;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class DocumentManagement {

  public static void createDocument(
      String knowledgeBaseName,
      String displayName,
      String mimeType,
      String knowledgeType,
      String contentUri)
      throws IOException, ApiException, InterruptedException, ExecutionException, TimeoutException {
    // Instantiates a client
    try (DocumentsClient documentsClient = DocumentsClient.create()) {
      Document document =
          Document.newBuilder()
              .setDisplayName(displayName)
              .setContentUri(contentUri)
              .setMimeType(mimeType)
              .addKnowledgeTypes(KnowledgeType.valueOf(knowledgeType))
              .build();
      CreateDocumentRequest createDocumentRequest =
          CreateDocumentRequest.newBuilder()
              .setDocument(document)
              .setParent(knowledgeBaseName)
              .build();
      OperationFuture<Document, KnowledgeOperationMetadata> response =
          documentsClient.createDocumentAsync(createDocumentRequest);
      Document createdDocument = response.get(300, TimeUnit.SECONDS);
      System.out.format("Created Document:\n");
      System.out.format(" - Display Name: %s\n", createdDocument.getDisplayName());
      System.out.format(" - Document Name: %s\n", createdDocument.getName());
      System.out.format(" - MIME Type: %s\n", createdDocument.getMimeType());
      System.out.format(" - Knowledge Types:\n");
      for (KnowledgeType knowledgeTypeId : document.getKnowledgeTypesList()) {
        System.out.format("  - %s \n", knowledgeTypeId.getValueDescriptor());
      }
      System.out.format(" - Source: %s \n", document.getContentUri());
    }
  }
}

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 Documents client.
//   const client = new dialogflow.DocumentsClient({
//     projectId: projectId,
//   });

//   /**
//    * TODO(developer): Uncomment the following lines before running the sample.
//    */
//   // const projectId = 'ID of GCP project associated with your Dialogflow agent';
//   // const knowledgeBaseFullName = `the full path of your knowledge base, e.g my-Gcloud-project/myKnowledgeBase`;
//   // const documentPath = `path of the document you'd like to add, e.g. https://dialogflow.com/docs/knowledge-connectors`;
//   // const documentName = `displayed name of your document in knowledge base, e.g. myDoc`;
//   // const knowledgeTypes = `The Knowledge type of the Document. e.g. FAQ`;
//   // const mimeType = `The mime_type of the Document. e.g. text/csv, text/html,text/plain, text/pdf etc.`;

//   const request = {
//     parent: knowledgeBaseFullName,
//     document: {
//       knowledgeTypes: [knowledgeTypes],
//       displayName: documentName,
//       contentUri: documentPath,
//       source: 'contentUri',
//       mimeType: mimeType,
//     },
//   };

//   const [operation] = await client.createDocument(request);
//   const [response] = await operation.promise();

//   console.log('Document created');
//   console.log(`Content URI...${response.contentUri}`);
//   console.log(`displayName...${response.displayName}`);
//   console.log(`mimeType...${response.mimeType}`);
//   console.log(`name...${response.name}`);
//   console.log(`source...${response.source}`);

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 create_document(
    project_id, knowledge_base_id, display_name, mime_type, knowledge_type, content_uri
):
    """Creates a Document.

    Args:
        project_id: The GCP project linked with the agent.
        knowledge_base_id: Id of the Knowledge base.
        display_name: The display name of the Document.
        mime_type: The mime_type of the Document. e.g. text/csv, text/html,
            text/plain, text/pdf etc.
        knowledge_type: The Knowledge type of the Document. e.g. FAQ,
            EXTRACTIVE_QA.
        content_uri: Uri of the document, e.g. gs://path/mydoc.csv,
            http://mypage.com/faq.html."""
    from google.cloud import dialogflow_v2beta1 as dialogflow

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

    document = dialogflow.Document(
        display_name=display_name, mime_type=mime_type, content_uri=content_uri
    )

    document.knowledge_types.append(
        getattr(dialogflow.Document.KnowledgeType, knowledge_type)
    )

    response = client.create_document(parent=knowledge_base_path, document=document)
    print("Waiting for results...")
    document = response.result(timeout=120)
    print("Created Document:")
    print(" - Display Name: {}".format(document.display_name))
    print(" - Knowledge ID: {}".format(document.name))
    print(" - MIME Type: {}".format(document.mime_type))
    print(" - Knowledge Types:")
    for knowledge_type in document.knowledge_types:
        print("    - {}".format(KNOWLEDGE_TYPES[knowledge_type]))
    print(" - Source: {}\n".format(document.content_uri))

A criação de um documento é uma operação de longa duração. Portanto, pode levar um tempo considerável para ser concluída. É possível pesquisar o status dessa operação para ver se ela foi concluída. Depois de concluída, a operação contém o ID do documento recém-criado. Salve esse ID para processamento futuro. Para mais informações, consulte Operações de longa duração.

Gerenciar documentos de conhecimento

Atualizar o conteúdo do documento de conhecimento

Se você atualizar seu conteúdo citado em um documento de conhecimento, talvez esse documento não seja atualizado automaticamente. Seu conteúdo será atualizado automaticamente se ele for fornecido como um URL público e você tiver marcado a opção Ativar recarregamento automático.

Para atualizar manualmente o Cloud Storage ou o conteúdo do documento de URL público, chame o método reload no tipo Document.

Para atualizar manualmente o conteúdo bruto enviado, use os métodos delete e create no tipo Document para recriar seu documento.

Listar documentos de conhecimento

Você pode listar todos os documentos de conhecimento da sua base de conhecimento. Para usar a API, chame o método list no tipo Document.

Excluir documentos de conhecimento

Você pode excluir os documentos de conhecimento da sua base de conhecimento. Para usar a API, chame o método delete no tipo Document. Se você não tiver o ID do documento, poderá listar os documentos conforme descrito acima.

Conteúdo permitido

Os seguintes tipos de documentos de conhecimento são compatíveis:

  • Perguntas frequentes: o conteúdo do documento contém pares de perguntas e respostas na forma HTML ou CSV. Os formatos HTML de perguntas frequentes comuns são analisados com precisão, mas formatos incomuns podem não ser analisados. O CSV precisa ter perguntas na primeira coluna e respostas na segunda, sem cabeçalho. Devido a esse formato explícito, eles são sempre analisados com precisão.
  • Controle de qualidade extrativo: documentos para os quais o texto não estruturado é extraído e usado para responder a perguntas.

A tabela a seguir mostra os tipos MIME permitidos em Tipo de conhecimento e Origem.

Tipo de conhecimento\origem Arquivo enviado por upload (Document.content) (NÃO recomendado) Arquivo enviado por upload (Document.raw_content) (recomendado) Arquivo do Cloud Storage (Document.contentUri) Arquivo do URL público (Document.contentUri)
Perguntas frequentes text/csv text/csv text/csv text/html
Controle de qualidade extrativo text/plain, text/html text/plain, text/html, application/pdf text/plain, text/html, application/pdf N/A

O conteúdo do documento tem os seguintes problemas conhecidos, limitações e práticas recomendadas:

Geral:

  • Os arquivos de URLs públicos precisam ter sido rastreados pelo indexador do Google Search para que apareçam no índice de pesquisa. Verifique isso com o Google Search Console. O indexador não mantém o conteúdo atualizado. Você precisa atualizar explicitamente o documento de conhecimento quando o conteúdo de origem for alterado.
  • Arquivos CSV precisam usar vírgulas como delimitadores.
  • As pontuações de confiança ainda não estão calibradas entre as perguntas frequentes e os artigos da base de conhecimento. Portanto, se você usar os dois, o melhor resultado nem sempre será o mais alto.
  • O Dialogflow remove tags HTML do conteúdo ao criar respostas. Por esse motivo, é melhor evitar tags HTML e usar texto simples quando possível.
  • As respostas do Google Assistente têm um limite de 640 caracteres por balão de chat. Portanto, respostas longas são truncadas na integração com o Google Assistente.
  • O tamanho máximo do documento é 50 MB.
  • Ao usar arquivos do Cloud Storage, você precisa utilizar URIs públicos ou privados para acesso da sua conta de usuário ou de serviço.

Específico às perguntas frequentes:

  • O CSV precisa ter perguntas na primeira coluna e respostas na segunda, sem cabeçalho.
  • Use o CSV sempre que possível, porque ele é analisado com mais precisão.
  • Conteúdo de HTML público com um único par de controles de qualidade não é permitido.
  • O número de pares de controles de qualidade em um documento não deve exceder 2.000.
  • Perguntas duplicadas com respostas diferentes não são aceitas.
  • Use qualquer documento de perguntas frequentes: o analisador de perguntas frequentes pode processar a maioria dos formatos delas.

Específico ao controle de qualidade extrativo:

  • O controle de qualidade extrativo é experimental. Ele é baseado em tecnologias semelhantes que foram executadas e testadas no Google em produtos como Pesquisa e Assistente. Envie-nos seu feedback sobre o funcionamento dele no Dialogflow.
  • Conteúdo com texto denso funciona melhor. Evite conteúdo com muitos parágrafos de frase única.
  • Tabelas e listas não são permitidas.
  • O número de parágrafos em um documento não pode exceder 2.000.
  • Se um artigo for longo (mais de mil palavras), tente dividi-lo em vários artigos menores. Além disso, se abordar vários problemas, ele poderá ser dividido em artigos menores que abranjam problemas individuais. Porém, se o artigo abordar apenas um problema, concentre-o na descrição do problema e seja breve na resolução.
  • O ideal é que apenas o conteúdo principal de um artigo seja fornecido (descrição e resolução do problema). Conteúdos extras como nome do autor, histórico de modificações, links relacionados e anúncios não são importantes.
  • Tente incluir uma descrição dos problemas que um artigo pode ajudar a resolver e/ou exemplos de consultas que ele pode responder.

Como usar o Cloud Storage

Se seu conteúdo não for público, armazená-lo no Cloud Storage é a opção recomendada. Ao criar documentos de conhecimento, você deve fornecer os URLs dos seus objetos do Cloud Storage.

Como criar buckets e objetos do Cloud Storage

Ao criar o bucket do Cloud Storage:

  • Verifique se selecionou o projeto do GCP que você usa para o Dialogflow.
  • Verifique se a conta de usuário ou de serviço que você normalmente usa para acessar a API Dialogflow tem permissões de leitura nos objetos do bucket.
  • Use a classe Standard Storage.
  • Defina o local do bucket como o local mais próximo de você. Você precisará do ID do local (por exemplo, us-west1) para algumas chamadas da API. Portanto, lembre-se de sua escolha.

Siga as instruções do guia de início rápido do Cloud Storage para criar um bucket e fazer o upload de arquivos.

Como fornecer um objeto do Cloud Storage para um documento de base de conhecimento

Para fornecer seu conteúdo:

  • Crie uma base de conhecimento como descrito acima.
  • Crie um documento de conhecimento conforme descrito acima. Ao chamar o método create no tipo Document, defina contentUri como o URL do seu documento do Cloud Storage. O formato desse URL é gs://bucket-name/object-name.
Anterior
Gerenciar intents com a API
Próxima
Atualizar dados com um FieldMask