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

Catálogos e información de los catálogos

En esta página, se proporcionan prácticas recomendadas para crear la información y propagar los datos de tu catálogo.

Descripción general

Los datos del catálogo que importas a la venta minorista tienen un efecto directo en la calidad del modelo resultante y, por lo tanto, en la calidad de los resultados que proporciona la API de venta minorista. En general, cuanto más precisa y específica sea la información del catálogo que puedas proporcionar, mejor será la calidad de tu modelo.

Tu catálogo debe mantenerse actualizado. Puedes subir los cambios del catálogo con la frecuencia que sea necesaria. Idealmente, todos los días para catálogos con una alta tasa de cambio. Puedes subir (actualizar) elementos de productos existentes; solo se actualizarán los campos modificados. No se aplican cargos por subir información del catálogo. Para obtener más información, consulta Cómo mantener tu catálogo actualizado.

Ramas del catálogo

Usa las ramas del catálogo para probar los datos nuevos que subiste sin conexión antes de que se publiquen en tu sitio.

Con la API de venta minorista, puedes usar hasta tres ramas, identificadas como 0, 1 y 2. Tu sitio en vivo apunta a default_branch para sus datos del catálogo. Especifica qué rama es tu default_branch en vivo en este momento (está configurada como 0 de la rama de forma predeterminada) mediante setDefaultBranch o la pestaña Datos en Cloud Console. Luego, debido a que tu sitio apunta a default_branch para sus datos de catálogo, debes hacer lo siguiente.

Por ejemplo, supongamos que default_branch está configurado en la actualidad com 0 del ID de rama, por lo que tu sitio usa los datos del catálogo que subiste a esa rama. Puedes subir datos de catálogos nuevos a la rama 1 y obtener una vista previa. Una vez que confirmes que el catálogo se subió de forma correcta, puedes cambiar a 1 de la rama como default_branch en vivo.

Productos

El catálogo es una colección de objetos de productos.

Información requerida del producto

Los siguientes campos son obligatorios: Debes proporcionar valores para ellos cuando creas elementos de productos en tu catálogo. También deben corresponder a los valores usados en tu base de datos interna de productos y deben reflejar con precisión el producto representado, ya que se incluyen en el entrenamiento de tus modelos.

En algunos casos, también se requieren otros campos. Consulta la lista completa de todos los campos de productos en la página de referencia de Product.

Toda la información del producto que proporcionas se puede usar para mejorar la calidad de las recomendaciones y los resultados de la búsqueda. Asegúrate de proporcionar tantos campos como sea posible.

Campo	Notas
`name`	Es el nombre completo y único del recurso del producto. Obligatorio para todos los métodos `Product`, excepto `import`. Durante la importación, el nombre se genera de forma automática y no es necesario proporcionarlo de forma manual.
`id`	El ID del producto que usa tu base de datos de productos. El campo de ID debe ser único en todo tu catálogo. Los mismos valores se usan cuando registras un evento de usuario, y los métodos `predict` y `search` los muestran.
`title`	Título del producto de tu base de datos de productos. Una string codificada en UTF-8. Límite de 1250 caracteres.

Atributos de productos

Se recomienda proporcionar valores para los atributos predefinidos del sistema en Product, como la marca, el color y el tamaño. También puedes incluir atributos personalizados que definas con Product.attributes.

Si usas la búsqueda de venta minorista, los atributos se incluyen en un producto en la respuesta de búsqueda si los marcas como recuperables en Product.retrievableFields. Luego, se pueden usar para otras funciones de la búsqueda de venta minorista, como el filtrado y las facetas.

Usa niveles de productos

Cuando importas tu catálogo por primera vez, debes especificar si solo proporcionas elementos principales o elementos principales y sus variantes.

Los elementos principales son los que muestra la API de venta minorista en los resultados de la predicción o la búsqueda. Pueden ser elementos individuales (nivel de SKU) o grupos de elementos similares (grupos de SKU). De forma predeterminada, la API de venta minorista está configurada para importar solo elementos principales.
Los elementos de Variante son versiones de un producto principal. Las variantes solo pueden ser elementos individuales (a nivel de SKU). Por ejemplo, si el producto principal es “camisa con cuello en V”, las variantes podrían ser “camisa de cuello en V marrón, talle XL” y “camisa blanca de cuello en V, talle S”. A veces, los primarios y las variantes se describen como elementos "principales" y "secundarios". La importación de variantes es opcional.

Durante la importación de catálogos, configura tus niveles de producto mediante el método Catalog.patch. Por ejemplo:

curl -X PATCH 

-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" 

-H "Content-Type: application/json; charset=utf-8" 

--data '{
    "productLevelConfig": {
      "ingestionProductType": "PRODUCT-TYPE",
      "merchantCenterProductIdField": "PRODUCT-ID-FIELD"
    }
 }' 

"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

Para determinar las mejores opciones de nivel de producto para la implementación, debes revisar los datos de tu catálogo y la lógica de tu sitio web. ¿Qué ID de productos están disponibles cuando capturas datos de eventos de usuario? ¿Qué ID de productos serían más eficaces con predicciones o resultados de la búsqueda? ¿Cómo se comparan y se relacionan esos ID?

Sigue los pasos correspondientes según si importas desde Merchant Center o no:

Determina tus niveles de productos para importarlos desde Merchant Center

Cuando importas datos de catálogos de Merchant Center, la API de venta minorista usa ingestionProductType para ayudar a identificar si los debes subir como primarios o variantes, y merchantCenterProductIdField para especificar si se usará offer_id o item_group_idde Merchant Center como ID del producto.

