Faça a gestão das bases de conhecimentos

Uma base de conhecimentos representa uma coleção de documentos de conhecimentos que fornece ao Dialogflow. Os seus documentos de conhecimentos contêm informações que podem ser úteis durante as conversas com os utilizadores finais. Algumas funcionalidades do Dialogflow usam bases de conhecimentos quando procuram uma resposta a uma expressão do utilizador final. Este guia descreve como criar e gerir bases de conhecimentos.

Uma base de conhecimentos é aplicada ao nível do agente.

Antes de começar

Antes de ler este guia, deve fazer o seguinte:

  1. Leia as noções básicas do Dialogflow.
  2. Realize os passos de configuração.

Crie uma base de conhecimentos

Os exemplos abaixo mostram como usar a consola do Dialogflow, a API REST (incluindo a linha de comandos) ou as bibliotecas cliente para criar uma base de conhecimentos. Para usar a API, chame o método create no tipo KnowledgeBase.

IU da Web

Use a consola do Dialogflow para criar uma base de conhecimentos:

  1. Aceda à consola do Dialogflow ES
  2. Select an agent
  3. Clique em Conhecimento no menu da barra lateral esquerda
  4. Clique em Criar base de conhecimentos
  5. Introduza um nome da base de conhecimentos
  6. Clique em Guardar.

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • KNOWLEDGE_BASE_DISPLAY_NAME: nome da base de conhecimentos pretendida

Método HTTP e URL: 

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

Corpo JSON do pedido: 

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Tome nota do valor do campo name. Este é o nome da sua nova base de conhecimentos. O segmento do caminho após knowledgeBases é o novo ID da base de conhecimentos. Guarde este ID para os pedidos abaixo.

Java

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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))

Adicione um documento à base de conhecimentos

Atualmente, a sua nova base de conhecimentos não tem documentos. Por isso, deve adicionar um documento. Consulte a secção Conteúdo suportado abaixo para ver uma descrição de todas as opções de conteúdo suportadas. Pode usar o documento de Perguntas frequentes do Cloud Storage para este exemplo.

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

IU da Web

Use a consola do Dialogflow para criar um documento de conhecimentos:

  1. Se não estiver a continuar a partir dos passos acima, navegue para as definições da base de conhecimentos:
    1. Aceda à consola do Dialogflow ES
    2. Select an agent
    3. Clique em Conhecimento no menu da barra lateral esquerda
    4. Clique no nome da base de conhecimentos
  2. Clique em Novo documento ou Criar o primeiro
  3. Introduza um nome de documento
  4. Selecione text/html para Tipo MIME
  5. Selecione Perguntas frequentes para Tipo de conhecimento
  6. Selecione URL para Origem de dados
  7. Introduza https://cloud.google.com/storage/docs/faq no campo URL
  8. Clique em CRIAR

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID do seu projeto da GCP
  • KNOWLEDGE_BASE_ID: o ID da base de conhecimentos devolvido pelo pedido anterior
  • DOCUMENT_DISPLAY_NAME: desired knowledge document name

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

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

Java

Para se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 se autenticar no Dialogflow, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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, pelo que pode demorar um período considerável a ser concluída. Pode verificar o estado desta operação para ver se foi concluída. Quando estiver concluída, a operação contém o ID do documento recém-criado. Guarde este ID para processamento futuro. Para mais informações, consulte o artigo Operações de longa duração.

Faça a gestão dos documentos de conhecimentos

Atualize o conteúdo do documento de conhecimentos

Se atualizar o conteúdo referenciado por um documento de conhecimentos, o documento de conhecimentos pode não ser atualizado automaticamente. O conteúdo só é atualizado automaticamente se for fornecido como um URL público e tiver selecionado a opção Ativar recarregamento automático para o documento.

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

Para atualizar manualmente o conteúdo não processado carregado, use os métodos delete e create no tipo Document para recriar o documento.

Liste documentos de conhecimento

Pode listar todos os documentos de conhecimentos da sua base de conhecimentos. Para usar a API, chame o método list no tipo Document.

Elimine documentos de conhecimentos

Pode eliminar documentos de conhecimentos da sua base de conhecimentos. Para usar a API, chame o método delete no tipo Document. Se não tiver o ID do documento, pode listar os documentos conforme descrito acima.

Conteúdo suportado

São suportados os seguintes tipos de documentos de conhecimentos:

  • Perguntas frequentes: o conteúdo do documento contém pares de perguntas e respostas como HTML ou CSV. Os formatos HTML de Perguntas frequentes típicos são analisados com precisão, mas os formatos invulgares podem não ser analisados. O CSV tem de ter perguntas na primeira coluna e respostas na segunda, sem cabeçalho. Devido a este formato explícito, são sempre analisados com precisão.
  • QA de extração: documentos dos quais é extraído texto não estruturado e que são usados para responder a perguntas.

