Filtrar recomendaciones

En esta página, se describen los resultados de filtrado para las recomendaciones mediante atributos del producto.

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 para cada producto. La lista de productos de la respuesta se reduce a productos. donde 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 práctica solo aplican a la versión 2 del filtrado, que filtra recomendaciones con atributos de producto.

Filtrado de recomendaciones, versión 2

La versión 2 usa atributos de productos. Filtrar expresiones 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, 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 devuelve productos principales que contienen al menos un producto principal o una variante que tenga un valor de atributo que coincida con el filtro expresión. Para obtener más información sobre los productos principales y las variantes, consulte Niveles de producto.

El siguiente ejemplo de expresión de filtro también filtra por cualquier color rojo o azul productos configurados como “Nuevos” y no establecido como promocional:

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 pasos: y procedimientos de seguridad. 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 planeas filtrar.
  3. Usa atributos de productos filtrables 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 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 etiquetado como “Rojo” o "azul", así como la etiqueta "Nueva llegada", y no se etiquetado 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 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 en stock que tienen la etiqueta spring-sale o exclusive (o ambas), y no tiene el 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 productos filtrables, puede entregar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es es posible incluir expresiones de filtrado v1 y v2 en la misma de predicción.

Límites de filtrado de recomendaciones

Cada atributo filtrable consume cierta memoria en cada uno de tus modelos. El 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, 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 establecidos como filtrables, la cantidad total de valores de atributos se puede estimar de la siguiente manera: 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 agregadas al número total de valores del atributo es menor que 100,000,000.

Si superas los límites, no podrás estableciendo atributos adicionales como filtrables. Si necesitas superar estos límites, solicitar 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 hay más de 10 atributos se encuentran durante el entrenamiento de modelos, solo se usan 10.

Sintaxis de expresiones 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 la incorporación de los operadores AND y OR entre paréntesis es limitada. Las expresiones lógicas del filtro deben estar en formato disyuntivo normal (CNF). La más compleja expresión lógica admitida puede ser una lista conectada con AND de cláusulas que solo contienen operadores OR, como por ejemplo: (... 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 textuales, no se admiten las operaciones menor que, mayor que y verificación de rango para el filtrado de recomendaciones estándar. Las operaciones menor que y mayor que pueden usarse solo con las recomendaciones para las condiciones de control mejorar y ocultar 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 que se incluyen en expresiones ANY(). Si una cláusula OR tiene varias expresiones ANY(), su todos los argumentos se consideran en 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.

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 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 por 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 devuelve los productos principales si 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 mejorar y ocultar para las recomendaciones admite campos adicionales que no son compatibles con el filtrado de recomendaciones estándar. Para obtener una lista de campos adicionales compatibles con la función mejorar y ocultar recomendaciones, consulta Campos compatibles mejorar y ocultar.

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 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 enumerados en los Campos admitidos, Boost/bury para las 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 el precio original y los valores de campo de precio de PriceInfo.
"rating" Product.rating Número total de calificaciones para el período producto.
"ratingCount" rating.ratingCount Es la cantidad total de calificaciones del producto.

Cómo establecer 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 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 strings 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.
  • 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 para 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 en tu modelo. La valores permitidos son los siguientes:

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

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 servicio un modelo de responsabilidad compartida.

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 productos recomendados, activa el filtrado de los atributos de 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 hagas que se puedan filtrar más atributos de los necesarios. Existe un límite de atributos que se pueden filtrar.

Establece los atributos como filtrables 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 Modificar 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 del siguiente entrenamiento de modelos. el ciclo de vida de los cambios.

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 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 aparece cuando visualizas attributesConfig como en el ejemplo anterior y, luego, usa el valor predeterminado 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 del siguiente entrenamiento de modelos. el ciclo de vida de los cambios. Este proceso suele tardar ocho horas como mínimo.

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 la versión 2 filtros de recomendaciones. Si no se configura el parámetro, se filtrará la versión 1 permanezca activa. Si un modelo tiene etiquetas creadas manualmente y productos filtrables puede entregar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es posible incluir el filtrado v1 y el filtrado 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. Esta En el 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, 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.