README.md

---
language:
  - es
license: apache-2.0
base_model: intfloat/multilingual-e5-small
pipeline_tag: sentence-similarity
library_name: sentence-transformers
tags:
  - sentence-transformers
  - embeddings
  - contrastive-learning
  - e-commerce
  - semantic-search
  - product-recommendation
  - spanish
datasets:
  - Mateo-Rua/pares-productos-ecommerce-es
  - Mateo-Rua/titulos-productos-ecommerce-es
---

# 🔍 Embeddings de Productos para E-commerce en Español

Modelo de embeddings que convierte **títulos de productos en vectores semánticos de 384 dimensiones**,
de forma que productos similares quedan cerca en el espacio vectorial. Diseñado para los tres
pilares de un marketplace moderno como Mercado Libre, Amazon o Falabella:

- 🔎 **Búsqueda semántica** — encuentra productos por significado, no solo por palabras exactas
- 🛒 **Recomendación** — "quien vio esto, también podría querer estos otros"
- 🔗 **Detección de duplicados y agrupación automática de catálogo**

## 💡 Por qué importa

Una búsqueda tradicional falla si el usuario escribe "zapatillas para correr" y el producto
dice "running Nike": no comparten palabras. Este modelo entiende que **significan lo mismo**.
En pruebas reales agrupó zapatillas de marcas distintas bajo el concepto "correr", reconoció
celulares Samsung sin ver la palabra "celular", y distinguió un teclado gamer (Razer, HyperX)
de un teclado musical — matiz que los modelos genéricos confunden.

## 📊 Rendimiento

Se compararon **dos modelos base multilingües**, cada uno antes y después del fine-tuning con
contrastive learning. Métricas de retrieval sobre un test independiente (¿los vecinos más
cercanos de un producto pertenecen a su misma categoría?):

| Modelo | Recall@1 | Recall@5 | Recall@10 | NDCG@10 |
|---|---|---|---|---|
| MiniLM base | 0.401 | 0.566 | 0.641 | 0.493 |
| MiniLM fine-tuned | 0.734 | 0.853 | 0.890 | 0.796 |
| E5 base | 0.562 | 0.753 | 0.802 | 0.656 |
| **E5 fine-tuned (este modelo)** 🏆 | **0.795** | **0.893** | **0.921** | **0.844** |

**Recall@10 de 0.921:** dado un producto, el 92% de las veces hay uno de su misma categoría
entre sus 10 vecinos más cercanos. El fine-tuning mejoró al modelo base en **+23 puntos** de Recall@1.

## 🚀 Uso

```python
from sentence_transformers import SentenceTransformer

modelo = SentenceTransformer("Mateo-Rua/embeddings-productos-ecommerce-es")

productos = [
    "Celular Samsung Galaxy S10 128gb",
    "Zapatillas Nike Running Air Max",
    "Teclado Mecánico Gamer Razer",
]
embeddings = modelo.encode(productos, normalize_embeddings=True)

# Similitud entre productos
similitudes = modelo.similarity(embeddings, embeddings)
print(similitudes)
```

## 🔧 Cómo se entrenó

- **Modelo base:** [intfloat/multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small)
- **Método:** contrastive learning con `MultipleNegativesRankingLoss` — acerca productos de la
  misma categoría y aleja los de categorías distintas (los negativos se generan in-batch)
- **Datos:** [100.000 títulos](https://huggingface.co/datasets/Mateo-Rua/titulos-productos-ecommerce-es)
  en español del MeLi Data Challenge 2019, filtrados por calidad (`reliable`), en 682 categorías →
  [25.797 pares de entrenamiento](https://huggingface.co/datasets/Mateo-Rua/pares-productos-ecommerce-es)
- **Configuración:** 1 época, batch 64 — suficiente para un salto grande de rendimiento sin
  sobreajustar, priorizando la generalización a productos nuevos

## ⚙️ Especificaciones técnicas

- **Tipo:** Sentence Transformer
- **Dimensionalidad de salida:** 384 dimensiones
- **Longitud máxima de secuencia:** 512 tokens
- **Función de similitud:** coseno
- **Modalidad:** texto

```
SentenceTransformer(
  (0): Transformer({'architecture': 'BertModel'})
  (1): Pooling({'embedding_dimension': 384, 'pooling_mode': 'mean'})
  (2): Normalize()
)
```

## ⚠️ Limitaciones

- Optimizado para **títulos cortos de productos** en español; puede rendir distinto en textos largos
- Hereda ambigüedades del catálogo de entrenamiento (términos con doble significado según dominio)
- Datos de 2019: categorías o marcas muy recientes pueden estar subrepresentadas
- Solo español; para portugués se recomienda re-entrenar con datos en ese idioma

## Autor

**Mateo Rúa** — Data Scientist · Medellín, Colombia
[GitHub](https://github.com/Mateo-Rua) · [LinkedIn](https://www.linkedin.com/in/mateo-londono-rua117) · [Hugging Face](https://huggingface.co/Mateo-Rua)