Configuración de la búsqueda del almacén de datos

Puedes influir en los resultados de la búsqueda recuperados de las herramientas de almacén de datos de los agentes conversacionales (Dialogflow CX) configurando especificaciones de refuerzo y filtro. Esto permite interacciones más personalizadas y contextuales cuando tu agente usa un almacén de datos para encontrar información.

De manera opcional, puedes incluir expresiones dinámicas para ajustar los resultados según el contexto de la conversación. Por ejemplo, tu agente capturó información que indica que el usuario final tiene un "teléfono celular". Puedes configurar la herramienta de almacén de datos para potenciar los documentos relacionados con teléfonos celulares cuando respondas una búsqueda general más adelante en la conversación, como "¿Cómo reviso mi correo de voz?".

Puedes configurar los resultados de la búsqueda del almacén de datos con la consola, la API o la integración de Dialogflow CX Messenger.

Entradas de condiciones de búsqueda

Los resultados de la búsqueda se configuran con los campos especificación de refuerzo (BoostSpec) y especificación de filtro (FilterSpec) de un objeto SearchConfig. Estos parámetros de configuración se aplican por almacén de datos dentro de la herramienta, lo que te brinda un control detallado sobre el comportamiento de cada almacén de datos conectado.

Puedes configurar las condiciones de búsqueda de dos maneras: con la consola o con una llamada directa a la API. Existen diferencias importantes entre ambos.

  • Llamada a la API: BoostSpec y FilterSpec se envían en un SearchConfig con una llamada a la API de DetectIntent. Se debe proporcionar un objeto SearchConfig completo en la solicitud. Un SearchConfig enviado por una llamada directa a la API siempre anula un SearchConfig enviado con la consola. No se admiten las expresiones dinámicas ni las referencias a parámetros.

  • Consola: Tus configuraciones de BoostSpec y FilterSpec se usan para construir un objeto SearchConfig que se envía con la solicitud de búsqueda. De manera opcional, puedes incluir referencias a parámetros y expresiones dinámicas para adaptar los resultados a los datos de contexto registrados en la conversación. Solo debes proporcionar objetos ConditionBoostSpec y una lista de cadenas de filtro para construir FilterSpecs en lugar de un objeto SearchConfig completo.

La información del usuario final se proporciona como JSON. No hay un esquema esperado, por lo que puedes definir las propiedades del objeto.

Especificaciones de refuerzo (especificaciones de refuerzo)

Las especificaciones de refuerzo te permiten cambiar la clasificación de los resultados de la búsqueda aplicando un valor de refuerzo a documentos específicos. Puedes agregar varias especificaciones de refuerzo a un solo almacén de datos.

Cada especificación de refuerzo se ingresa como una cadena JSON. Esta cadena JSON debe representar un solo objeto ConditionBoostSpec.

Campos clave:

  • condition: (cadena) Es una expresión que especifica cuándo se debe aplicar el refuerzo. Esto usa la sintaxis de expresión de filtro estándar. Puedes usar expresiones de Dialogflow para que los resultados sean dinámicos, como $session.params.YOUR_PARAM_NAME o $request.end-user-metadata.YOUR_KEY.
  • boost: (Número) Es un valor entre -1.0 y 1.0 que determina la intensidad del aumento.
    • Un valor positivo promueve la coincidencia de documentos. Un valor de 1.0 otorga una promoción sólida.
    • Un valor negativo reduce la clasificación de los documentos coincidentes. Un valor de -1.0 genera una reducción importante en la clasificación.
    • Un valor de 0.0 no aplica ninguna mejora y no se permite.
  • boostControlSpec: Proporciona más controles para una clasificación personalizada que la combinación básica de condición y refuerzo. Para obtener más información sobre cómo configurar este campo, consulta la documentación de referencia.

Ejemplo de entrada de la consola:

Si configuras tu agente en la consola, debes proporcionar una lista de ConditionBoostSpecs en el siguiente formato.

En este ejemplo, los documentos con un URI que coincida con el valor del parámetro de sesión $session.params.doc_id se potenciarán con una intensidad de 0.5. JSON con este formato

{
  "condition": "uri: ANY(\"http://www.example.com/docs/$session.params.doc_id\")",
  "boost": 0.5
}

