Requisitos de datos - Topsort Documentation

T-Brain aprende de la información de tus productos y de la actividad de los compradores. Puedes subir datos desde tus sistemas existentes o, si eres cliente de Topsort, usar conjuntos de datos que ya están sincronizados desde Topsort. Para empezar, proporciona tu catálogo y al menos un mes de historial de eventos, incluidas todas las compras y los clics e impresiones de productos pagados.

Tipos de conjuntos de datos

Un conjunto de datos es una colección con nombre que se usa para entrenar un modelo. T-Brain admite tres tipos de conjuntos de datos:

Tipo de conjunto de datos	Qué contiene
Categories	Nombres de categorías y su lugar en la jerarquía del catálogo.
Products	Información de productos, incluidos identificadores, descripciones, marcas y asociaciones de categoría.
Events	Actividad de los compradores, incluidas impresiones, clics y compras.

Puedes nombrar los conjuntos de datos para distinguir su propósito u origen, como products-main-store o events-september.

Subir datos

Ve a Data.
Haz clic en Add dataset.
Selecciona Categories, Products o Events.
Ponle un nombre al conjunto de datos.
Sube tus archivos Parquet y sigue las instrucciones.

T-Brain muestra la estructura requerida para cada tipo de conjunto de datos y verifica que tus archivos la cumplan. Las tablas siguientes explican las columnas que aparecen en los requisitos de carga. Los campos marcados como Required deben completarse. Los demás aportan información de producto, relaciones o contexto necesario para tu caso de uso.

Columna	Tipo	Requisito	Descripción
`category_id`	String	Required	Identificador único de la categoría. Los productos hacen referencia a este valor mediante `category_ids`.
`name`	String	Required	Nombre visible de la categoría.
`path`	String	Optional	Jerarquía de categorías separada por puntos, con la categoría más general primero.

Products

Las cargas de productos son instantáneas. Cada carga debe contener el conjunto completo de productos.

Columna	Tipo	Requisito	Descripción
`product_id`	String	Required	Identificador único del producto. Debe coincidir exactamente con el `product_id` correspondiente en los registros de eventos.
`name`	String	Optional	Nombre visible del producto, usado para ayudar al modelo a entender el producto.
`description`	String	Optional	Descripción del producto. Se acepta HTML y se elimina durante el procesamiento.
`image_url`	String	Optional	URL de la imagen del producto, usada al generar embeddings de imagen.
`brand_id`	String	Optional	Identificador de la marca.
`brand_name`	String	Optional	Nombre visible de la marca.
`category_ids`	List of strings	Optional	Identificadores de categoría que coinciden con registros del conjunto de datos de categorías.
`price`	Decimal	Optional	Precio en las unidades de moneda de tu marketplace. Cero es un precio válido; null significa desconocido.
`active`	Boolean	Optional	Si el producto está disponible para que el modelo lo seleccione.
`parent_product_id`	String	Optional	Identificador del producto padre de una variante.

Aunque solo product_id es estructuralmente obligatorio, incluye información descriptiva cuando esté disponible para que el modelo tenga información útil sobre tus productos.

Events

Proporciona al menos un mes de historial de eventos. Incluye todas las compras, no solo las compras atribuidas a la publicidad, más los clics e impresiones de productos pagados. Los eventos deben incluir un identificador de comprador consistente para poder conectar las interacciones y las compras. En el conjunto de datos, este identificador se guarda en user_id y debe mantenerse estable entre sesiones y días. Las cargas de eventos son aditivas, lo que permite añadir actividad de períodos adicionales.

