Retail cambiará de nombre a Vertex AI Search for Retail. Estamos en proceso de actualizar el contenido para reflejar el nuevo desarrollo de la marca.

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

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 especificando una expresión de filtro en predict solicitudes. 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 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 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 producto. 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 establece un atributo de producto como filtrable, pueden usar automáticamente esos atributos como etiquetas para el filtrado de recomendaciones, en lugar de exigir que agregar etiquetas de filtro.

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. Más adelante en esta página, se brinda cada procedimiento.

Activa el filtrado de recomendaciones para un modelo que hará lo siguiente: entregar recomendaciones filtradas.
Activa el filtrado de recomendaciones para los atributos de productos que planeas filtrar.
Utiliza 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 las etiquetas de filtro, que debes agregar manualmente a cualquier producto de tu que planeas 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 todos los productos que tengan el valor stockState. de OUT_OF_STOCK.

Puedes combinar filtros de etiquetas y de agotados para que solo los elementos satisfaga 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 manualmente y atributos de producto filtrables, puedes entregar solicitudes de predicción con cualquiera de las versiones de filtrado. Sin embargo, no es es posible incluir el filtrado v1 y las expresiones de filtrado v2 en la misma de predicción.

Límites para el filtrado de recomendaciones

Cada atributo filtrable consume algo de 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.

La cantidad total de valores de atributos en tu catálogo se puede estimar de la siguiente manera: multiplica la cantidad de productos en tu catálogo por la cantidad de productos que se pueden filtrar atributos.

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 las recomendaciones de la versión 1 filtrando junto con la versión 2, el la cantidad de etiquetas de filtro se tienen en cuenta para 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 expresión de filtro para buscar y recomendaciones son similares. Sin embargo, el recomendaciones tiene varias limitaciones.

La sintaxis de la expresión de filtro de recomendaciones se puede resumir de la siguiente manera: 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. El expresiones lógicas en el filtro deben estar en Formato conjuntivo 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 los siguientes: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Las expresiones se pueden negar con la palabra clave NOT o con -. 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 pueden Se usa como parte de una cláusula OR o 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 la función Boost y bury)
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 ANY(). con expresiones regulares. 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.

La siguiente tabla muestra ejemplos de expresiones de filtro válidas, así como ejemplos de expresiones de filtro no válidas ejemplos 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	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 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, consulte 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 de filtros de recomendaciones.

Los atributos relacionados con el inventario se pueden usar en cláusulas AND, pero no en 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 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

Mejorar y ocultar admite algunos campos adicionales que no son compatibles con el estándar filtros de recomendaciones, 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 textuales

campo	descripción
“etiquetas”	`Product.tags[]` Las etiquetas personalizadas 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` Número total de calificaciones para el período producto.

Establecer filtros de recomendaciones para un modelo

Puedes activar el filtrado de recomendaciones con la Busca en la consola de venta minorista o en el recurso de la API de Models.

En la consola, puedes crear un modelo nuevo que tenga filtros de recomendaciones habilitado. También puedes actualizar esta opción para los modelos existentes.

Con el recurso de API de Models, puedes crear un modelo nuevo con recomendaciones activar el filtrado o actualizar este parámetro de configuración para un modelo existente con models.Patch

Ten en cuenta que si la configuración de entrega que devuelve predicciones concordancia de categorías habilitada, el filtro no funciona las "categorías" porque la respuesta solo devuelve resultados de productos que comparten una categoría con el producto contextual.

Configurar el filtrado para un modelo con la consola

En 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 él.

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 de recomendaciones con la consola.

Este parámetro de configuración no se puede actualizar en la consola para los modelos existentes. Para actualizar esto La 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 usando models.Create cuando crees un nuevo modelo o models.Patch cuando actualizas un modelo 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 recomendaciones filtro 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 configuración de las opciones de filtrado de un servicio model.

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 Busca en la consola de venta minorista o usa el recurso de API de Attributes.

No permitas 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

Puede establecer un atributo como filtrable Página Controles en la Consola de Search for Retail.

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

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.
Configure Filterable como True para el atributo del producto.
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. Esta Estos son los valores permitidos para este campo:

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 de la siguiente manera: se pueden filtrar.

Cuando actualices un atributo existente, conservar los valores originales del atributo para indexableOption, dynamicFacetableOption y searchableOption, ya que 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 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 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 configurado como verdadero y un expresión de filtro con los atributos de 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, la configuración de entrega parámetro de configuración de diversificación también puede influir en los resultados que muestra la respuesta.