Ejemplo de entrada de la API:

Si llamas a la API directamente, debes proporcionar ConditionBoostSpecs en un objeto SearchConfig completo.La siguiente configuración de búsqueda describe una especificación de refuerzo:

"searchConfig": {
  "boostSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "spec": [
        {
          "conditionBoostSpecs": {
            "condition": "CONDITION",
            "boost": "1.0"
          }
        }
      ]
    }
  ]
}

Especificaciones de filtros

Las especificaciones de filtro restringen los resultados de la búsqueda para que solo incluyan los documentos que coinciden con los criterios definidos. Puedes agregar varias especificaciones de filtros a un solo almacén de datos.

Cada especificación de filtro se debe ingresar como una expresión de cadena. La cadena debe cumplir con la sintaxis de expresión de filtro estándar. Puedes usar expresiones de Dialogflow dentro de esta cadena para que los resultados sean dinámicos, como $session.params.YOUR_PARAM_NAME o $request.end-user-metadata.YOUR_KEY.

Ejemplo de cadena de especificación de filtro de la consola:

Si configuras tu agente con la consola, debes proporcionar una lista de cadenas filter para formar un objeto FilterSpec.

En este ejemplo, el filtro solo devuelve documentos con numeric_field mayor o igual que el valor de $session.params.min_value Y donde stock_availability es "IN_STOCK".

"numeric_field >= $session.params.min_value AND stock_availability: ANY(\"IN_STOCK\")"

Ejemplo de configuración del filtro de la API:

Si llamas a la API directamente, debes proporcionar cadenas filter en un objeto SearchConfig completo:

"searchConfig": {
  "filterSpecs": [
    {
      "dataStores": [ "DATASTORE_ID" ],
      "filter": "CONDITION"
    }
  ]
}

Expresiones dinámicas de Dialogflow

Tanto las condiciones BoostSpec como las cadenas FilterSpec pueden incorporar expresiones de Dialogflow para que sean dinámicas. Esto te permite personalizar el comportamiento de búsqueda en función de los datos contextuales recuperados de una conversación en curso. Las expresiones dinámicas no se admiten en las llamadas directas a la API y solo se pueden usar si realizas la configuración con la consola.

Puedes acceder a los datos del contexto de la conversación de dos maneras:

  • Parámetros de sesión: Son los valores recopilados durante la conversación con $session.params.YOUR_PARAMETER_ID.
  • Metadatos del usuario final: Son los metadatos sobre el usuario final que se pasan en DetectIntentRequest con $request.end-user-metadata.YOUR_KEY. Para que esta opción esté disponible, verifica que end_user_metadata se incluya en el QueryParameters de tus llamadas a DetectIntent. Para obtener más información, consulta endUserMetadata.

Para obtener más detalles sobre las funciones del sistema y la sintaxis de las expresiones disponibles, consulta la referencia de condiciones y funciones del sistema.

Condiciones de búsqueda aplicadas en el tiempo de ejecución

Cuando tu herramienta de almacén de datos ejecuta una búsqueda, sucede lo siguiente:

  1. Se evalúan las cadenas JSON que proporcionaste para las especificaciones de refuerzo. Cada cadena JSON válida se convierte en un objeto ConditionBoostSpec. Luego, se agrupan en un objeto BoostSpecs para la conexión específica del almacén de datos, que se agrega al objeto SearchConfig general.
  2. Las cadenas que proporcionaste para las especificaciones de filtro se evalúan como expresiones de Dialogflow. Cada cadena de filtro resultante se usa para crear un objeto FilterSpecs para el almacén de datos, que también se agrega a SearchConfig.
  3. Este SearchConfig construido de forma dinámica se incluye luego en el QueryParameters de la solicitud de búsqueda que se envía al almacén de datos.

Configura las condiciones de búsqueda

Antes de configurar las condiciones de búsqueda, verifica que tengas lo siguiente:

  • Un agente existente de Conversational Agents (Dialogflow CX)
  • Una herramienta de almacén de datos configurada para tu agente con uno o más almacenes de datos habilitados