A tabela seguinte mostra os tipos MIME suportados por tipo de conhecimento e fonte.

Knowledge Type \ Source Ficheiro carregado (Document.content) (NÃO recomendado) Ficheiro carregado (Document.raw_content) (recomendado) Ficheiro do Cloud Storage (Document.contentUri) Ficheiro de URL público (Document.contentUri)
Perguntas frequentes text/csv text/csv text/csv text/html
QA extrativo text/plain, text/html text/plain, text/html, application/pdf text/plain, text/html, application/pdf N/A

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

Geral:

  • Os ficheiros de URLs públicos têm de ter sido rastreados pelo indexador da Pesquisa Google, para que existam no índice de pesquisa. Pode verificar esta situação com a Google Search Console. Tenha em atenção que o indexador não mantém o seu conteúdo atualizado. Tem de atualizar explicitamente o documento de conhecimentos quando o conteúdo de origem é alterado.
  • Os ficheiros CSV têm de usar vírgulas como delimitadores.
  • As classificações de confiança ainda não estão calibradas entre as Perguntas frequentes e os artigos da base de conhecimentos, por isso, se usar ambos, as Perguntas frequentes e os artigos da base de conhecimentos, o melhor resultado pode nem sempre ser o mais elevado.
  • O Dialogflow remove as etiquetas HTML do conteúdo quando cria respostas. Por este motivo, é preferível evitar as etiquetas HTML e usar texto simples sempre que possível.
  • As respostas do Assistente Google têm um limite de 640 carateres por balão de chat. Por isso, as respostas longas são truncadas quando são integradas com o Assistente Google.
  • O tamanho máximo do documento é de 50 MB.
  • Quando usar ficheiros do Cloud Storage, deve usar URIs públicos ou URIs privados aos quais a sua conta de utilizador ou conta de serviço tenha acesso.

Específico das Perguntas frequentes:

  • O CSV tem de ter perguntas na primeira coluna e respostas na segunda, sem cabeçalho.
  • Sempre que possível, use CSV, porque é analisado com maior precisão.
  • O conteúdo HTML público com um único par de QA não é suportado.
  • O número de pares de perguntas e respostas num documento não deve exceder 2000.
  • Não é suportada a duplicação de perguntas com respostas diferentes.
  • Pode usar qualquer documento de Perguntas frequentes; o analisador de Perguntas frequentes é capaz de processar a maioria dos formatos de Perguntas frequentes.

Específico para CQ extrativa:

  • A QA extrativa é atualmente experimental. Baseia-se em tecnologias semelhantes que foram experimentadas e testadas na Google em produtos como a Pesquisa e o Assistente. Envie-nos o seu feedback sobre o desempenho do Dialogflow.
  • O conteúdo com texto denso funciona melhor. Evite conteúdo com muitos parágrafos de uma única frase.
  • As tabelas e as listas não são suportadas.
  • O número de parágrafos num documento não deve exceder 2000.
  • Se um artigo for longo (> 1000 palavras), tente dividi-lo em vários artigos mais pequenos. Se o artigo abordar vários problemas, pode ser dividido em artigos mais curtos que abordem os problemas individuais. Se o artigo abranger apenas um problema, foque-se na descrição do problema e mantenha a resolução do problema breve.
  • Idealmente, apenas deve fornecer o conteúdo essencial de um artigo (descrição e resolução do problema). O conteúdo adicional, como o nome do autor, o histórico de modificações, os links relacionados e os anúncios, não é importante.
  • Tente incluir uma descrição dos problemas que um artigo pode ajudar a resolver e/ou exemplos de consultas que este artigo pode responder.

Usar o Cloud Storage

Se o seu conteúdo não for público, armazená-lo no Cloud Storage é a opção recomendada. Quando cria documentos de conhecimentos, fornece os URLs dos seus objetos do Cloud Storage.

Criar contentores e objetos do Cloud Storage

Ao criar o contentor do Cloud Storage:

Siga as instruções do início rápido do Cloud Storage para criar um contentor e carregar ficheiros.

Fornecer um objeto do Cloud Storage a um documento da base de conhecimentos

Para fornecer o seu conteúdo:

  • Crie uma base de conhecimentos conforme descrito acima.
  • Crie um documento de conhecimentos conforme descrito acima. Quando chamar o método create no tipo Document, defina o campo contentUri para o URL do seu documento do Cloud Storage. O formato deste URL é gs://bucket-name/object-name.
Anterior
Faça a gestão de intenções com a API
Avançar
Atualize dados com um FieldMask