Revisa las lógicas del catálogo y el sitio web para responder las siguientes preguntas:

¿Tengo principales y variantes en mi catálogo?
De ser así, ¿qué nivel de elemento tendrás disponible cuando capture los datos del evento del usuario?
¿Qué tipo de elementos necesito que se muestren con mis resultados?

Determina si:

Tu catálogo tiene solo un nivel de artículos. Esto puede significar lo siguiente:
- Todos tus productos y eventos están a nivel de SKU, y deseas predicciones de nivel de SKU.
- Todos los productos y eventos están a nivel del grupo y deseas obtener predicciones a nivel del grupo.
Si es así, importa solo elementos principales. Esta es la configuración de importación predeterminada.
Deseas predicciones a nivel de grupo (principal), pero tus productos de Merchant Center están a nivel de SKU. En este caso, tu decisión de importación depende de cómo se capturan los eventos.
1. Tus eventos se capturan a nivel del grupo. Si es así, usa la siguiente configuración durante la importación:
  - ingestionProductType configurado como primary (predeterminado)
  - merchantCenterProductIdField configurado como itemGroupId.
  Varios productos de Merchant Center tienen el mismo Merchant Centeritem_group_id, la venta minorista importa solo uno de ellos como producto principal y usa elitem_group_id como ID del producto. En este caso, no se pueden importar los productos que no tienen un item_group_id. Los eventos registrados deben hacer referencia al ID del producto principal (a nivel del grupo).
2. Tus eventos se capturan a nivel de SKU. Si es así, usa la siguiente configuración durante la importación:
  - ingestionProductType configurado como variant.
  - merchantCenterProductIdField configurado como offerId (predeterminado)
  La venta minorista importa tus productos como variantes y usa offer_id de Merchant Center como su ID de producto. Los eventos grabados deben hacer referencia al ID del producto de la variante (nivel de SKU).

Determina los niveles de tus productos para importar sin Merchant Center

Todos tus productos deben tener un valor para primaryProductId o ninguno de ellos puede. No puedes importar datos de catálogos con primaryProductId establecido en algunos elementos, pero no en otros.

Si tu catálogo tiene un solo nivel de elementos, esto puede significar lo siguiente:
- Todos tus productos y eventos están a nivel de SKU, y deseas resultados a nivel de SKU.
- Todos los productos y eventos están a nivel del grupo y deseas obtener resultados a nivel de grupo.
Si es así, importa solo elementos principales. Esta es la configuración de importación predeterminada y recomendada.
Si tus eventos y productos están a nivel del SKU, puedes obtener resultados a nivel de grupo. Configura ingestionProductType como variant durante la importación.

La predicción y la búsqueda a nivel de SKU no son compatibles si solo tienes eventos y productos a nivel de grupo.

Si planeas importar datos de catálogos de Merchant Center en el futuro, revisa tus datos como se describe para importaciones de Merchant Center a fin de asegurarte de que tomas la decisión correcta. Solo se puede cambiar esta configuración si borras el catálogo y lo vuelves a subir (consulta Cambia la configuración a nivel del producto).

Métricas de calidad de los datos del catálogo

Para ayudarte a supervisar la calidad de búsqueda de tus datos de catálogo, la venta minorista evalúa los datos de tus productos en función de un conjunto de reglas de calidad. Puedes ver el porcentaje de productos que cumplen con cada regla de calidad en la página de datos de venta minorista.

En la siguiente tabla, se describen las métricas de calidad que usa la venta minorista para ayudarte a evaluar los datos de tus productos:

Métrica de calidad del catálogo	Regla de calidad	Notas
El URI está presente y se puede acceder a él	El producto tiene un `Product.uri` válido. El URI debe ser accesible y coincidir con tu dominio.	La búsqueda de venta minorista de Cloud usa señales web rastreadas a través de este URI para mejorar la calidad de la búsqueda.
Cumple con la conformidad de horario	`Product.availableTime` es anterior a la hora actual y `Product.expireTime` es posterior a la hora actual.	Solo se pueden buscar productos que cumplan con la conformidad de horario.
El atributo que se puede buscar está presente	El producto debe tener al menos un `attribute` configurado para que se pueda buscar.	Los atributos personalizados que están marcados para la búsquedas se pueden buscar mediante consultas de texto.
La descripción está presente	El producto tiene `Product.description` no vacío.	Una descripción completa ayuda a mejorar la calidad de la búsqueda.
El título consta de al menos dos palabras	`Product.title` consta de, al menos, dos palabras.	Un título integral ayuda a mejorar la calidad de la búsqueda.
Tiene variante con imagen	El producto `variant` tiene al menos un `Product.image`. Puedes ignorar esta métrica si todos tus productos se encuentran en el nivel de `primary`.	Esta métrica solo tiene fines informativos y no afecta la calidad de la búsqueda.
Tiene variantes con información sobre el precio	El producto `variant` tiene configurado `Product.priceInfo`. Puedes ignorar esta métrica si todos tus productos se encuentran en el nivel de `primary`.	Esta métrica solo tiene fines informativos y no afecta la calidad de la búsqueda.

Esquema de venta minorista

Cuando importes un catálogo desde BigQuery, usa el esquema de venta minorista que se encuentra a continuación para crear una tabla de BigQuery con el formato correcto y cargarla con los datos de tu catálogo. Luego, importa el catálogo.

JSON de esquema de venta minorista

JSON

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          },
          {
            "name": "searchable",
            "type": "BOOLEAN",
            "mode": "NULLABLE"
          },
          {
            "name": "indexable",
            "type": "BOOLEAN",
            "mode": "NULLABLE"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "retrievableFields",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]