Administra bases de conocimiento

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

Una base de conocimiento se aplica a nivel del agente.

Antes de comenzar

Debes hacer lo siguiente antes de leer esta guía:

  1. Lee los conceptos básicos de Dialogflow.
  2. Realiza los pasos de configuración.

Crea una base de conocimiento

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

IU web

Usa la consola de Dialogflow para crear una base de conocimiento:

  1. Ve a la consola de Dialogflow ES.
  2. Selecciona un agente.
  3. Haz clic en Conocimiento (Knowledge) en el menú de la barra lateral izquierda.
  4. Haz clic en Crear una base de conocimiento.
  5. Ingresa un nombre para la base de conocimiento.
  6. Haga clic en Guardar.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de GCP.
  • KNOWLEDGE_BASE_DISPLAY_NAME: Es el nombre de la base de conocimiento deseada.

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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Anota el valor del campo name. Este es el nombre de tu base de conocimiento nueva. El segmento de ruta después de knowledgeBases es el ID nuevo de la base de conocimiento. Guarda este ID para las solicitudes que se muestran a continuación.

Java

Para autenticarte en Dialogflow, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para 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))

Agrega un documento a la base de conocimiento

En la actualidad, tu nueva base de conocimiento no tiene documentos, por lo que debes agregarle un documento. Consulta el contenido admitido a continuación para ver una descripción de las opciones de contenido admitidas. Puedes usar el documento de Preguntas frecuentes de Cloud Storage para este ejemplo.

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

IU web

Usa la consola de Dialogflow para crear un documento de conocimiento:

  1. Si no continúas desde los pasos anteriores, navega a la configuración de tu base de conocimiento y haz lo siguiente:
    1. Ve a la consola de Dialogflow ES.
    2. Selecciona un agente.
    3. Haz clic en Conocimiento en el menú de la barra lateral izquierda.
    4. Haz clic en el nombre de tu base de conocimiento.
  2. Haz clic en Documento nuevo o Crear el primero.
  3. Ingresa un nombre para el documento.
  4. Selecciona texto/html para Tipo de Mime.
  5. Selecciona Preguntas frecuentes para Tipo de conocimiento.
  6. Selecciona URL para Fuente de datos.
  7. Ingresa https://cloud.google.com/storage/docs/faq en el campo URL.
  8. Haz clic en CREAR.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de GCP.
  • KNOWLEDGE_BASE_ID: Es el ID de tu base de conocimiento que se muestra en la solicitud anterior.
  • DOCUMENT_DISPLAY_NAME: Es el nombre del documento de conocimiento 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, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

El segmento de 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. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para 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. Si deseas obtener más información, consulta Configura la autenticación para 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))

La creación de un documento es una operación de larga duración, por lo que puede tardar bastante tiempo en completarse. Puedes consultar 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.

Administra documentos de conocimiento

Actualiza el contenido de un documento de conocimiento

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

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

Si deseas actualizar de forma manual el contenido sin procesar que se subió, usa los métodos delete y create en el tipo Document para volver a crear el documento.

Enumera los documentos de conocimiento

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

Borra los documentos de conocimiento

Puedes borrar los documentos de conocimiento de tu base de conocimiento. Para usar la API, realiza una llamada al método delete en el tipo Document. Si no tienes el ID del documento, puedes enumerar los documentos como se describió en la sección anterior.

Contenido admitido

Se admiten los siguientes tipos de documentos de conocimiento:

  • 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 con precisión, pero es posible que falle el análisis de los formatos inusuales. El CSV debe tener preguntas en la primera columna y respuestas en la segunda, sin encabezado. Debido a este formato explícito, siempre se analizan con precisión.
  • Control de calidad de extracción: documentos para los que se extrae texto no estructurado y que se usan a fin de responder preguntas.

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

Fuente\Tipo de conocimiento 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 texto/csv texto/csv texto/csv text/html
Control de calidad de extracción texto/sin formato, texto/html texto/sin formato, texto/html, aplicación/pdf texto/sin formato, texto/html, aplicación/pdf No aplica

El contenido del documento tiene las siguientes limitaciones, recomendaciones y problemas conocidos:

