Vertex AI Search para retail cambia su nombre a Vertex AI Search para el sector del comercio. Estamos actualizando el contenido para reflejar la nueva marca.

Esta página se ha traducido con Cloud Translation API.

Filtrar recomendaciones

En esta página se describe cómo filtrar los resultados de las recomendaciones mediante atributos de producto.

Puede filtrar los resultados de las predicciones especificando una expresión de filtro en las solicitudes de predicción. La expresión del filtro es una expresión lógica que se evalúa para cada producto. La lista de productos de la respuesta se limita a los productos en los que la expresión se evalúa como verdadera.

Hay dos versiones de filtrado de recomendaciones:

Se recomienda la versión 2.
La versión 1 está obsoleta, pero puede que aún se esté usando.

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.

Filtrado de recomendaciones, versión 2

La versión 2 usa atributos de producto. Las expresiones de filtro se basan en atributos de producto. Pueden ser atributos del sistema predefinidos, como categories y colors, o atributos personalizados que definas, como attributes.styles. Cuando define un atributo de producto como filtrable, las recomendaciones pueden usar automáticamente esos atributos como etiquetas para filtrar recomendaciones, en lugar de tener que añadir etiquetas de filtro manualmente.

Cuando usas atributos para filtrar productos, la respuesta de predicción devuelve productos principales que contienen al menos un producto principal o una 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, consulte el artículo Niveles de producto.

El siguiente ejemplo de expresión de filtro también filtra los productos rojos o azules que se hayan definido como "Novedad" 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 explica más adelante en esta página.

Activa el filtrado de recomendaciones para un modelo que ofrezca recomendaciones filtradas.
Active el filtro de recomendaciones para los atributos de producto que quiera usar para filtrar.
Usa atributos de producto filtrables en las solicitudes de predicción.

Filtrado de recomendaciones, versión 1 (obsoleto)

La versión 1 usa etiquetas de filtro creadas manualmente. Las expresiones de filtro se basan en etiquetas de filtro, que debe añadir manualmente a los productos de su catálogo que quiera filtrar.

En el siguiente ejemplo de expresión de filtro se usan etiquetas de filtro para especificar los productos etiquetados como "Rojo" o "Azul", así como la etiqueta "Novedad", y que no estén etiquetados 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 etiquetas pueden contener los operadores booleanos OR u NOT, que deben separarse de los valores de las etiquetas con uno o varios espacios. Los valores de las etiquetas también se pueden preceder inmediatamente con un guion (-), que equivale al operador NOT. Las expresiones de etiquetas que usan operadores booleanos deben incluirse entre paréntesis.

Además de las etiquetas, puedes filtrar por filterOutOfStockItems. La marca filterOutOfStockItems filtra los productos que tienen un stockState de OUT_OF_STOCK.

Puedes combinar filtros de etiquetas y filtros de falta de stock para que solo se devuelvan los elementos que cumplan todas las expresiones de filtro especificadas.

Algunos ejemplos de cadenas de filtro:

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

"filter": "filterOutOfStockItems"

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

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

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

Compatibilidad entre filtros de atributos y filtros de etiquetas

Si un modelo tiene etiquetas creadas manualmente y atributos de producto filtrables, puede responder a solicitudes de predicción usando cualquiera de las dos versiones del filtro. Sin embargo, no es posible incluir expresiones de filtrado de la versión 1 y de la versión 2 en la misma solicitud de predicción.

Límites de filtrado de recomendaciones

Añade manualmente criterios de filtro para restringir el conjunto de recomendaciones que se devuelven a los usuarios finales. Usa Vertex AI Search para el comercio y aplica reglas empresariales para ajustar qué ven los clientes, incluidas las opciones para filtrar por disponibilidad de los productos, etiquetas personalizadas y otros criterios.

Cada atributo por el que se puede filtrar consume memoria en cada uno de sus modelos. Los siguientes límites ayudan a evitar efectos adversos en el rendimiento del servicio:

Puede definir hasta 10 atributos personalizados como filtrables en su catálogo.
Su catálogo puede incluir hasta 100.000.000 valores de atributos filtrables.

El número total de valores de atributo de su catálogo se puede estimar multiplicando el número de productos de su catálogo por el número de atributos por los que se puede filtrar.

Por ejemplo, si tiene un catálogo con 1000 productos y 3 atributos definidos como filtrables, el número total de valores de atributos se puede estimar como 3 x 1000=3000.

