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

Puedes influir en los resultados de la búsqueda que se recuperan de las herramientas de almacén de datos de Dialogflow CX configurando las especificaciones de aumento y filtro. Esto te permite tener 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 en función del 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 impulsar los documentos relacionados con los teléfonos celulares cuando respondas una consulta general más adelante en la conversación, como "¿Cómo reviso mi buzón 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

Para configurar los resultados de la búsqueda, usa los campos especificación de aumento (BoostSpec) y especificación de filtro (FilterSpec) en un objeto SearchConfig. Estos parámetros de configuración se aplican por almacén de datos dentro de la herramienta, lo que te permite controlar cómo se comporta cada almacén de datos conectado.

Puedes configurar las condiciones de búsqueda de una de las siguientes dos maneras: con la consola o enviando una llamada a la API directa.

Existen diferencias importantes entre ambas:

• Llamada a la API: Envías BoostSpec y FilterSpec en un SearchConfig con una llamada a la API de DetectIntent. Debes proporcionar un objeto SearchConfig completo en la solicitud. Un SearchConfig que se envía a través de una llamada a la API directa siempre anula un SearchConfig que se envía con la consola. No se admiten las expresiones dinámicas ni las referencias de parámetros.

• Consola: La consola usa tus parámetros de configuración de BoostSpec y FilterSpec para construir un objeto SearchConfig que envía con la solicitud de búsqueda. De manera opcional, puedes incluir referencias de parámetros y expresiones dinámicas para adaptar los resultados a los datos de contexto registrados de 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 en detectIntentRequest. No hay un esquema esperado, por lo que puedes definir las propiedades del objeto.

Mejorar especificaciones (Boost specs)

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

Ingresa cada especificación de aumento como una cadena JSON que representa un solo objeto ConditionBoostSpec.

Campos clave:

• condition: (cadena) Es una expresión que especifica cuándo se debe aplicar la mejora. Esto usa la sintaxis de expresión de filtro estándar. Puedes usar expresiones de Dialogflow CX 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 fuerza de la mejora.
  • Un valor positivo promueve los documentos que coinciden. Un valor de 1.0 otorga una promoción sólida.
  • Un valor negativo disminuye la clasificación de los documentos que coinciden. Un valor de -1.0 genera un descenso de nivel fuerte.
  • Un valor de 0.0 no aplica ningún aumento y no está permitido.
• boostControlSpec: Proporciona más controles para una clasificación personalizada que la combinación básica de condición y aumento. 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, proporciona una lista de ConditionBoostSpecs en el siguiente formato:

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

Nota: En este ejemplo, los documentos con un URI que coincide con el valor del parámetro de sesión $session.params.doc_id se potencian con una intensidad de 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 aumento de rendimiento:

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

Nota: DATASTORE_ID es el nombre completo del almacén de datos: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
CONDITION debe seguir la sintaxis de expresión de filtro de Agent Search,
y el valor de aumento debe estar entre -1.0 y 1.0.

Especificaciones de filtro (especificaciones de filtro)

Las especificaciones de filtro restringen los resultados de la búsqueda para que solo incluyan documentos que coincidan con los criterios definidos. Puedes agregar varias especificaciones de filtro 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 CX 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 que o igual al valor de $session.params.min_value y en los que stock_availability es "IN_STOCK":

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

Ejemplo de configuración de filtro de API:

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

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

Nota: DATASTORE_ID es el nombre completo del almacén de datos: projects/your_project_id/locations/your_location/collections/your_collection_name/dataStores/your_datastore_name,
y CONDITION deben seguir la sintaxis de expresión de filtro de Agent Search.

Expresiones dinámicas de Dialogflow CX

Nota: Las expresiones dinámicas solo están disponibles para las herramientas de almacén de datos. No están disponibles para los controladores de almacenes de datos.

Tanto las condiciones BoostSpec como las cadenas FilterSpec pueden incorporar expresiones de Dialogflow CX para que sean dinámicas. Esto te permite adaptar el comportamiento de la búsqueda según los datos de contexto 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 de 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 esté incluido en el QueryParameters de tus llamadas a DetectIntent. Para obtener más información, consulta endUserMetadata.

Para obtener más información 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 entorno de ejecución

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

1. Evalúa las cadenas JSON que proporcionaste para las especificaciones de potenciación. Cada cadena JSON válida se convierte en un objeto ConditionBoostSpec. Luego, se agrupan en un objeto BoostSpecs para la conexión del almacén de datos específico, que se agrega al SearchConfig general.
2. Evalúa las cadenas que proporcionaste para las especificaciones de filtro como expresiones de Dialogflow CX. Cada cadena de filtro resultante se usa para crear un objeto FilterSpecs para el almacén de datos, que también se agrega al SearchConfig.
3. Incluye este SearchConfig construido de forma dinámica en el QueryParameters de la solicitud de búsqueda enviada al almacén de datos.

Configura las condiciones de búsqueda

Para configurar las condiciones de búsqueda, asegúrate de haber completado los siguientes requisitos previos:

• Un agente de Dialogflow CX existente.
• 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 Agentes conversacionales y elige un proyecto deGoogle 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 mejora y 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 Especificaciones de Boost para obtener más detalles.
   • Para una especificación de filtro, proporciona una cadena que defina los criterios de filtro. Consulta Especificaciones de 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 de almacén de datos para guardar los cambios.

Configuración de API

Puedes proporcionar datos de configuración de búsqueda a Dialogflow CX cuando envías solicitudes de detección de intents. Debes proporcionar esta información en cada solicitud de intent de detección, ya que no se conserva en la sesión.

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

Ir a la referencia de la API de sesión

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

Cerrar

Configuración de Dialogflow CX Messenger

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

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

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

Para obtener más información, consulta el método setQueryParameters.

Soluciona problemas

Las siguientes soluciones abordan algunos problemas comunes que se encuentran durante la configuración. Prueba tus parámetros de configuración de forma exhaustiva 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 Boost Spec o una cadena de Filter Spec contiene una expresión de Dialogflow CX no válida (por ejemplo, una sintaxis incorrecta o una referencia a un parámetro inexistente), la compilación de la expresión fallará. Los errores relacionados con la compilación de expresiones suelen mostrarse en DetectIntentResponse, dentro del campo diagnostic_info, como SystemFunctionResults.

JSON de ConditionBoostSpec no válido

La consola de Agentes conversacionales realiza algunas validaciones en la cadena JSON ConditionBoostSpec cuando la guarda para verificar si es un JSON válido y si su estructura se puede 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 entorno de ejecución

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

Revisa el archivo SearchConfig compilado

El SearchConfig que se aplica cuando se ejecuta la consulta 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?

• Para obtener más información sobre la estructura de SearchConfig y sus componentes, consulta la documentación de search_config.
• Para obtener más información sobre la sintaxis de las expresiones, consulta la referencia de condiciones y funciones del sistema de Dialogflow CX.
• Para obtener más información sobre la sintaxis de las expresiones de filtro para la búsqueda, consulta Filtra y ordena los resultados.