Cómo filtrar recomendaciones

En esta página, se describe cómo filtrar los resultados de las recomendaciones con atributos de productos.

Puedes filtrar los resultados de la predicción si especificas una expresión de filtro en las solicitudes de predicción. La expresión de filtro es una expresión lógica que se evalúa para cada producto. La lista de productos en la respuesta se reduce a los productos en los que la expresión se evalúa como verdadera.

Existen dos versiones de filtrado para las recomendaciones:

• Se recomienda la versión 2.
• La versión 1 dejó de estar disponible, pero es posible que aún esté en uso.

Las secciones de esta guía solo se aplican a la versión 2 del filtrado, que filtra las recomendaciones con atributos de productos.

Filtrado de recomendaciones, versión 2

La versión 2 usa atributos de productos. Las expresiones de filtro se basan en atributos de productos. Estos pueden ser atributos del sistema predefinidos, como categories y colors, o atributos personalizados que definas, como attributes.styles. Cuando configuras un atributo de producto como filtrable, las recomendaciones pueden usar automáticamente esos atributos como etiquetas para filtrar las recomendaciones, en lugar de requerir que agregues etiquetas de filtro de forma manual.

Cuando usas atributos para filtrar productos, la respuesta de la predicción muestra productos principales que contienen al menos un producto principal o variante que tiene un valor de atributo que coincide con la expresión del filtro. Para obtener más información sobre los productos principales y las variantes, consulta Niveles de producto.

En el siguiente ejemplo de expresión de filtro, también se filtran los productos rojos o azules configurados como “Nuevos” y no como promocionales:

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

Para usar la versión 2 del filtrado de recomendaciones, sigue estos procedimientos. Cada procedimiento se indica más adelante en esta página.

1. Activa el filtrado de recomendaciones para un modelo que publicará recomendaciones filtradas.
2. Activa el filtrado de recomendaciones para los atributos de productos que deseas filtrar.
3. Usa atributos de productos filtrables en las solicitudes de predicción.

Filtrado de recomendaciones, versión 1 (obsoleto)

La versión 1 usa etiquetas de filtro creadas de forma manual. Las expresiones de filtro se basan en las etiquetas de filtro, que debes agregar de forma manual a los productos de tu catálogo que deseas filtrar.

En el siguiente ejemplo de expresión de filtro, se usan etiquetas de filtro para especificar productos etiquetados como “Rojo” o “Azul”, así como la etiqueta “Nuevos”, y que no están etiquetados como “Promocionales”:

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

Consulta la documentación de referencia de la API para el campo Product.tags[].

Las expresiones de etiqueta pueden contener los operadores booleanos OR o NOT, que deben estar separados de los valores de la etiqueta por uno o más espacios. También se puede anteponer un guion (-) a los valores de la etiqueta, lo que equivale al operador NOT. Las expresiones de etiqueta que usan los operadores booleanos deben estar entre paréntesis.

Además de las etiquetas, puedes filtrar por filterOutOfStockItems. La marca filterOutOfStockItems filtra cualquier producto con un stockState de OUT_OF_STOCK.

Puedes combinar los filtros de etiquetas y los filtros de productos agotados para que solo se muestren los elementos que satisfagan todas las expresiones de filtro especificadas.

Estas son algunas strings de filtro de ejemplo:

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

En el siguiente ejemplo, solo se muestran artículos que están en stock y que tienen la etiqueta spring-sale o exclusive (o ambas) y tampoco tienen la etiqueta items-to-exclude.

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

Compatibilidad del filtro de atributos y el filtro de etiquetas

Si un modelo tiene etiquetas creadas de forma manual y atributos de productos filtrables, puede entregar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es posible incluir expresiones de filtrado de v1 y de v2 en la misma solicitud de predicción.

Límites de filtrado de recomendaciones

Cada atributo filtrable consume cierta memoria en cada uno de tus modelos. Los siguientes límites ayudan a evitar efectos adversos en el rendimiento de la publicación:

• Puedes configurar hasta 10 atributos personalizados como filtros en tu catálogo.

• Tu catálogo puede tener hasta 100,000,000 de valores de atributos filtrables.

  Para estimar la cantidad total de valores de atributos en tu catálogo, debes multiplicar la cantidad de productos por la cantidad de atributos filtrables.

  Por ejemplo, si tienes un catálogo con 1,000 productos y 3 atributos configurados como filtrables, la cantidad total de valores de atributos se puede estimar como 3 × 1,000=3,000.

  Si usas el filtrado de recomendaciones de la versión 1 junto con la versión 2, la cantidad de etiquetas de filtro se considera en tu cuota. Asegúrate de que la cantidad de etiquetas de filtro que se agregan a la cantidad total de valores de atributos sea inferior a 100,000,000.

Si superas los límites, no podrás configurar atributos adicionales como filtrables. Si necesitas superar estos límites, solicita un aumento de la cuota.

