Filtrar recomendaciones

En esta página, se describen los resultados de filtrado de Recomendaciones IA mediante 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 limita a los productos en los que la expresión se evalúa como verdadera.

Existen dos versiones de filtrado para Recomendaciones IA:

  • Se recomienda la versión 2.
  • La versión 1 está obsoleta, pero es posible que todavía esté en uso.

Las secciones de esta guía práctica solo se aplican a la versión 2 del filtrado, que filtra las recomendaciones mediante atributos de producto.

Filtro de recomendaciones, versión 2

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

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

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

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

Si deseas usar la versión 2 del filtro para Recomendaciones IA, sigue estos procedimientos. Cada procedimiento se proporciona más adelante en esta página.

  1. Activa el filtro de recomendaciones para un modelo que entregará recomendaciones filtradas.
  2. Activa el filtrado de recomendaciones para los atributos de productos que planeas filtrar.
  3. Usa atributos de producto filtrables en solicitudes de predicción.

Filtro de recomendaciones, versión 1 (obsoleta)

La versión 1 usa etiquetas de filtro creadas de forma manual. Las expresiones de filtro se basan en etiquetas de filtro, que debes agregar de forma manual a cualquier producto de tu catálogo que planees 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 “Nueva llegada” y 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 filtros de etiquetas y filtros agotados para que solo se muestren elementos que cumplan con 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 los artículos que están en stock y que tienen la etiqueta spring-sale o exclusive (o ambos) y no tienen la etiqueta items-to-exclude.

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

Compatibilidad con el filtro de atributos y el filtro de etiquetas

Si un modelo tiene etiquetas creadas de forma manual y atributos de producto que se pueden filtrar, puede entregar solicitudes de predicción mediante cualquiera de las versiones de filtrado. Sin embargo, no es posible incluir el filtrado v1 y las expresiones de filtrado v2 en la misma solicitud de predicción.

Límites de filtrado de recomendaciones

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

  • Se pueden configurar hasta 10 atributos personalizados en su catálogo.
  • Puede haber hasta 100,000,000 de valores de atributos filtrables en tu catálogo.

    Para calcular la cantidad total de valores de atributos en tu catálogo, se debe multiplicar la cantidad de productos del catálogo por la cantidad de atributos que se pueden filtrar.

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

    Si usas recomendaciones de la versión 1 filtrando 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 agregaron a la cantidad total de valores de atributo sea inferior a 100,000,000.

Si excedes los límites, la API de Retail te impide establecer atributos adicionales como filtrables. Si necesitas exceder 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, falla el entrenamiento de modelos. Si se encuentran más de 10 atributos personalizados filtrables durante el entrenamiento de modelos, solo se usan 10.

Sintaxis de la expresión de filtro de Recomendaciones IA

Las sintaxis de expresiones de filtro para Retail Search y Recomendaciones IA son similares. Sin embargo, Recomendaciones IA tiene varias limitaciones.

La sintaxis de la expresión de filtro de Recomendaciones IA se puede resumir de la siguiente forma: 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 string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

Filtrar restricciones de sintaxis

