Motor de Recomendaciones IA con Laravel y MongoDB

Motor de Recomendaciones IA con Laravel y MongoDB Atlas Vector Search

En el ecosistema actual del desarrollo web, los sistemas de recomendación de contenido han evolucionado drásticamente más allá de las soluciones basadas en etiquetas o categorías predefinidas. La incorporación de inteligencia artificial mediante embeddings vectoriales representa un salto cualitativo en la capacidad de sugerir contenido contextualmente relevante. Este artículo explora la construcción de un motor de recomendaciones robusto para una API de blog, combinando el poder de Laravel como framework backend, MongoDB Atlas como capa de persistencia y búsqueda vectorial, y los modelos de lenguaje de Hugging Face para la generación de representaciones semánticas del texto.

La premisa fundamental de este enfoque reside en una diferencia conceptual crítica respecto a los motores tradicionales: en lugar de buscar coincidencias por palabras clave o metadatos explícitos, el sistema comprende el significado del contenido. Dos artículos pueden no compartir ninguna palabra en común y, sin embargo, tratar el mismo concepto desde ángulos distintos. Un motor basado en embeddings es capaz de detectar esa similitud semántica latente, lo que resulta en recomendaciones genuinamente útiles para el usuario final.

Fundamentos Técnicos: Embeddings y Búsqueda Vectorial

Un embedding es una representación matemática densa de un fragmento de texto en un espacio vectorial de alta dimensionalidad, típicamente entre 384 y 1536 dimensiones dependiendo del modelo utilizado. Los modelos de Hugging Face, particularmente de la familia sentence-transformers, están optimizados para generar embeddings donde textos con significado similar producen vectores con alta similitud coseno. Este principio es la base operacional de todo el sistema.

MongoDB Atlas Vector Search implementa el algoritmo HNSW (Hierarchical Navigable Small World), una estructura de grafos que permite búsquedas de vecinos más cercanos aproximados (ANN) con una complejidad temporal sublineal. Esto es esencial cuando la colección de artículos crece a miles o millones de documentos, garantizando que las consultas de similitud se ejecuten en milisegundos sin necesidad de calcular la distancia contra cada documento individualmente.

La diferencia entre un motor de recomendaciones semántico y uno basado en etiquetas no es solo técnica: es la diferencia entre un sistema que entiende el contexto y uno que simplemente compara cadenas de texto.

Requisitos Técnicos y Configuración del Entorno

Antes de comenzar la implementación, es necesario disponer de un entorno correctamente configurado. La pila tecnológica requiere componentes específicos que deben estar alineados en versión y compatibilidad para garantizar la estabilidad del sistema en producción.

• PHP 8.2+ con las extensiones mongodb y curl habilitadas
• Laravel 11.x como framework principal de la aplicación
• MongoDB Atlas con un clúster M10 o superior (requerido para Vector Search)
• Composer 2.x para la gestión de dependencias PHP
• Cuenta en Hugging Face con acceso a la Inference API
• Driver oficial de MongoDB para Laravel: mongodb/laravel-mongodb

Creación del Proyecto Laravel e Instalación de Dependencias

El punto de partida es la creación de un proyecto Laravel limpio e instalación de los paquetes necesarios. La integración con MongoDB se realiza a través del paquete oficial mantenido por el equipo de MongoDB, que extiende Eloquent con soporte nativo para documentos y operaciones específicas de MongoDB.

# Crear el proyecto Laravel
composer create-project laravel/laravel blog-recommender

cd blog-recommender

# Instalar el driver de MongoDB para Laravel
composer require mongodb/laravel-mongodb

# Instalar cliente HTTP para comunicación con Hugging Face
composer require guzzlehttp/guzzle

Una vez instaladas las dependencias, es necesario configurar la extensión PHP de MongoDB. En sistemas basados en Ubuntu/Debian, esto se realiza mediante PECL. En entornos Docker, se recomienda partir de imágenes oficiales de PHP que incluyan el soporte para la extensión de forma nativa, evitando inconsistencias entre entornos de desarrollo y producción.

# Instalación de la extensión MongoDB vía PECL
pecl install mongodb

# Agregar al php.ini
echo "extension=mongodb.so" >> /etc/php/8.2/cli/php.ini

Configuración de la Conexión con MongoDB Atlas

La configuración de la conexión se define en el archivo config/database.php, añadiendo un nuevo driver de tipo mongodb. Las credenciales de conexión deben almacenarse en el archivo .env siguiendo las buenas prácticas de seguridad, nunca hardcodeadas en los archivos de configuración versionados.

// config/database.php
'connections' => [
    'mongodb' => [
        'driver'   => 'mongodb',
        'dsn'      => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'blog_recommender'),
    ],
    // ...
],