Si usas el filtrado de recomendaciones de la versión 1 junto con la versión 2, el número de etiquetas de filtro se incluirá en tu cuota. Asegúrese de que el número de etiquetas de filtro añadidas al número total de valores de atributo sea inferior a 100.000.000.

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

El número total de etiquetas se calcula durante el entrenamiento del modelo. Si el número total supera el límite, no se podrá entrenar el modelo. Si se encuentran más de 10 atributos personalizados filtrables durante el entrenamiento del modelo, solo se usarán 10.

Sintaxis de las expresiones de filtro de recomendaciones

Las sintaxis de las expresiones de filtro de las búsquedas 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 la sintaxis de filtro

Se aplican las siguientes limitaciones:

La profundidad de la inserción de los operadores AND y OR entre paréntesis es limitada. Las expresiones lógicas del filtro deben estar en forma normal conjuntiva (FNC). La expresión lógica más compleja que se puede usar es una lista de cláusulas conectadas con AND que solo contengan operadores OR, como (... OR ... OR ...) AND (... OR ...) AND (... OR ...).
Las expresiones se pueden negar con la palabra clave NOT o con -. Esta opción solo funciona con expresiones ANY() con un único argumento que no incluyan 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).
Como el filtrado de recomendaciones estándar solo admite campos de texto, no se pueden usar las operaciones menor que, mayor que y de comprobación de intervalo. Las operaciones de menor que y mayor que solo se pueden usar con las condiciones de control de aumentar o reducir la visibilidad de las recomendaciones, que admiten algunos campos numéricos (consulta Campos admitidos para aumentar o reducir la visibilidad).
El número máximo de términos en la cláusula AND de nivel superior es 20.
Una cláusula OR puede tener hasta 100 argumentos incluidos en ANY() expresiones. 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	Sí	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 por atributos relacionados con el inventario se basa en el estado en tiempo real de sus productos. En el caso del filtrado por availability: ANY("IN_STOCK"), la respuesta de predicción devuelve los productos principales en los que el producto principal o una variante tienen el valor de IN_STOCK. Para obtener más información sobre los productos principales y las variantes, consulte el artículo Niveles de producto. No admitimos el filtrado por Primary only ni por Variant only.

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

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

Campos admitidos

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

La función de destacar o ocultar recomendaciones admite campos adicionales que no se pueden usar con el filtrado de recomendaciones estándar. Para ver una lista de estos campos, consulta Campos admitidos para aumentar o reducir la visibilidad.

campo	description
"productId"	El ID del producto (el último segmento de Product.name).
"brands"	Los Product.brands.
"categories"	El valor de Product.categories.
"genders"	Audience.genders.
"ageGroups"	Audience.age_groups.
"colorFamilies"	ColorInfo.color_families.
"colors"	ColorInfo.colors.
"sizes"	Product.sizes.
"materials"	The Product.materials.
"patterns"	Product.patterns.
"conditions"	The Product.conditions.
"attributes.key"	Atributo personalizado de texto del objeto Product. La clave puede ser cualquier clave del mapa Product.attributes si los valores de los atributos son textuales.

Campos admitidos para aumentar o reducir la importancia

La función de destacar o ocultar 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 indican en Campos admitidos, la función de destacar o ocultar recomendaciones admite los siguientes campos:

Campos de texto

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

Campos numéricos

campo	description
"price"	`PriceInfo.price`. El precio del producto.
"discount"	El descuento del producto. Este campo se calcula a partir de los valores de los campos de precio y precio original de `PriceInfo`.
"rating"	`Product.rating`. Número total de valoraciones del producto.
"ratingCount"	`rating.ratingCount`. Número total de valoraciones del producto.

Definir el filtrado de recomendaciones de un modelo

Puede activar el filtrado de recomendaciones mediante la consola de búsqueda de comercio o el recurso de la API Models.

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

Con el recurso de la API Models, puedes crear un modelo con el filtro de recomendaciones activado o actualizar este ajuste en un modelo ya creado con models.Patch.

Tenga en cuenta que, si la configuración de servicio que devuelve predicciones tiene habilitada la coincidencia de categorías, no se puede filtrar por el atributo "categories" porque la respuesta solo devuelve resultados de productos que comparten una categoría con el producto de contexto.

Definir filtros para un modelo con la consola

