Filtrar recomendaciones

En esta página, se describe el filtrado de los resultados para las recomendaciones que usan atributos de productos.

Puedes especificar una expresión de filtro en las solicitudes de predicción para filtrar los resultados de la 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 productos en los que la expresión se evalúa como verdadera.

Nota: Las actualizaciones de expresiones de etiquetas pueden tardar hasta ocho horas en estar disponibles y usarlas para filtrar predicciones con v1 y v2, incluidos los parámetros de configuración de atributos para el filtrado y los cambios de metadatos a nivel del producto. Solo el campo Availability tiene actualizaciones en tiempo real.

Existen dos versiones de filtrado de 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 práctica solo se aplican a la versión 2 del filtrado, que filtra las recomendaciones con atributos de producto.

Filtrado de recomendaciones, versión 2

La versión 2 usa atributos de producto. Las expresiones de filtro se basan en 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, las recomendaciones pueden usar automáticamente esos atributos como etiquetas para el filtrado de 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 los productos principales que contienen al menos un producto principal o una variante con un valor de atributo que coincide con la expresión de filtro. Para obtener más información sobre los productos principales y las variantes, consulta Niveles de producto.

El siguiente ejemplo de expresión de filtro también filtra para cualquier producto rojo o azul configurado como “Nueva llegada” y no configurado como promocional:

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

Si quieres usar la versión 2 del filtrado para las recomendaciones, sigue estos procedimientos. Más adelante en esta página, se brinda cada procedimiento.

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

Filtrado 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”, además de la etiqueta “Nueva llegada”, y no se etiquetan como “promocional”:

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 todos los productos con un stockState de OUT_OF_STOCK.

Puedes combinar filtros de etiquetas y filtros agotados para que solo se muestren los elementos que satisfacen 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, se muestran solo los artículos en stock que tienen la etiqueta spring-sale o exclusive (o ambas), y que también no tienen la etiqueta items-to-exclude.

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

Compatibilidad con filtros de atributos y filtros de etiquetas

Si un modelo tiene etiquetas creadas de forma manual y atributos de producto filtrables, puede entregar 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.

Límites para el 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 publicación:

• En tu catálogo, se pueden configurar hasta 10 atributos personalizados para que se puedan filtrar.

• En tu catálogo, pueden haber hasta 100,000,000 valores de atributos filtrables.

  Para estimar la cantidad total de valores de atributos en tu catálogo, se puede multiplicar la cantidad de productos del catálogo 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 las recomendaciones de la versión 1 que filtran 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 agregadas 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 para que se puedan filtrar. 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, el entrenamiento de modelos falla. Si se encuentran más de 10 atributos personalizados filtrables durante el entrenamiento de modelos, solo se usan 10.

Sintaxis de expresiones de filtro de recomendaciones

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

La sintaxis de la expresión de filtro de recomendaciones se puede resumir con el 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;

Filtrar restricciones de sintaxis

Se aplican las siguientes restricciones:

• La profundidad de la incorporación de los operadores AND y OR entre paréntesis es limitada. Las expresiones lógicas del filtro deben estar en formato normal conjuntivo (CNF). La expresión lógica admitida más compleja puede ser una lista conectada con AND de cláusulas que solo contienen operadores OR, como (... 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 único 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 textuales, no se admiten las operaciones de menor que, mayor que y verificación de rango para el filtrado de recomendaciones estándar. Las operaciones menor que y mayor que se pueden usar solo con las recomendaciones de condiciones de control mejorar y ocultar, que admiten algunos campos numéricos (consulta Campos compatibles con el aumento y 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 incluidos 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")	Sí
NOT colors: ANY("red")	Sí
NOT colors: ANY("red", green")	No	Negara una `ANY()` con más de un argumento.
colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")	Sí
(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")	Sí
(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")	No	No en forma conjuntiva normal.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")	Sí
(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. Para el filtrado 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 se admiten los filtros Primary only ni Variant only.

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

En la siguiente tabla, se resumen los campos de texto admitidos.

La función mejorar y ocultar para las recomendaciones admite campos adicionales que el filtrado de recomendaciones estándar no admite. Si quieres obtener una lista de campos adicionales compatibles con las mejoras y las opiniones para las recomendaciones, consulta Campos compatibles con las mejoras y las opiniones.

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 compatibles con la mejora y el ocultamiento

La función mejorar y ocultar admite algunos campos adicionales que el filtrado de recomendaciones estándar no admite, incluidos los campos numéricos.

Además de los campos enumerados en Campos admitidos, la función mejorar y ocultar para las recomendaciones admite los siguientes campos:

Campos textuales

campo	description
“etiquetas”	Product.tags[]. Son las etiquetas personalizadas asociadas con el 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 originales de precio y campo de precio de PriceInfo.
"rating"	Product.rating. Es la cantidad total de calificaciones del producto.
"ratingCount"	rating.ratingCount. Es la cantidad total de calificaciones del producto.

Establecer filtros de recomendaciones para un modelo

Puedes activar el filtrado para las 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 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 filtrado no funcionará con el atributo "categorías" porque la respuesta solo muestra resultados de productos que comparten una categoría con el producto del contexto.

Configurar el filtrado para un modelo con la consola

Con la consola de Search for Retail, selecciona la opción Generar etiquetas automáticamente durante la creación del modelo para permitir el filtrado de recomendaciones en 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 ocurre en último lugar.

• Por ejemplo, combinar diversity-level y category attribute filtering basados en reglas con frecuencia genera resultados vacíos.
  • diversity-level=high-diversity fuerza al modelo a limitar la cantidad máxima de resultados para las mismas cadenas de categoría. Es decir, 1 resultado para category1, 1 resultado para category2, etcétera.
  • Filtrar 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.
• Para el modelo similar-items, ya contiene boosting 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 personalizados.

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

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

Configura el filtrado para un modelo con la API

Puedes activar el filtrado 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, establece el campo filteringOption en tu modelo. Los valores permitidos de este campo son los siguientes:

• RECOMMENDATIONS_FILTERING_DISABLED (predeterminado): El filtro está desactivado para el modelo.
• RECOMMENDATIONS_FILTERING_ENABLED: El filtro 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 las opciones de filtrado 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 atributos como filtrables

Para filtrar los productos recomendados, activa el filtrado por los atributos de producto que usarás en las expresiones de filtro. 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 puedan filtrar más atributos de los necesarios. Existe un límite para la cantidad de atributos filtrables.

Establece los atributos como filtrables con la consola

Puedes establecer un atributo como página Controles filtrables en la consola de Search for Retail.

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 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.

Establece atributos para que se puedan filtrar con la API

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

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

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

En el siguiente ejemplo de curl, se consultan los 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 establece 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 elegido no aparece mientras visualizabas 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. Este proceso suele demorar al menos ocho horas.

Usa atributos filtrables en una solicitud de predicción

Una vez que tu modelo se haya vuelto a entrenar, puedes usar atributos de producto filtrables 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 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 filtrables, puede entregar 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 configurado como verdadero y una expresión de filtro con los atributos de producto colors y categories. En este ejemplo, se supone que colors y categories se configuraron 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, la configuración de diversificación de la configuración de entrega también puede afectar la cantidad de resultados que muestra la respuesta.