La cantidad total de etiquetas se calcula durante el entrenamiento de modelos. Si la cantidad total supera el límite, el entrenamiento de modelos falla. Si se encuentran más de 10 atributos personalizados que se pueden filtrar durante el entrenamiento de modelos, solo se usan 10.

Sintaxis de la expresión de filtro de recomendaciones

Las sintaxis de las expresiones de filtro para la búsqueda y las recomendaciones son similares. Sin embargo, las recomendaciones tienen varias limitaciones.

La sintaxis de la expresión de filtro de recomendaciones se puede resumir con la siguiente EBNF:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  literal = double-quoted string;

  textual_field = see the tables below;

Restricciones de sintaxis de filtro

Se aplican las siguientes restricciones:

• La profundidad de incorporación de operadores AND y OR entre paréntesis es limitada. Las expresiones lógicas del filtro deben estar en formato disyuntivo normal (CNF). La expresión lógica más compleja que se admite puede ser una lista de cláusulas conectadas con AND que solo contenga operadores OR, como los siguientes: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• Las expresiones se pueden negar con la palabra clave NOT o con -. Esto solo funciona con expresiones ANY() con un solo argumento que no incluye atributos relacionados con el inventario.
• Las restricciones basadas en availability deben estar en el nivel superior. No se pueden usar como parte de una cláusula OR ni de una negación (NOT).
• Debido a que el filtrado de recomendaciones estándar solo admite campos de texto, las operaciones de menos que, mayor que y verificación de rango no son compatibles con el filtrado de recomendaciones estándar. Las operaciones de mayor que y menor que solo se pueden usar con condiciones de control de aumento o ocultación de recomendaciones, que admiten algunos campos numéricos (consulta Campos compatibles con el aumento o la ocultación).
• La cantidad máxima de términos en la cláusula AND de nivel superior es 20.
• Una cláusula OR puede tener hasta 100 argumentos que se incluyen en expresiones ANY(). Si una cláusula OR tiene varias expresiones ANY(), todos sus argumentos se consideran para este límite. Por ejemplo, colors: ANY("red", "green") OR colors: ANY("blue") tiene tres argumentos.

En la siguiente tabla, se muestran ejemplos de expresiones de filtro válidas, así como ejemplos no válidos y los motivos por los que no son válidos.

Filtrado de atributos relacionados con el inventario

El filtrado por atributos relacionados con el inventario se basa en el estado en tiempo real de tus productos. Para el filtrado de availability: ANY("IN_STOCK"), la respuesta de la predicción muestra productos principales en los que el producto principal o una variante tiene el valor coincidente de IN_STOCK. Para obtener más información sobre los productos principales y las variantes, consulta Niveles de producto. No admitimos el filtrado Primary only ni Variant only.

IN_STOCK es el único valor del atributo availability que admite la versión 2 del filtrado de recomendaciones.

Los atributos relacionados con el inventario se pueden usar en cláusulas AND, pero no en cláusulas OR.

Campos disponibles

Los campos de texto admitidos se resumen en la siguiente tabla.

La función para aumentar o ocultar recomendaciones admite campos adicionales que no son compatibles con el filtrado de recomendaciones estándar. Para obtener una lista de los campos adicionales que admiten la promoción o el ocultamiento para las recomendaciones, consulta Campos compatibles con la promoción o el ocultamiento.

Campos compatibles con la función para mejorar o ocultar

La función de aumento o ocultación admite algunos campos adicionales que no son compatibles con el filtrado de recomendaciones estándar, incluidos los campos numéricos.

Además de los campos que se enumeran en Campos admitidos, la función de aumento o ocultación para las recomendaciones admite los siguientes campos:

Campos de texto

Campos numéricos

Cómo configurar el filtrado de recomendaciones para un modelo

Puedes activar el filtrado de recomendaciones con la consola de Search for Retail o el recurso de la API de Models.

Desde la consola, puedes crear un modelo nuevo que tenga habilitado el filtrado de recomendaciones. También puedes actualizar esta opción para los modelos existentes.

Con el recurso de la API de Models, puedes crear un modelo nuevo con el filtrado de recomendaciones activado o actualizar este parámetro de configuración para un modelo existente con models.Patch.

Ten en cuenta que, si la configuración de publicación que muestra las predicciones tiene habilitada la coincidencia de categorías, el filtrado no funciona en el atributo "categories" porque la respuesta solo muestra resultados de productos que comparten una categoría con el producto de contexto.

Cómo configurar el filtrado de un modelo con la consola

En la consola de Search for Retail, selecciona la opción Auto generate tags durante la creación del modelo para permitir el filtrado de recomendaciones para ese modelo.

Vuelve a verificar la compatibilidad con otros parámetros de configuración, como diversity-level y category-match-level, etc., ya que los efectos totales se combinan y el filtrado se realiza al final.