# .env
MONGODB_URI=mongodb+srv://usuario:password@cluster0.xxxxx.mongodb.net/
MONGODB_DATABASE=blog_recommender
HUGGINGFACE_API_KEY=hf_xxxxxxxxxxxxxxxxxx
HUGGINGFACE_MODEL=sentence-transformers/all-MiniLM-L6-v2

Modelo y Migración para Artículos del Blog

El modelo Article debe extender de MongoDB\Laravel\Eloquent\Model en lugar del Model estándar de Eloquent. Esto habilita todas las capacidades nativas de MongoDB, incluyendo el soporte para campos de tipo array que serán utilizados para almacenar los vectores de embeddings.

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

class Article extends Model
{
    protected $connection = 'mongodb';
    protected $collection = 'articles';

    protected $fillable = [
        'title',
        'content',
        'tags',
        'embedding',        // Vector numérico de 384 dimensiones
        'created_at',
        'updated_at',
    ];

    protected $casts = [
        'embedding' => 'array',
        'tags'      => 'array',
    ];
}

Servicio de Generación de Embeddings con Hugging Face

El núcleo del sistema de recomendaciones reside en la capacidad de transformar texto en vectores numéricos. Se construye un servicio dedicado que encapsula la comunicación con la Inference API de Hugging Face, gestionando la autenticación, el manejo de errores y los reintentos en caso de que el modelo esté en estado de carga inicial (warm-up), algo habitual en los planes gratuitos de la plataforma.

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class EmbeddingService
{
    private string $apiUrl;
    private string $apiKey;

    public function __construct()
    {
        $model = config('services.huggingface.model', 
                         'sentence-transformers/all-MiniLM-L6-v2');
        $this->apiUrl = "https://api-inference.huggingface.co/pipeline/feature-extraction/{$model}";
        $this->apiKey = config('services.huggingface.api_key');
    }

    /**
     * Genera un embedding vectorial para el texto proporcionado.
     *
     * @param  string $text
     * @return array<float>
     * @throws \RuntimeException
     */
    public function generate(string $text): array
    {
        $response = Http::withHeaders([
            'Authorization' => "Bearer {$this->apiKey}",
            'Content-Type'  => 'application/json',
        ])->retry(3, 2000)->post($this->apiUrl, [
            'inputs'  => $text,
            'options' => ['wait_for_model' => true],
        ]);

        if ($response->failed()) {
            Log::error('HuggingFace API error', [
                'status' => $response->status(),
                'body'   => $response->body(),
            ]);
            throw new \RuntimeException('Error al generar el embedding: ' . $response->body());
        }

        $embedding = $response->json();

        // El modelo devuelve un array anidado; extraemos el primer elemento
        return is_array($embedding[0]) ? $embedding[0] : $embedding;
    }
}

Implementación del Motor de Búsqueda Vectorial

Con los embeddings generados y almacenados en MongoDB, el siguiente paso es configurar el índice de búsqueda vectorial en Atlas y construir el servicio que ejecuta las consultas de similitud. El índice debe crearse manualmente desde la consola de Atlas o mediante la API de administración, especificando el campo embedding, el número de dimensiones y el tipo de similitud.

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 384,
      "similarity": "cosine"
    }
  ]
}

<?php

namespace App\Services;

use App\Models\Article;
use MongoDB\Laravel\Eloquent\Builder;

class RecommendationService
{
    public function __construct(
        private readonly EmbeddingService $embeddingService
    ) {}

    /**
     * Obtiene artículos similares basados en similitud vectorial.
     *
     * @param  Article $article  Artículo de referencia
     * @param  int     $limit    Número de recomendaciones
     * @return \Illuminate\Database\Eloquent\Collection
     */
    public function getSimilar(Article $article, int $limit = 5): \Illuminate\Support\Collection
    {
        return Article::raw(function ($collection) use ($article, $limit) {
            return $collection->aggregate([
                [
                    '$vectorSearch' => [
                        'index'          => 'vector_index',
                        'path'           => 'embedding',
                        'queryVector'    => $article->embedding,
                        'numCandidates'  => $limit * 10,
                        'limit'          => $limit + 1, // +1 para excluir el propio artículo
                    ],
                ],
                [
                    '$match' => [
                        '_id' => ['$ne' => $article->_id],
                    ],
                ],
                [
                    '$limit' => $limit,
                ],
                [
                    '$project' => [
                        'title'   => 1,
                        'tags'    => 1,
                        'score'   => ['$meta' => 'vectorSearchScore'],
                        'content' => ['$substr' => ['$content', 0, 200]],
                    ],
                ],
            ]);
        });
    }
}

Controlador y Rutas de la API

