Conectores de conocimiento

Beta

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Los conectores de conocimiento complementan los intents definidos. Analizan documentos de conocimiento (por ejemplo, preguntas frecuentes o artículos) para encontrar respuestas automáticas. Para configurarlos, debes definir una o más bases de conocimiento, que son colecciones de documentos de conocimiento.

Puedes habilitar las bases de conocimiento para tu agente, de modo que todas las solicitudes de detección de intents puedan buscar respuestas automáticas mediante las bases de conocimiento. También puedes especificar una o más bases de conocimiento en las solicitudes de detección de intents individuales.

Es común que un agente que usa conectores de conocimiento también use intents definidos. Los conectores de conocimiento ofrecen menos control y precisión de respuesta que los intents. Debes definir los intents para que controlen solicitudes de usuario complejas y permitir que los conectores de conocimiento controlen las solicitudes simples.

Para obtener una lista de los idiomas compatibles, consulta la columna Conectores de conocimiento en la referencia de idiomas.

Limitaciones

La función de conectores de conocimiento solo está disponible para la región global.

Habilita las funciones Beta

Asegúrate de que las funciones beta estén habilitadas:

1. Ve a la consola de Dialogflow ES.
2. Selecciona un agente.
3. Haz clic en el botón de configuración () que se encuentra junto al nombre del agente.
4. Desplázate hacia abajo en la pestaña General y asegúrate de que la opción Funciones Beta esté habilitada.
5. Si realizaste cambios, haz clic en Guardar.

Crea una base y un documento de conocimiento

Sigue las instrucciones del instructivo de las bases de conocimiento para crear una base y un documento de conocimiento.

Configuración para conectores de conocimiento

Precaución: Por el momento, la configuración del conector de conocimiento no se incluye cuando exportas, importas o restableces agentes.

Puedes habilitar o inhabilitar las bases de conocimiento para tu agente. Las bases de conocimiento habilitadas se considerarán para todas las solicitudes de coincidencia de intents que no especifiquen bases de conocimiento. Para habilitar o inhabilitar las bases de conocimiento, sigue estos pasos:

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. Selecciona una o más bases de conocimiento de la lista.
5. Haz clic en Habilitar o Inhabilitar.

Cuando una expresión del usuario final también coincida con un intent, puedes especificar el grado de confianza de los resultados de conocimiento:

1. Desplázate hacia abajo hasta la sección Ajusta la preferencia de los resultados de conocimiento.
2. Ajusta el control deslizante desde el más débil (se le da preferencia al intent) hasta el más fuerte (se le da preferencia al conocimiento). Para obtener más información, consulta la sección Respuestas de detección de intent, que se encuentra a continuación.

Configura respuestas

De forma predeterminada, una base de conocimiento se configura con una sola respuesta de texto predeterminada que se completa con la respuesta de conocimiento de mayor coincidencia. Puedes cambiar esta respuesta y agregar mensajes de respuesta enriquecida. Las respuestas de conocimiento pueden contener hasta tres respuestas por base de conocimiento, y puedes hacer referencia a estas respuestas en tus respuestas configuradas. Para agregar respuestas, haz lo siguiente:

1. En la página Conocimiento, haz clic en el nombre de tu base de conocimiento.
2. Desplázate hacia abajo hasta la sección Respuestas y agrega las respuestas que desees:
   1. Cuando definas la primera respuesta, usa $Knowledge.Question[1] y $Knowledge.Answer[1] en los lugares en los que deben proporcionarse la pregunta y la respuesta.
   2. El índice para $Knowledge.Question y $Knowledge.Answer comienza en 1, por lo que debes aumentar este índice cuando agregues más respuestas.
3. Cuando termines de editar, haz clic en Guardar.

Cuando definas respuestas, debes considerar estos puntos:

• Si la cantidad de respuestas definidas es mayor que el número N de coincidencias de respuestas del conector de conocimiento, solo se mostrarán N respuestas.
• Dado que la precisión podría ser inferior a si se asociaran los intents definidos de forma explícita, recomendamos que muestres tres respuestas a los usuarios cuando sea posible.

Precaución: El comportamiento actual cuando se definen múltiples variantes de respuesta es un problema conocido. Una vez que se corrigió, el comportamiento será el siguiente:

• Si hay múltiples variantes de respuesta definidas dentro de un solo cuadro de Respuesta de texto o Respuesta simple del Asistente de Google, Dialogflow selecciona una al azar.
• Si hay múltiples cuadros de respuesta enriquecida definidos, Dialogflow selecciona una variante de respuesta de cada cuadro.

Ejemplo:

Detecta el intent con la base de conocimiento

Cuando realizas una solicitud de detección de intent, puedes especificar una o más bases de conocimiento para una respuesta posible. El suministro explícito de bases de conocimiento en una solicitud anula la configuración de las bases de conocimiento habilitadas o inhabilitadas.

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 detectar intents. Para usar la API, realiza una llamada al método detectIntent en el tipo Sessions.

IU web

Puedes interactuar con el agente y recibir respuestas del conector de conocimiento a través del simulador de Dialogflow:

1. Sigue los pasos anteriores para habilitar una base de conocimiento.
2. Sigue los pasos anteriores para definir respuestas.
3. Escribe “¿Cómo me registro?” en el simulador.

REST

Llama al método detectIntent en el tipo Sessions y especifica la base de conocimiento en el campo queryParams.

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 la base de conocimiento.

Método HTTP y URL:

POST https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent

Cuerpo JSON de la solicitud:

{
 "queryInput": {
   "text": {
     "text": "How do I sign up?",
     "languageCode": "en-US"
   }
 },
 "queryParams": {
   "knowledgeBaseNames": ["projects/PROJECT_ID/knowledgeBases/KNOWLEDGE_BASE_ID"]
 }
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent"

PowerShell (Windows)

Nota: En el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dialogflow.googleapis.com/v2beta1/projects/PROJECT_ID/agent/sessions/123456789:detectIntent" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de APIs se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

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

{
  ...
  "queryResult": {
    "queryText": "How do I sign up?",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
    "intent": {
      "name": "projects/my-gcp-project/agent/intents/487c7242-a769-408a-a339-47b95e10dac4",
      "displayName": "Knowledge.KnowledgeBase.MzkzNTAyMDE3NDQxNDk3MDg4MA"
    },
    "intentDetectionConfidence": 0.99371547,
    "languageCode": "en-us",
    "knowledgeAnswers": {
      "answers": [
        {
          "answer": "Sign up for Cloud Storage by turning on the Cloud Storage service in the Google Cloud Platform Console.",
          "matchConfidenceLevel": "HIGH",
          "matchConfidence": 0.99371547
        },
        {
          "answer": "Certain types of content are not allowed on this service; please refer to the Terms of Services and Platform Policies for details. If you believe a piece of content is in violation of our policies, report it here (select See more products, then Google Cloud Storage and Cloud Bigtable).",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0012244871
        },
        {
          "answer": "From the Cloud Storage documentation click \"Send feedback\" near the top right of the page. This will open a feedback form. Your comments will be reviewed by the Cloud Storage team.",
          "matchConfidenceLevel": "LOW",
          "matchConfidence": 0.0011537358
        }
      ]
    }
  }
}

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.v2beta1.DetectIntentRequest;
import com.google.cloud.dialogflow.v2beta1.DetectIntentResponse;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers;
import com.google.cloud.dialogflow.v2beta1.KnowledgeAnswers.Answer;
import com.google.cloud.dialogflow.v2beta1.QueryInput;
import com.google.cloud.dialogflow.v2beta1.QueryParameters;
import com.google.cloud.dialogflow.v2beta1.QueryResult;
import com.google.cloud.dialogflow.v2beta1.SessionName;
import com.google.cloud.dialogflow.v2beta1.SessionsClient;
import com.google.cloud.dialogflow.v2beta1.TextInput;
import com.google.common.collect.Maps;
import java.io.IOException;
import java.util.List;
import java.util.Map;

public class DetectIntentKnowledge {

  // DialogFlow API Detect Intent sample with querying knowledge connector.
  public static Map<String, KnowledgeAnswers> detectIntentKnowledge(
      String projectId,
      String knowledgeBaseName,
      String sessionId,
      String languageCode,
      List<String> texts)
      throws IOException, ApiException {
    // Instantiates a client
    Map<String, KnowledgeAnswers> allKnowledgeAnswers = Maps.newHashMap();
    try (SessionsClient sessionsClient = SessionsClient.create()) {
      // Set the session name using the sessionId (UUID) and projectID (my-project-id)
      SessionName session = SessionName.of(projectId, sessionId);
      System.out.println("Session Path: " + session.toString());

      // Detect intents for each text input
      for (String text : texts) {
        // Set the text and language code (en-US) for the query
        TextInput.Builder textInput =
            TextInput.newBuilder().setText(text).setLanguageCode(languageCode);
        // Build the query with the TextInput
        QueryInput queryInput = QueryInput.newBuilder().setText(textInput).build();

        QueryParameters queryParameters =
            QueryParameters.newBuilder().addKnowledgeBaseNames(knowledgeBaseName).build();

        DetectIntentRequest detectIntentRequest =
            DetectIntentRequest.newBuilder()
                .setSession(session.toString())
                .setQueryInput(queryInput)
                .setQueryParams(queryParameters)
                .build();
        // Performs the detect intent request
        DetectIntentResponse response = sessionsClient.detectIntent(detectIntentRequest);

        // Display the query result
        QueryResult queryResult = response.getQueryResult();

        System.out.format("Knowledge results:\n");
        System.out.format("====================\n");
        System.out.format("Query Text: '%s'\n", queryResult.getQueryText());
        System.out.format(
            "Detected Intent: %s (confidence: %f)\n",
            queryResult.getIntent().getDisplayName(), queryResult.getIntentDetectionConfidence());
        System.out.format(
            "Fulfillment Text: '%s'\n",
            queryResult.getFulfillmentMessagesCount() > 0
                ? queryResult.getFulfillmentMessages(0).getText()
                : "Triggered Default Fallback Intent");
        KnowledgeAnswers knowledgeAnswers = queryResult.getKnowledgeAnswers();
        for (Answer answer : knowledgeAnswers.getAnswersList()) {
          System.out.format(" - Answer: '%s'\n", answer.getAnswer());
          System.out.format(" - Confidence: '%s'\n", answer.getMatchConfidence());
        }

        KnowledgeAnswers answers = queryResult.getKnowledgeAnswers();
        allKnowledgeAnswers.put(text, answers);
      }
    }
    return allKnowledgeAnswers;
  }
}

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 sessionClient = new dialogflow.SessionsClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'ID of GCP project associated with your Dialogflow agent';
// const sessionId = `user specific ID of session, e.g. 12345`;
// const languageCode = 'BCP-47 language code, e.g. en-US';
// const knowledgeBaseId = `the ID of your KnowledgeBase`;
// const query = `phrase(s) to pass to detect, e.g. I'd like to reserve a room for six people`;

// Define session path
const sessionPath = sessionClient.projectAgentSessionPath(
  projectId,
  sessionId
);
const knowledgeBasePath =
  'projects/' + projectId + '/knowledgeBases/' + knowledgeBaseId + '';

// The audio query request
const request = {
  session: sessionPath,
  queryInput: {
    text: {
      text: query,
      languageCode: languageCode,
    },
  },
  queryParams: {
    knowledgeBaseNames: [knowledgeBasePath],
  },
};

const responses = await sessionClient.detectIntent(request);
const result = responses[0].queryResult;
console.log(`Query text: ${result.queryText}`);
console.log(`Detected Intent: ${result.intent.displayName}`);
console.log(`Confidence: ${result.intentDetectionConfidence}`);
console.log(`Query Result: ${result.fulfillmentText}`);
if (result.knowledgeAnswers && result.knowledgeAnswers.answers) {
  const answers = result.knowledgeAnswers.answers;
  console.log(`There are ${answers.length} answer(s);`);
  answers.forEach(a => {
    console.log(`   answer: ${a.answer}`);
    console.log(`   confidence: ${a.matchConfidence}`);
    console.log(`   match confidence level: ${a.matchConfidenceLevel}`);
  });
}

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 detect_intent_knowledge(
    project_id, session_id, language_code, knowledge_base_id, texts
):
    """Returns the result of detect intent with querying Knowledge Connector.

    Args:
    project_id: The GCP project linked with the agent you are going to query.
    session_id: Id of the session, using the same `session_id` between requests
              allows continuation of the conversation.
    language_code: Language of the queries.
    knowledge_base_id: The Knowledge base's id to query against.
    texts: A list of text queries to send.
    """
    from google.cloud import dialogflow_v2beta1 as dialogflow

    session_client = dialogflow.SessionsClient()

    session_path = session_client.session_path(project_id, session_id)
    print("Session path: {}\n".format(session_path))

    for text in texts:
        text_input = dialogflow.TextInput(text=text, language_code=language_code)

        query_input = dialogflow.QueryInput(text=text_input)

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

        query_params = dialogflow.QueryParameters(
            knowledge_base_names=[knowledge_base_path]
        )

        request = dialogflow.DetectIntentRequest(
            session=session_path, query_input=query_input, query_params=query_params
        )
        response = session_client.detect_intent(request=request)

        print("=" * 20)
        print("Query text: {}".format(response.query_result.query_text))
        print(
            "Detected intent: {} (confidence: {})\n".format(
                response.query_result.intent.display_name,
                response.query_result.intent_detection_confidence,
            )
        )
        print("Fulfillment text: {}\n".format(response.query_result.fulfillment_text))
        print("Knowledge results:")
        knowledge_answers = response.query_result.knowledge_answers
        for answers in knowledge_answers.answers:
            print(" - Answer: {}".format(answers.answer))
            print(" - Confidence: {}".format(answers.match_confidence))

Respuestas de detección de intent

La respuesta para el método Sessions tipo detectIntent es un DetectIntentResponse. Varios factores afectan cómo se propagan los campos de respuesta.

Si un intent definido y una base de conocimiento son coincidencias posibles, la confianza de la coincidencia de cada uno y las preferencias de resultados de conocimiento (consulta la sección Configuración para conectores de conocimiento) se usan a fin de determinar qué coincidencia es la seleccionada. La coincidencia seleccionada se propaga en el campo DetectIntentResponse.queryResult, y otras coincidencias potenciales se propagan en el campo DetectIntentResponse.alternativeQueryResults. Ambos campos contienen mensajes QueryResult.

Si una base de conocimiento proporciona una coincidencia posible, sucede lo siguiente:

• QueryResult.knowledgeAnswers se propaga con una lista de posibles respuestas de conocimiento ordenadas de mayor a menor según la confianza de la coincidencia.
• Si se definieron respuestas enriquecidas para la base de conocimiento, QueryResult.fulfillmentMessages se propaga con mensajes de respuesta enriquecida.

Cuando se realiza una solicitud de detección de intents, es posible que falle la consulta de conocimiento. Cuando esto suceda, se seleccionarán los intents definidos, por lo que la solicitud de detección de intent general no fallará. Puedes encontrar información sobre el error de consulta de conocimiento en el campo DetectIntentResponse.alternativeQueryResults[i].diagnosticInfo.

Administra bases de conocimiento

Para obtener más información sobre la administración de bases de conocimiento, consulta Administra bases de conocimiento.