Configuración mediante Console

  1. Abre la consola de Conversational Agents y elige un proyecto de Google Cloud.
  2. Selecciona un agente en el menú desplegable.
  3. Navega al menú de la izquierda y haz clic en Herramientas. Selecciona la herramienta de almacén de datos que deseas configurar.
  4. En la página de edición de la herramienta, navega a la sección Almacenes de datos. Haz clic en el ícono de Configuración (⚙️) junto al almacén de datos que deseas modificar.
  5. Aparecerá el menú Configurar almacén de datos. Aquí puedes agregar especificaciones de refuerzo y especificaciones de filtro para modificar los resultados de la búsqueda.
    • Para una especificación de aumento, proporciona un objeto JSON que defina un ConditionBoostSpec. Consulta las Especificaciones de refuerzo para obtener más detalles.
    • Para un Filter Spec, proporciona una cadena que defina los criterios del filtro. Consulta Especificaciones de los filtros para obtener más detalles.
  6. Después de agregar y configurar tus especificaciones, haz clic en Confirmar en la parte inferior del panel lateral.
  7. Haz clic en Guardar en la página de edición de la herramienta del almacén de datos para guardar los cambios.

Configuración de API

Puedes proporcionar datos de configuración de búsqueda a los agentes conversacionales (Dialogflow CX) cuando envías solicitudes de detección de intención. Esta información se debe proporcionar en cada solicitud de detección de intención, ya que no se conserva en la sesión.

Proporciona esta información en el campo queryParams.searchConfig del método Sessions.detectIntent.

Selecciona un protocolo y una versión para la referencia de sesión:

Protocolo V3 V3beta1
REST Recurso de sesión Recurso de sesión
RPC Interfaz de sesión Interfaz de sesión
C++ SessionsClient No disponible
C# SessionsClient No disponible
Go SessionsClient No disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP No disponible No disponible
Python SessionsClient SessionsClient
Ruby No disponible No disponible

Configuración de Dialogflow CX Messenger

Puedes proporcionar datos de configuración de búsqueda a la integración de Dialogflow CX Messenger. Consulta el método setContext para obtener más información.

Para aplicar una especificación o configuración de búsqueda, se debe agregar el siguiente fragmento al código de Dialogflow CX Messenger cuando se incorpora en un sitio web:

<script>
  document.addEventListener('df-messenger-loaded', () => {
    const dfMessenger = document.querySelector('df-messenger');
    const searchConfig = { ... }
    dfMessenger.setQueryParameters(searchConfig);
  });
</script>

Consulta el método setQueryParameters.

Soluciona problemas

En esta sección, se describen las soluciones a algunos problemas comunes que se producen durante la configuración. Siempre prueba tus configuraciones a fondo simulando conversaciones que activen diferentes parámetros de sesión y valores de metadatos del usuario final.

Expresiones no válidas

Si una condición de especificación de refuerzo o una cadena de especificación de filtro contiene una expresión no válida de agentes conversacionales (Dialogflow CX) (por ejemplo, sintaxis incorrecta o referencia a un parámetro inexistente), fallará la compilación de la expresión. Los errores relacionados con la compilación de expresiones suelen devolverse en DetectIntentResponse dentro del campo diagnostic_info como SystemFunctionResults.

JSON de ConditionBoostSpec no válido

La consola de Conversational Agents realiza cierta validación en la cadena JSON de ConditionBoostSpec cuando la guarda. Esto es para verificar que sea un JSON válido y que su estructura se pueda asignar a un objeto ConditionBoostSpec. Si el JSON es válido, pero genera un SearchConfig no válido según el servicio de búsqueda subyacente (por ejemplo, una cadena de condición no válida después de la sustitución de parámetros), el servicio de búsqueda devolverá un error.

Errores de sustitución en el tiempo de ejecución

Si una cadena JSON de ConditionBoostSpec es válida y se puede analizar, pero se produce un error durante la sustitución en el tiempo de ejecución de las expresiones de Dialogflow dentro de sus campos (como la cadena de condición), estos errores se informarán en diagnostic_info como SystemFunctionResults.

Revisa el SearchConfig compilado

El SearchConfig que se aplica cuando se ejecuta la búsqueda está disponible en search_signals en la respuesta. Revisar el SearchConfig puede proporcionar información sobre problemas adicionales que no se describen aquí.

¿Qué sigue?