Columna	Tipo	Requisito	Descripción
`event_id`	String	Required	Identificador único de la fila del evento. Cada línea de compra tiene su propio identificador.
`event_type`	String	Required	Tipo de actividad. Consulta los valores admitidos más abajo.
`ts`	Datetime	Required	Cuándo ocurrió la actividad, y no cuándo se subió el archivo.
`user_id`	String	Needed to connect shopper activity	Identificador de comprador consistente entre sesiones y días.
`product_id`	String	Where applicable	Producto involucrado en el evento. Puede ser null en eventos de página y de request.
`request_id`	String	Where applicable	Identificador de la request o de la subasta asociado al evento.
`source`	String	Where applicable	`sponsored` u `organic`.
`placement`	String	Optional	Dónde ocurrió la interacción en la página.
`search_term`	String	Optional	Consulta de búsqueda del comprador, decodificada y recortada.
`page_type`	String	Optional	`home`, `category`, `search`, `pdp` u `other`. `pdp` significa página de detalle de producto.
`device`	String	Optional	`mobile` o `desktop`.
`category`	String	Where applicable	Identificador de categoría asociado a la request o a la página.
`order_id`	String	For purchase rows	Agrupa las líneas de producto que pertenecen al mismo pedido.
`quantity`	Integer	For purchase rows	Número de unidades compradas en esa línea.
`unit_price`	Decimal	For purchase rows	Precio pagado por unidad, en las unidades de moneda de tu marketplace.
`product_ids`	List of strings	For request rows	Productos mostrados o considerados en la request.

Tipos de evento admitidos

Valor	Significado
`impression`	Un comprador vio una ubicación de producto.
`click`	Un comprador hizo clic en un producto.
`add_to_cart`	Un comprador añadió un producto a su carrito.
`page_view`	Un comprador vio una página.
`purchase`	Un comprador compró un producto.

Mantén los identificadores consistentes

Usa identificadores exactos y consistentes entre conjuntos de datos:

El product_id de un evento debe coincidir con el product_id del conjunto de datos de productos.
Los valores de category_ids de un producto deben coincidir con el category_id de los registros de categoría.
Usa el mismo user_id para el mismo comprador en interacciones y compras.
Da a cada línea de compra un event_id único y usa order_id para agrupar las líneas del mismo pedido.

Actualizar un conjunto de datos subido

En Data, haz clic en Add Files junto al conjunto de datos que quieres actualizar. Para productos y categorías, proporciona una instantánea completa. Para eventos, añade los nuevos registros de eventos. Cuando el conjunto de datos esté actualizado, vuelve a entrenar cualquier modelo que deba aprender de la información actualizada. Añadir archivos no actualiza automáticamente un modelo ya entrenado.

Usar conjuntos de datos sincronizados de Topsort

Si eres cliente de Topsort, ya habrá tres conjuntos de datos disponibles:

Topsort-categories
Topsort-products
Topsort-events

Estos conjuntos de datos se actualizan en tiempo real. Puedes seleccionarlos al crear una tarea en lugar de subir tú la misma información. Las actualizaciones en tiempo real de los conjuntos de datos no reentrenan automáticamente los modelos desplegados.

Entrenar con tus conjuntos de datos

Ve a Tasks, elige qué quieres que haga el modelo y selecciona los conjuntos de datos relevantes. Por ejemplo, una tarea de ranking de productos usa productos y eventos. Inicia el entrenamiento, sigue el progreso en Training y revisa la calidad del modelo en Evals antes del despliegue.

Privacidad y acceso a los datos

Tus datos subidos y tus modelos con fine-tuning están aislados por minorista. Las políticas de retención y eliminación se pueden configurar según tus requisitos. Habla con un representante de ventas de Topsort para coordinar el acceso. La documentación de la API está disponible bajo solicitud, incluidos la autenticación, los formatos de solicitud y respuesta, la latencia y los límites de tasa.

​Tipos de conjuntos de datos

​Subir datos

​Categories

​Products

​Events

​Tipos de evento admitidos

​Mantén los identificadores consistentes

​Actualizar un conjunto de datos subido

​Usar conjuntos de datos sincronizados de Topsort

​Entrenar con tus conjuntos de datos

​Privacidad y acceso a los datos