• Por ejemplo, combinar diversity-level y category attribute filtering basados en reglas suele generar un resultado vacío.
  • diversity-level=high-diversity obliga al modelo a limitar los resultados máximos para las mismas cadenas de categorías. Es decir, 1 resultado para la categoría 1, 1 resultado para la categoría 2, etcétera.
  • El filtrado de atributos con metadatos de categoría (Product.categories = ANY ("category2")) hace que el modelo descarte los elementos que no coinciden.
  • El resultado final tiene menos de tres resultados.
• En el caso del modelo similar-items, ya contiene un aumento adicional de la relevancia de la categoría con el category-match-level = relaxed-category-match predeterminado. Cambia a category-match-level=no-category-match para inhabilitar el comportamiento y usar reglas de filtrado personalizadas.

Consulta Crea modelos de recomendaciones para obtener instrucciones sobre cómo crear un modelo de recomendaciones con la consola.

Este parámetro de configuración no se puede actualizar en la consola para los modelos existentes. Para actualizar este parámetro de configuración de un modelo, usa el método de la API models.Patch.

Configura el filtrado de un modelo con la API

Puedes activar el filtrado de recomendaciones para un modelo con models.Create cuando crees uno nuevo o con models.Patch cuando actualices uno existente.

Para permitir el filtrado, establece el campo filteringOption para tu modelo. Los valores permitidos para este campo son los siguientes:

• RECOMMENDATIONS_FILTERING_DISABLED (predeterminado): El filtrado está desactivado para el modelo.
• RECOMMENDATIONS_FILTERING_ENABLED: El filtrado está activado para los productos principales.

En el siguiente ejemplo de curl, se crea un modelo nuevo que tiene activado el filtrado de recomendaciones.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

En el siguiente ejemplo de curl, se actualiza la configuración de la opción de filtrado para un modelo existente.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

Configura los atributos para que se puedan filtrar

Para filtrar los productos recomendados, activa el filtrado de los atributos del producto que usarás en las expresiones de filtrado. Puedes actualizar este parámetro de configuración con la consola de Search for Retail o con el recurso de la API de Attributes.

No permitas que se filtren más atributos de los necesarios. Existe un límite para la cantidad de atributos filtrables.

Cómo establecer atributos que se puedan filtrar con la consola

Puedes establecer un atributo como filtro en la página Controles de la consola de Búsqueda para venta minorista.

1. Ve a la página Controles en la consola de Search for Retail.
   
   Ir a la página Controles

2. Ve a la pestaña Controles de atributos.

   En esta pestaña, se muestra una tabla de todos los atributos de producto para los que puedes establecer controles de todo el sitio.

3. Haz clic en editModificar controles.

4. Establece Filtrable en Verdadero para el atributo del producto.

5. Haz clic en Guardar controles.

Puedes comenzar a usar el atributo para filtrar después de que se complete el siguiente ciclo de entrenamiento de modelos.

Configura atributos como filtrables con la API

AttributesConfig representa una lista de atributos para un catálogo.

Establece el campo AttributesConfig.filteringOption para CatalogAttribute. Los valores permitidos para este campo son los siguientes:

• RECOMMENDATIONS_FILTERING_DISABLED (predeterminado): El filtrado está desactivado para el atributo.
• RECOMMENDATIONS_FILTERING_ENABLED: El filtrado está activado para el atributo.

En el siguiente ejemplo de curl, se consultan los atributos de tus productos existentes.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

En el siguiente ejemplo de curl, se establece el atributo del producto categories como filtrable.

Cuando actualices un atributo existente, conserva los valores originales del atributo para indexableOption, dynamicFacetableOption y searchableOption como aparecen en el paso anterior. Si el atributo que elegiste no apareció cuando viste attributesConfig como en el ejemplo anterior, usa la configuración predeterminada como se muestra en el siguiente ejemplo.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

Puedes comenzar a usar el atributo para filtrar después de que se complete el siguiente ciclo de entrenamiento de modelos. Por lo general, este proceso demora al menos ocho horas.

Usa atributos filtrables en una solicitud de predicción

Después de volver a entrenar el modelo, puedes usar atributos de productos que se pueden filtrar en tus solicitudes de predicción.

Establece el valor del parámetro de solicitud filterSyntaxV2 en verdadero para activar el filtrado de recomendaciones de la versión 2. Si no se establece el parámetro, el filtrado de la versión 1 permanecerá activo. Si un modelo tiene etiquetas creadas de forma manual y atributos de producto que se pueden filtrar, puede publicar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es posible incluir expresiones de filtrado v1 y v2 en la misma solicitud de predicción.

En el siguiente ejemplo parcial de curl, se muestra filterSyntaxV2 establecido como verdadero y una expresión de filtro que usa los atributos del producto colors y categories. En este ejemplo, se supone que colors y categories están configurados como filtrables.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

En el siguiente ejemplo de curl, se muestra una solicitud de predicción completa.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

Además de los filtros, el parámetro de configuración de diversificación de la configuración de publicación también puede afectar la cantidad de resultados que muestra la respuesta.