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.

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

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 práctica 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 predefinidos del sistema, como categories y colors, o atributos personalizados que definas, como attributes.styles. Cuando estableces 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 variante que tiene un valor de atributo que coincide con la expresión de filtro. Para obtener más información sobre los productos principales y variantes, consulta Niveles de productos.

En el siguiente ejemplo de expresión de filtro, también se filtran los productos rojos o azules establecidos como "New-Arrival" 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 proporciona 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 en los que planeas 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 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 "Red" o "Blue", así como la etiqueta "New-Arrival", y no están etiquetados como "promotional":

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 de artículos 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, 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 entre el filtro de atributos y el filtro de etiquetas

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

Límites de filtrado de recomendaciones

Agrega criterios de filtro de forma manual para restringir el conjunto de recomendaciones que se muestran a los usuarios finales. Usa AI Commerce Search para aplicar reglas comerciales y ajustar lo que ven los clientes, incluidas las opciones para filtrar por disponibilidad de productos, etiquetas personalizadas y otros criterios.

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:

• Se pueden establecer hasta 10 atributos personalizados como filtrables en tu catálogo.

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

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

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

  Si usas el filtrado de recomendaciones de la versión 1 junto con la versión 2, la cantidad de etiquetas de filtro se incluye 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 establecer 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, 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

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

Se puede resumir la sintaxis de la expresión de filtro de recomendaciones 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 la sintaxis de filtro

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 del filtro deben estar en forma normal conjuntiva (CNF). La expresión lógica admitida más compleja puede ser una lista conectada con AND-de cláusulas que solo contengan OR operadores, 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 solo argumento que no incluyen 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).
• Dado que el filtrado de recomendaciones estándar solo admite campos de texto, las operaciones de menor que, mayor que y verificación de rango no son compatibles con el filtrado de recomendaciones estándar. Las operaciones de menor que y mayor que pueden usarse solo con las condiciones de control de aumento o disminución de recomendaciones, que admiten algunos campos numéricos (consulta Campos admitidos para aumentar o disminuir).
• 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 incluyen en este límite. Por ejemplo, colors: ANY("red", "green") OR colors: ANY("blue") tiene tres argumentos. Para el caso de uso de AI Commerce Search, puedes considerar un argumento como el equivalente de un valor de atributo.

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.

Expresión	Válido	Notas
colors: ANY("red", "green")	Sí
NOT colors: ANY("red")	Sí
NOT colors: ANY("red", green")	No	Niega un `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 está en forma normal conjuntiva.
(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 predicción muestra los 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 variantes, consulta Niveles de productos. No admitimos el filtrado Primary only ni Variant only.

IN_STOCK es el único valor de atributo availability admitido por 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.

**Sugerencia:** Si bien la API de Search admite el filtrado por estado de stock del inventario local, la API de Recommendations no lo hace. Una solución alternativa para filtrar las respuestas de Recomendaciones por estado de stock a nivel del inventario local es agregar un paso de procesamiento posterior, en el que filtras la lista de productos con tu propio método antes de enviarla al cliente.

Campos disponibles

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

El aumento o la disminución de recomendaciones admite campos adicionales que no son compatibles con el filtrado de recomendaciones estándar. Para obtener una lista de esos campos, consulta Campos admitidos para aumentar o disminuir.

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 para aumentar o disminuir

El aumento o la disminució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 disponibles, el aumento o la disminución de recomendaciones admite los siguientes campos:

Campos de texto

campo	descripción
"tags"	Product.tags[]. 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 de los campos de precio y precio original 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 de recomendaciones con AI Commerce Search en la consola de Gemini Enterprise para la experiencia del cliente 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 predicciones tiene la coincidencia de categorías habilitada, el filtrado no funciona con el atributo "categories", ya que la respuesta solo muestra resultados de productos que comparten una categoría con el producto de contexto.

Configura el filtrado para un modelo con la consola

Con AI Commerce Search en la consola de Gemini Enterprise para la experiencia del cliente, selecciona la opción Generar etiquetas automáticamente durante la creación del modelo para permitir el filtrado de recomendaciones para ese modelo.

Verifica 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, la combinación de diversity-level basado en reglas y category attribute filtering suele dar como resultado 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.
  • El filtrado de atributos con metadatos de categorías (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 un aumento adicional de la relevancia de la categoría con el valor predeterminado category-match-level = relaxed-category-match. 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 para un modelo, usa el models.Patch método de la API.

Configura el filtrado para un modelo con la API

Puedes activar el filtrado de recomendaciones para un modelo con models.Create cuando crees un modelo nuevo o models.Patch cuando actualices un modelo 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 el parámetro de 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"

Establece atributos como filtrables

Para filtrar los productos recomendados, activa el filtrado para los atributos de productos que usarás en las expresiones de filtro. Puedes actualizar este parámetro de configuración con AI Commerce Search en la consola de Gemini Enterprise para la experiencia del cliente o con el recurso de la API de Attributes.

No establezcas más atributos como filtrables de lo necesario. Existe un límite en la cantidad de atributos filtrables.

Establece atributos como filtrables con la consola

Puedes establecer un atributo como filtrable página Controles en la AI Commerce Search en la consola de Gemini Enterprise para la experiencia del cliente.

1. Ve a la página Controles en AI Commerce Search en la consola de Gemini Enterprise para la experiencia del cliente.
   
   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. Establece Filtrable en Verdadero para el atributo de producto.

5. Haz clic en Guardar controles.

Puedes comenzar a usar el atributo para el filtrado después de que se complete el próximo ciclo de entrenamiento de modelos.

Establece 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 tus 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 tal como aparecen en el paso anterior. Si el atributo elegido 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 el filtrado después de que se complete el próximo ciclo de entrenamiento de modelos. Por lo general, esto tarda al menos ocho horas.

Usa atributos filtrables en una solicitud de predicción

Después de volver a entrenar tu modelo, puedes usar atributos de productos filtrables en tus solicitudes de predicción.

Establece el valor del parámetro de solicitud filterSyntaxV2 como 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 permanece activo. Si un modelo tiene etiquetas creadas de forma manual y atributos de productos filtrables, 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 con los atributos de productos colors y categories. En este ejemplo, se supone que colors y categories están establecidos 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.