Se cambiará el nombre de Vertex AI Search para la venta minorista a Vertex AI Search para comercios. Estamos actualizando el contenido para reflejar el nuevo desarrollo de la marca.

Se usó la API de Cloud Translation para traducir esta página.

Cómo filtrar recomendaciones

En esta página, se describe cómo filtrar los resultados de las recomendaciones con 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 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.

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

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

Filtrado de recomendaciones, versión 2

La versión 2 usa atributos del producto. Las expresiones de filtro se basan en atributos del producto. Pueden ser atributos del sistema predefinidos, como categories y colors, o atributos personalizados que definas, como attributes.styles. Cuando configuras un atributo del 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 predicción devuelve 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 las variantes, consulta Niveles de producto.

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

Activa el filtrado de recomendaciones para un modelo que publicará recomendaciones filtradas.
Activa el filtrado de recomendaciones para los atributos de productos que planeas usar como filtro.
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 manualmente. Las expresiones de filtro se basan en etiquetas de filtro, que debes agregar manualmente a los productos de tu catálogo que planeas 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 "Nuevo", y que 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 de artículos sin stock para que solo se muestren los artículos 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 del filtro de atributos y el filtro de etiquetas

Si un modelo tiene etiquetas creadas manualmente y atributos de productos filtrables, puede atender solicitudes de predicción con cualquiera de las versiones de filtrado. 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

Agrega manualmente criterios de filtro para restringir el conjunto de recomendaciones que se muestran a los usuarios finales. Usa Vertex AI Search for Commerce 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:

En tu catálogo, se pueden configurar hasta 10 atributos personalizados como filtrables.
En tu catálogo, puede haber hasta 100,000,000 de valores de atributos filtrables.

La cantidad total de valores de atributos en tu catálogo se puede estimar multiplicando 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 configurados como filtrables, la cantidad total de valores de atributos se puede estimar como 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 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 aptos para filtrarse. 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 usarán 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.

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 del filtro

Se aplican las siguientes restricciones:

La profundidad de los operadores AND y OR incluidos entre paréntesis es limitada. Las expresiones lógicas del filtro deben estar en forma normal conjuntiva (CNF). La expresión lógica más compleja admitida puede ser una lista de cláusulas conectadas con AND que solo contengan operadores OR, como la siguiente: (... 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, no se admiten las operaciones de menor que, mayor que ni de verificación de rango para el filtrado de recomendaciones estándar. Las operaciones de menor que y mayor que solo se pueden usar con las condiciones de control de refuerzo o ocultamiento de recomendaciones, que admiten algunos campos numéricos (consulta Campos admitidos para refuerzo o ocultamiento).
La cantidad máxima de términos en la cláusula AND de nivel superior es de 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. En el caso de uso de Vertex AI Search for Commerce, puedes considerar un argumento como el equivalente a 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 según los atributos relacionados con el inventario se basa en el estado en tiempo real de tus productos. Para el filtrado de availability: ANY("IN_STOCK"), la respuesta de predicción devuelve productos principales en los que el producto principal o un producto variante tienen 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 de 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 las cláusulas AND, pero no en las cláusulas OR.

Campos disponibles

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

La función de potenciar o descartar recomendaciones admite campos adicionales que no son compatibles con el filtrado de recomendaciones estándar. Para obtener una lista de estos campos, consulta Campos admitidos para potenciar o enterrar.

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 función de mejorar y ocultar

La función de refuerzo o eliminació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 admitidos, la amplificación y el ocultamiento de recomendaciones admiten los siguientes campos:

Campos de texto

campo	descripción
"tags"	`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 del precio original y del 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.

Cómo establecer el filtrado de recomendaciones para un modelo

Puedes activar el filtrado de recomendaciones con la consola de Search for commerce o el recurso de la API de Models.

En la consola, puedes crear un modelo nuevo con el filtro de recomendaciones habilitado. 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 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 devuelve predicciones tiene habilitada la coincidencia de categorías, el filtrado no funciona con el atributo "categories", ya que la respuesta solo devuelve resultados de productos que comparten una categoría con el producto de contexto.

Cómo establecer el filtrado para un modelo con la consola

Con la consola de Search for Commerce, 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, ya que los efectos totales se combinan y el filtrado se realiza al final.

Por ejemplo, combinar diversity-level y category attribute filtering basadas en reglas suele generar 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étera.
- El filtrado de 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 una potenciación 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 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 un modelo nuevo o con 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 con el filtrado 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 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"

Cómo configurar atributos como filtrables

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

No hagas que más atributos sean filtrables de lo necesario. Existe un límite en la cantidad de atributos que se pueden filtrar.

Cómo configurar atributos como filtrables con la consola

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

Ve a la página Controles en la consola de Search for commerce.

Ir a la página Controles
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.
Haz clic en Modificar controles.
Establece Filterable en True para el atributo del producto.
Haz clic en Guardar controles.

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

Configura 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 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 del 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 que elegiste 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 filtrar después de que se complete el próximo ciclo de entrenamiento de modelos. Por lo general, este proceso 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 en 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 permanecerá activo. Si un modelo tiene etiquetas creadas manualmente y atributos de productos filtrables, puede atender solicitudes de predicción con cualquiera de las versiones de filtrado. 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 establecido como verdadero y una expresión de filtro que usa los atributos del producto colors y categories. En este ejemplo, se supone que colors y categories están configurados 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 la entrega también puede afectar la cantidad de resultados que devuelve la respuesta.