Gestionar bases de conocimientos

Una base de conocimientos representa una colección de documentos de conocimientos que proporcionas a Dialogflow. Tus documentos de conocimientos contienen información que puede ser útil durante las conversaciones con los usuarios finales. Algunas funciones de Dialogflow usan bases de conocimientos cuando buscan una respuesta a una expresión de un usuario final. En esta guía se describe cómo crear y gestionar bases de conocimientos.

Una base de conocimientos se aplica a nivel de agente.

Antes de empezar

Antes de leer esta guía, debes hacer lo siguiente:

  1. Consulta los conceptos básicos de Dialogflow.
  2. Sigue los pasos de configuración.

Crear una base de conocimientos

En los ejemplos siguientes se muestra cómo usar la consola de Dialogflow, la API REST (incluida la línea de comandos) o las bibliotecas de cliente para crear una base de conocimientos. Para usar la API, llama al método create en el tipo KnowledgeBase.

UI web

Para crear una base de conocimientos en la consola de Dialogflow, sigue estos pasos:

  1. Ve a la consola de Dialogflow ES.
  2. Select an agent
  3. En el menú de la barra lateral de la izquierda, haz clic en Conocimientos.
  4. Haga clic en Crear base de conocimientos.
  5. Introduce un nombre para la base de conocimientos
  6. Haz clic en Guardar.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto de GCP
  • KNOWLEDGE_BASE_DISPLAY_NAME: nombre de la base de conocimientos que quieras

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "displayName": "KNOWLEDGE_BASE_DISPLAY_NAME"
}

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

Anota el valor del campo name. Este es el nombre de tu nueva base de conocimientos. El segmento de ruta después de knowledgeBases es el nuevo ID de la base de conocimientos. Guarda este ID para las solicitudes que se indican más abajo.

Java

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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))

Añadir un documento a la base de conocimientos

Tu nueva base de conocimientos no tiene ningún documento, por lo que deberías añadir uno. Consulta la sección Contenido admitido más abajo para ver una descripción de todas las opciones de contenido admitidas. Puedes usar el documento de preguntas frecuentes de Cloud Storage para este ejemplo.

En los ejemplos siguientes se muestra cómo usar la consola de Dialogflow, la API REST (incluida la línea de comandos) o las bibliotecas de cliente para crear un documento de conocimientos. Para usar la API, llama al método create en el tipo Document.

UI web

Para crear un documento de conocimiento en la consola de Dialogflow, sigue estos pasos:

  1. Si no has seguido los pasos anteriores, ve a los ajustes de la base de conocimientos:
    1. Ve a la consola de Dialogflow ES.
    2. Select an agent
    3. En el menú de la barra lateral de la izquierda, haz clic en Conocimientos.
    4. Haga clic en el nombre de su base de conocimientos.
  2. Haz clic en Nuevo documento o en Crea el primero.
  3. Introduce un nombre para el documento
  4. Selecciona text/html en Mime Type (Tipo de MIME).
  5. Selecciona Preguntas frecuentes en Tipo de conocimiento.
  6. Seleccione URL en Fuente de datos.
  7. Escribe https://cloud.google.com/storage/docs/faq en el campo URL.
  8. Haz clic en CREAR.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_ID: tu ID de proyecto de GCP
  • KNOWLEDGE_BASE_ID: el ID de la base de conocimientos devuelto en la solicitud anterior.
  • DOCUMENT_DISPLAY_NAME: nombre del documento de conocimientos deseado

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, despliega una de estas opciones:

Deberías recibir una respuesta JSON similar a la siguiente:

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

El segmento de la ruta que aparece después de operations es tu ID de operación.

Java

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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 autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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))

Crear un documento es una operación de larga duración, por lo que puede tardar bastante tiempo en completarse. Puedes sondear el estado de esta operación para ver si se ha completado. Una vez completada, la operación contiene el ID del documento recién creado. Guarda este ID para procesarlo más adelante. Para obtener más información, consulta Operaciones de larga duración.

Gestionar documentos de conocimientos

Actualizar el contenido de un documento de conocimientos

Si actualizas el contenido al que hace referencia un documento de conocimiento, es posible que este no se actualice automáticamente. El contenido solo se actualiza automáticamente si se proporciona como una URL pública y has marcado la opción Habilitar recarga automática del documento.

Para actualizar manualmente el contenido de un documento de Cloud Storage o de una URL pública, llama al método reload del tipo Document.

Para actualizar manualmente el contenido sin formato subido, usa los métodos delete y create en el tipo Document para volver a crear el documento.

Listar documentos de conocimientos

Puedes enumerar todos los documentos de conocimiento de tu base de conocimientos. Para usar la API, llama al método list en el tipo Document.

Eliminar documentos de conocimientos

Puedes eliminar documentos de conocimientos de tu base de conocimientos. Para usar la API, llama al método delete en el tipo Document. Si no tienes el ID del documento, puedes enumerar los documentos como se ha descrito anteriormente.

Contenido admitido