En la consola de búsqueda de comercio, seleccione la opción Generar etiquetas automáticamente durante la creación del modelo para permitir el filtrado de recomendaciones de ese modelo.

Comprueba la compatibilidad con otros ajustes, como diversity-level y category-match-level, etc., ya que los efectos totales se combinan y el filtrado se produce al final.

Por ejemplo, combinar diversity-level y category attribute filtering basadas en reglas suele dar como resultado un resultado vacío.
- diversity-level=high-diversity obliga al modelo a limitar los resultados máximos de las mismas cadenas de categorías. Es decir, un resultado para la categoría 1, un resultado para la categoría 2, etc.
- Si se filtran los atributos mediante metadatos de categoría (Product.categories = ANY ("category2")), el modelo descartará los elementos que no coincidan.
- La salida final tiene menos de tres resultados.
En el caso del modelo similar-items, ya incluye un aumento de la relevancia de las categorías con el valor predeterminado category-match-level = relaxed-category-match. Cambie a category-match-level=no-category-match para inhabilitar el comportamiento y usar reglas de filtrado personalizadas.

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

Este ajuste no se puede actualizar en la consola para los modelos que ya existen. Para actualizar este ajuste en un modelo, usa el método de la API models.Patch.

Definir filtros para un modelo con la API

Puedes activar el filtrado de recomendaciones de un modelo mediante models.Create al crear un modelo o models.Patch al actualizar uno que ya tengas.

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

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

En el siguiente ejemplo de curl se crea un modelo nuevo con el filtro de recomendaciones activado.

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 opción de filtrado de un modelo que ya existe.

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"

Definir atributos como filtrables

Para filtrar los productos recomendados, active el filtro de los atributos de producto que vaya a usar en las expresiones de filtro. Puede actualizar este ajuste mediante la consola de búsqueda de comercio o el recurso de la API Attributes.

No haga que se puedan filtrar más atributos de los necesarios. Hay un límite en el número de atributos por los que se puede filtrar.

Definir atributos como filtrables mediante la consola

Puede definir un atributo como filtrable en la página Controles de la consola de búsqueda de comercio.

Ve a la página Controles de la consola de búsqueda de comercio.

Ve a la página Controles.
Ve a la pestaña Controles de atributos.

En esta pestaña se muestra una tabla con todos los atributos de producto para los que puede definir controles en todo el sitio.
Haz clic en Modificar controles.
Asigna el valor True al atributo de producto Filterable.
Haz clic en Guardar controles.

Puede empezar a usar el atributo para filtrar después de que se haya completado el siguiente ciclo de entrenamiento del modelo.

Definir atributos como filtrables mediante la API

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

Defina el campo AttributesConfig.filteringOption de CatalogAttribute. Los valores permitidos de este campo son:

RECOMMENDATIONS_FILTERING_DISABLED (valor predeterminado): el filtrado 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 producto que ya tiene.

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 define el atributo de producto categories como filtrable.

Cuando actualice un atributo, conserve los valores originales de indexableOption, dynamicFacetableOption y searchableOption tal como aparecen en el paso anterior. Si el atributo que ha elegido no aparece al ver attributesConfig, como en el ejemplo anterior, utilice la configuración predeterminada, tal 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"

Puede empezar a usar el atributo para filtrar después de que se haya completado el siguiente ciclo de entrenamiento del modelo. Este proceso suele tardar al menos ocho horas.

Usar atributos filtrables en una solicitud de predicción

Una vez que se haya vuelto a entrenar el modelo, podrá usar atributos de producto filtrables en sus solicitudes de predicción.

Asigna el valor filterSyntaxV2 al parámetro de solicitud para activar el filtrado de recomendaciones de la versión 2. Si no se define el parámetro, el filtrado de la versión 1 seguirá activo. Si un modelo tiene etiquetas creadas manualmente y atributos de producto filtrables, puede responder a solicitudes de predicción usando cualquiera de las dos versiones del filtro. Sin embargo, no es posible incluir expresiones de filtrado de la versión 1 y de la versión 2 en la misma solicitud de predicción.

En el siguiente ejemplo parcial de curl se muestra filterSyntaxV2 definido como true y una expresión de filtro que usa los atributos de producto colors y categories. En este ejemplo se da por hecho que colors y categories se han definido 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 ajuste de diversificación de la configuración de publicación también puede afectar al número de resultados devueltos por la respuesta.