Se aplican las siguientes restricciones:

  • La profundidad de la incorporación de operadores AND y OR entre paréntesis es limitada. Las expresiones lógicas en el filtro deben estar en formato normal conjuntivo (CNF). La expresión lógica compatible más compleja puede ser una lista conectada de AND de cláusulas que solo contengan operadores OR, como (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
  • Las expresiones pueden negarse 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 ser del nivel superior. No se pueden usar como parte de una cláusula OR o una negación (NOT).
  • Debido a que el filtrado de recomendaciones estándar solo admite campos de texto, no se admiten las operaciones de comprobación menor, mayor que o superior de rango para el filtrado de recomendaciones estándar. Las operaciones de tipo "menor que y superior a" se pueden usar solo con recomendaciones de condiciones de control por refuerzo y ocultar, que admiten algunos campos numéricos (consulta Campos admitidos para aumentar la potencia y ocultar).
  • 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 las expresiones ANY(). Si una cláusula OR tiene varias expresiones ANY(), todos sus argumentos se tienen en cuenta 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 lo son.

Expresión Válido Notas
colors: ANY("red", "green")
NOT colors: ANY("red")
NOT colors: ANY("red", green") No Negrita un `ANY()` con más de un argumento.
colors: ANY("red", "green") OR
categories: ANY(\"Phone > Android > Pixel\")
(colors: ANY("red") OR colors: ANY("green")) AND
categories: ANY(\"Phone > Android > Pixel\")
(colors: ANY("red") AND colors: ANY("green")) OR
categories: ANY(\"Phone > Android > Pixel\")
No No de forma conjuntiva normal.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")
(colors: ANY("red")) OR (availability: ANY("IN_STOCK")) No Combina availability en una expresión OR con otras condiciones.

Filtrado de atributos relacionados con el inventario

El filtrado de atributos relacionados con el inventario se basa en el estado en tiempo real de tus productos.

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

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

Campos disponibles

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

Boost/bury para Recomendaciones IA admite campos adicionales que no son compatibles con el filtrado de recomendaciones estándar. Si deseas obtener una lista de los campos adicionales compatibles con Boost/bury para Recomendaciones IA, consulta Campos compatibles con Boost/bury.

campo description
"productId" El ID del producto (el último segmento de Product.name).
“marcas” El atributo Product.Brands.
"categories" The Product.categories.
"genders" The Audience.genders.
"ageGroups" The Audience.age_groups.
"colorFamilies" El atributo ColorInfo.color_families.
"colors" The ColorInfo.colors.
"sizes" El atributo Product.sizes.
"materials" El atributo Product.materials.
"patterns" El atributo Product.patrones.
"conditions" El atributo Product.condition.
“attributes.key” El atributo personalizado textual en el objeto Product. La clave puede ser cualquier clave en el mapa Product.attributes, si los valores de atributos son textuales.

Campos admitidos Boost/bury

Boost/bury 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 enumerados en Campos compatibles, Boost/bury para obtener recomendaciones admite los siguientes campos:

Campos de texto

campo description
"etiquetas" Product.tags[] Etiquetas personalizadas asociadas al producto.

Campos numéricos

campo description
"price" PriceInfo.price: Es el precio del producto.
"discount" Es el descuento del producto. Este campo se calcula con los valores de precio y campo de precios originales de PriceInfo.
"rating" Product.rating Es la cantidad total de calificaciones del producto.
"ratingCount" rating.ratingCount Es la cantidad total de calificaciones del producto.

Configura el filtrado de recomendaciones para un modelo

Puedes activar el filtrado para Recomendaciones IA mediante la consola de venta minorista 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 filtro de recomendaciones activado o actualizar esta configuración para un modelo existente con models.Patch.

Ten en cuenta que, si la configuración de entrega que muestra predicciones tiene habilitada la coincidencia de categorías, el filtro no funcionará con el atributo "categories" porque la respuesta solo mostrará resultados de productos que compartan una categoría con el producto de contexto.

Configurar el filtrado para un modelo con la consola

En la consola de Retail, selecciona la opción Generar etiquetas automáticamente durante la creación del modelo a fin de permitir el filtrado de recomendaciones para ese modelo.

Consulta Crea modelos de recomendación para obtener instrucciones sobre cómo crear un modelo de recomendación mediante la consola.

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

Configura el filtrado para un modelo mediante la API

Puedes activar el filtro de recomendaciones para un modelo con models.Create cuando creas un modelo nuevo o con models.Patch cuando actualizas un modelo existente.

Para permitir el filtrado, configura el campo filteringOption de tu modelo. Los valores permitidos de 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 activados los filtros 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 las opciones de filtro de 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"

Establece los atributos como filtrados

Para filtrar productos recomendados, activa el filtrado de los atributos de productos que usarás en las expresiones de filtro. Puedes actualizar esta configuración con la consola de venta minorista o con el recurso de la API de Attributes.

No permita que se puedan filtrar más atributos de los necesarios. Existe un límite para la cantidad de atributos que se pueden filtrar.

Configure los atributos como filtros con la consola

Puedes establecer un atributo como la página Controles filtrable en la consola de Google Cloud.

  1. Ve a la página Controles de Retail en Google Cloud Console.

    Ir a la página Controles

  2. Vaya 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 Modificar controles.

  4. Configure Filterable como True 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.

Cómo configurar atributos con filtros mediante la API

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

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

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

En el siguiente ejemplo de curl, se consultan sus atributos de 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 configura el atributo de 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 aparece cuando ves attributesConfig, como en el ejemplo anterior, utiliza 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.

Usa atributos filtrables en una solicitud de predicción

Después de volver a entrenar el modelo, puedes usar atributos de producto filtrables en las solicitudes de predicción.

Establece el valor filterSyntaxV2 del parámetro de la solicitud en verdadero para activar el filtrado de recomendaciones de la versión 2. Si no se configura 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 entregar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es posible incluir las expresiones de filtrado de v1 y de filtrado de v2 en la misma solicitud de predicción.

En el siguiente ejemplo de curl parcial, se muestra filterSyntaxV2 configurado como verdadero y una expresión de filtro que usa los atributos de producto colors y categories. En este ejemplo, se supone que colors y categories se configuran 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\")',
        useMostRecentServingConfig: true
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

Además de los filtros, la configuración de diversificación de la configuración de entrega también puede afectar la cantidad de resultados que se muestran en la respuesta.