Se admiten los siguientes tipos de documentos de conocimientos:

  • Preguntas frecuentes: el contenido del documento contiene pares de preguntas y respuestas en formato HTML o CSV. Los formatos HTML de preguntas frecuentes típicos se analizan correctamente, pero es posible que los formatos poco habituales no se analicen. El archivo CSV debe tener las preguntas en la primera columna y las respuestas en la segunda, sin encabezados. Gracias a este formato explícito, siempre se analizan correctamente.
  • Control de calidad extractivo: documentos de los que se extrae texto no estructurado y se usa para responder preguntas.

En la siguiente tabla se muestran los tipos MIME admitidos por Tipo de conocimiento y Fuente.

Knowledge Type \ Source Archivo subido (Document.content) (NO recomendado) Archivo subido (Document.raw_content) (recomendado) Archivo de Cloud Storage (Document.contentUri) Archivo de URL pública (Document.contentUri)
Preguntas frecuentes text/csv text/csv text/csv text/html
Extracción de respuestas text/plain, text/html text/plain, text/html, application/pdf text/plain, text/html, application/pdf N/A

El contenido de los documentos tiene los siguientes problemas conocidos, limitaciones y prácticas recomendadas:

General:

  • El indexador de la Búsqueda de Google debe haber rastreado los archivos de las URLs públicas para que estén en el índice de búsqueda. Puede comprobarlo con Google Search Console. Tenga en cuenta que el indexador no mantiene su contenido actualizado. Debes actualizar explícitamente tu documento de conocimientos cuando cambie el contenido de la fuente.
  • Los archivos CSV deben usar comas como delimitadores.
  • Las puntuaciones de confianza aún no se han calibrado entre las preguntas frecuentes y los artículos de la base de conocimientos, por lo que, si utilizas ambos, es posible que el mejor resultado no siempre sea el más alto.
  • Dialogflow elimina las etiquetas HTML del contenido al crear respuestas. Por este motivo, es mejor evitar las etiquetas HTML y usar texto sin formato siempre que sea posible.
  • Las respuestas del Asistente de Google tienen un límite de 640 caracteres por burbuja de chat, por lo que las respuestas largas se truncan al integrarse con el Asistente de Google.
  • El tamaño máximo del documento es de 50 MB.
  • Cuando utilices archivos de Cloud Storage, debes usar URIs públicos o URIs privados a los que tu cuenta de usuario o cuenta de servicio tengan acceso.

Específicas de las preguntas frecuentes:

  • El archivo CSV debe tener las preguntas en la primera columna y las respuestas en la segunda, sin encabezados.
  • Utiliza el formato CSV siempre que sea posible, ya que es el que se analiza con mayor precisión.
  • No se admite contenido HTML público con un solo par de preguntas y respuestas.
  • El número de pares de preguntas y respuestas de un documento no debe superar los 2000.
  • No se admiten preguntas duplicadas con respuestas diferentes.
  • Puedes usar cualquier documento de preguntas frecuentes, ya que el analizador de preguntas frecuentes puede gestionar la mayoría de los formatos.

Específico de Extractive QA:

  • Actualmente, la respuesta a preguntas extractiva es experimental. Se basa en tecnologías similares que se han probado en Google en productos como la Búsqueda y el Asistente. Envíanos tus comentarios sobre su funcionamiento en Dialogflow.
  • El contenido con texto denso funciona mejor. Evita el contenido con muchos párrafos de una sola frase.
  • No se admiten tablas ni listas.
  • El número de párrafos de un documento no debe superar los 2000.
  • Si un artículo es largo (más de 1000 palabras), intenta dividirlo en varios artículos más pequeños. Si el artículo trata varios temas, se puede dividir en artículos más cortos que aborden cada tema por separado. Si el artículo solo trata un problema, céntrate en la descripción del problema y haz que la solución sea breve.
  • Lo ideal es que solo se proporcione el contenido principal de un artículo (descripción del problema y solución). No es importante el contenido adicional, como el nombre del autor, el historial de modificaciones, los enlaces relacionados y los anuncios.
  • Intenta incluir una descripción de los problemas que puede ayudar a resolver un artículo o consultas de ejemplo que este artículo puede responder.

Usar Cloud Storage

Si tu contenido no es público, te recomendamos que lo almacenes en Cloud Storage. Cuando creas documentos de conocimientos, proporcionas las URLs de tus objetos de Cloud Storage.

Crear segmentos y objetos de Cloud Storage

Al crear el segmento de Cloud Storage:

Sigue las instrucciones de la guía de inicio rápido de Cloud Storage para crear un segmento y subir archivos.

Proporcionar un objeto de Cloud Storage a un documento de base de conocimientos

Para proporcionar tu contenido, sigue estos pasos:

  • Crea una base de conocimientos como se describe más arriba.
  • Crea un documento de conocimientos como se describe más arriba. Cuando llames al método create en el tipo Document, asigna al campo contentUri la URL de tu documento de Cloud Storage. El formato de esta URL es gs://bucket-name/object-name.