La exposición del motor de recomendaciones a través de una API RESTful requiere un controlador que orqueste el flujo completo: recibir la solicitud, recuperar el artículo de referencia, invocar el servicio de recomendaciones y devolver una respuesta estructurada. Se implementa además un mecanismo de caché para evitar recalcular recomendaciones en consultas repetidas sobre el mismo artículo.

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Article;
use App\Services\EmbeddingService;
use App\Services\RecommendationService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Cache;

class ArticleController extends Controller
{
    public function __construct(
        private readonly EmbeddingService    $embeddingService,
        private readonly RecommendationService $recommendationService
    ) {}

    /**
     * Crea un artículo y genera su embedding de forma automática.
     */
    public function store(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'title'   => 'required|string|max:255',
            'content' => 'required|string|min:50',
            'tags'    => 'nullable|array',
        ]);

        // Concatenar título y contenido para un embedding más representativo
        $textToEmbed = $validated['title'] . '. ' . $validated['content'];
        $embedding   = $this->embeddingService->generate($textToEmbed);

        $article = Article::create([
            ...$validated,
            'embedding' => $embedding,
        ]);

        return response()->json($article, 201);
    }

    /**
     * Obtiene recomendaciones para un artículo específico.
     */
    public function recommendations(string $id): JsonResponse
    {
        $article = Article::findOrFail($id);

        $cacheKey       = "recommendations:{$id}";
        $recommendations = Cache::remember($cacheKey, now()->addHours(6), function () use ($article) {
            return $this->recommendationService->getSimilar($article, 5);
        });

        return response()->json([
            'article_id'      => $id,
            'recommendations' => $recommendations,
            'total'           => count($recommendations),
        ]);
    }
}

// routes/api.php
use App\Http\Controllers\Api\ArticleController;

Route::prefix('v1')->group(function () {
    Route::post('/articles', [ArticleController::class, 'store']);
    Route::get('/articles/{id}/recommendations', [ArticleController::class, 'recommendations']);
});

Consideraciones de Rendimiento y Escalabilidad

La generación de embeddings es una operación computacionalmente costosa que no debe ejecutarse de forma síncrona en el ciclo de vida de la solicitud HTTP cuando el volumen de contenido es elevado. La arquitectura recomendada para entornos de producción traslada esta operación a un sistema de colas mediante Laravel Jobs, permitiendo que el endpoint de creación de artículos responda inmediatamente mientras el embedding se genera en segundo plano.

• Queue Jobs: Delegar la generación de embeddings a workers asíncronos usando php artisan queue:work
• Caché distribuida: Implementar Redis para almacenar recomendaciones calculadas y reducir consultas a MongoDB
• Batch processing: Para migrar artículos existentes, usar Article::chunk(100, ...) para procesar en lotes
• Monitoreo de índices: Revisar periódicamente las métricas del índice vectorial en Atlas para ajustar numCandidates
• Versionado de modelos: Almacenar la versión del modelo de embedding usado junto al vector para facilitar migraciones futuras

Un aspecto frecuentemente subestimado es la gestión del ciclo de vida de los embeddings. Cuando el contenido de un artículo se actualiza, el vector almacenado queda desactualizado e introduce ruido semántico en el sistema. La solución correcta es registrar un observer de Eloquent que detecte cambios en los campos title o content y encole automáticamente un job de regeneración del embedding, manteniendo la coherencia del sistema sin intervención manual.

Evaluación de la Calidad de las Recomendaciones

Medir la efectividad de un motor de recomendaciones semántico requiere métricas más sofisticadas que la simple precisión binaria. El score de similitud coseno devuelto por MongoDB Vector Search (accesible mediante $meta: vectorSearchScore) proporciona un valor entre 0 y 1 que indica el grado de afinidad semántica. Se recomienda establecer un umbral mínimo (típicamente 0.7 para el modelo all-MiniLM-L6-v2) por debajo del cual las recomendaciones no se incluyen en la respuesta, independientemente del límite solicitado.

Un sistema que devuelve cinco recomendaciones mediocres es peor que uno que devuelve dos altamente relevantes. La calidad sobre la cantidad debe ser el principio rector en la configuración de los umbrales de similitud.

La combinación de Laravel, MongoDB Atlas Vector Search y los modelos de Hugging Face constituye una pila tecnológica madura y lista para producción que democratiza el acceso a capacidades de búsqueda semántica antes reservadas a grandes organizaciones con equipos de machine learning dedicados. La arquitectura presentada es extensible: el mismo patrón puede aplicarse a sistemas de recomendación de productos en e-commerce, búsqueda semántica en bases de conocimiento corporativas, o detección de contenido duplicado en plataformas de publicación. La clave del éxito reside en la calidad del preprocesamiento del texto, la elección adecuada del modelo de embeddings según el dominio específico, y una configuración cuidadosa de los índices vectoriales en función del volumen de datos esperado.