General:

  • Para que los archivos de las URL públicas existan en el índice de búsqueda, el indexador de Búsqueda de Google debe haberlos rastreado. Puedes verificar esto con Google Search Console. Ten en cuenta que el indexador no mantiene actualizado el contenido. Cuando cambie el contenido de origen, deberás actualizar tu documento de conocimiento de forma explícita.
  • Los archivos CSV deben usar comas como delimitadores.
  • Las puntuaciones de confianza de los artículos de base de conocimiento y las Preguntas frecuentes aún no están calibradas entre sí, por lo que si usas ambas fuentes de información, es posible que en algunos casos no se le asigne la puntuación máxima al mejor resultado.
  • Dialogflow quita las etiquetas HTML del contenido cuando se crean respuestas. Debido a esto, es mejor evitar las etiquetas HTML y usar texto sin formato cuando sea posible.
  • Las respuestas del Asistente de Google tienen un límite de 640 caracteres por cuadro de chat, por lo que las respuestas largas se truncan cuando se integran en el Asistente de Google.
  • El tamaño máximo de documento es 50 MB.
  • Cuando usas archivos de Cloud Storage, debes usar URI públicos o privados a los que tu cuenta de servicio o usuario tenga acceso.

Específico de las Preguntas frecuentes:

  • El CSV debe tener preguntas en la primera columna y respuestas en la segunda, sin encabezado.
  • Usa CSV cuando sea posible, porque el CSV se analiza con mayor precisión.
  • El contenido HTML público con un único par de QA no es compatible.
  • La cantidad de pares de QA en un documento no debe ser superior a 2,000.
  • Las preguntas duplicadas con diferentes respuestas no son compatibles.
  • Puedes usar cualquier documento de Preguntas frecuentes. El analizador de Preguntas frecuentes es capaz de administrar la mayoría de los formatos de Preguntas frecuentes.

La siguiente información es específica para el control de calidad de extracción:

  • En la actualidad, el control de calidad de extracción se encuentra en estado experimental. Se basa en tecnologías similares que se probaron en productos de Google, como la Búsqueda y el Asistente. Envíanos tus comentarios sobre qué tan bien funciona para Dialogflow.
  • El contenido con texto denso funciona mejor. Evita el contenido con muchos párrafos de una sola oración.
  • Las tablas y listas no son compatibles.
  • La cantidad de párrafos en un documento no debe ser superior a 2,000.
  • Si un artículo es largo (> 1,000 palabras), intenta dividirlo en varios artículos más pequeños. Si el artículo abarca varios temas, puede dividirse en artículos más breves que cubran los subtemas. Si el artículo solo abarca un tema, enfoca el artículo en la descripción del tema y mantén la resolución del problema breve.
  • Lo ideal es que solo se proporcione el contenido principal de un artículo (descripción y resolución del problema). El contenido adicional como el nombre del autor, el historial de modificaciones, los vínculos relacionados y los anuncios no es importante.
  • Intenta incluir una descripción de los problemas que el artículo intenta solucionar o consultas de muestra que el artículo intenta responder.

Usa Cloud Storage

Si el contenido no es público, se recomienda almacenarlo en Cloud Storage. Cuando creas documentos de conocimiento, proporcionas las URL para tus objetos de Cloud Storage.

Crea depósitos y objetos de Cloud Storage

Haz lo siguiente cuando crees un bucket de Cloud Storage:

  • Asegúrate de seleccionar el proyecto de GCP que usas para Dialogflow.
  • Asegúrate de que la cuenta de usuario o la cuenta de servicio que usas con normalidad para acceder a la API de Dialogflow tenga permisos de lectura para los objetos del bucket.
  • Usa la clase Standard Storage.
  • Como ubicación de depósito, selecciona la opción más cercana a la ubicación en la que te encuentres. Necesitarás el ID de ubicación (por ejemplo, us-west1) para algunas llamadas a la API, así que toma nota de tu elección.

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

Proporciona un objeto de Cloud Storage a un documento de la base de conocimiento

Sigue estas instrucciones para proporcionar tu contenido:

  • Crea una base de conocimiento como se describió anteriormente.
  • Crea un documento de conocimiento como se describió anteriormente. Cuando llames al método create en el tipo Document, establece el campo contentUri en la URL de tu documento de Cloud Storage. El formato de la URL es gs://bucket-name/object-name.
Anterior
Gestionar los intents con la API
Siguiente
Actualizar datos con una FieldMask