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.

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 e LINHA DE CMD

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

  • project-id: código 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


import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2beta1.KnowledgeBase;
import com.google.cloud.dialogflow.v2beta1.KnowledgeBasesClient;
import com.google.cloud.dialogflow.v2beta1.ProjectName;
import java.io.IOException;

public class KnowledgeBaseManagement {

  // Create a Knowledge base
  public static KnowledgeBase createKnowledgeBase(String projectId, String displayName)
      throws ApiException, IOException {
    // Instantiates a client
    try (KnowledgeBasesClient knowledgeBasesClient = KnowledgeBasesClient.create()) {
      KnowledgeBase knowledgeBase = KnowledgeBase.newBuilder().setDisplayName(displayName).build();
      ProjectName projectName = ProjectName.of(projectId);
      KnowledgeBase response = knowledgeBasesClient.createKnowledgeBase(projectName, knowledgeBase);
      System.out.format("Knowledgebase created:\n");
      System.out.format("Display Name: %s \n", response.getDisplayName());
      System.out.format("Knowledge ID: %s \n", response.getName());

      return response;
    }
  }
}

Node.js

// 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

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('Knowledge ID: {}\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 e faça o seguinte:
    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 e LINHA DE CMD

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

  • project-id: código 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


import com.google.api.gax.longrunning.OperationFuture;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.dialogflow.v2beta1.CreateDocumentRequest;
import com.google.cloud.dialogflow.v2beta1.Document;
import com.google.cloud.dialogflow.v2beta1.Document.KnowledgeType;
import com.google.cloud.dialogflow.v2beta1.DocumentsClient;
import com.google.cloud.dialogflow.v2beta1.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 Document 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(180, TimeUnit.SECONDS);
      System.out.format("Created Document:\n");
      System.out.format(" - Display Name: %s\n", createdDocument.getDisplayName());
      System.out.format(" - Knowledge ID: %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());
      return createdDocument;
    }
  }
}

Node.js

//   // 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

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 referenciado por um documento de conhecimento, esse documento não será atualizado automaticamente.

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

Para atualizar 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.
  • Um 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.
  • Use a classe Armazenamento padrão.
  • 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.