Vector Search Native — Documentación completa

Presentación

Vector Search Native transforma la búsqueda de productos de WooCommerce en un motor semántico. En lugar de comparar palabras clave letra a letra, el plugin convierte cada producto y cada consulta en vectores numéricos (embeddings) mediante un modelo de IA, y luego calcula su similitud de significado. Resultado: un cliente que teclea «chaqueta ligera de algodón para verano» encuentra su «blazer estival de lino», incluso sin ninguna palabra en común.

El plugin soporta tres proveedores de embeddings — OpenAI, Voyage AI y Cohere — intercambiables con un clic, con una indexación incremental que solo llama a la API cuando el contenido de un producto ha cambiado realmente, y un fallback automático a la búsqueda nativa por palabras clave cuando la búsqueda vectorial no es suficiente.

Requisitos

• WordPress 6.2 o superior
• WooCommerce 7.0 o superior (probado hasta 9.4)
• PHP 8.0 o superior
• Una clave API de uno de los tres proveedores: OpenAI, Voyage AI o Cohere
• WP-Cron funcional (o un cron del sistema que llame a wp-cron.php)

Instalación

1. En su back office de WordPress, vaya a Plugins → Añadir nuevo → Subir plugin.
2. Seleccione el archivo vector-search-native.zip y haga clic en Instalar ahora.
3. Haga clic en Activar. El plugin crea automáticamente sus dos tablas (wp_vsn_embeddings y wp_vsn_index_queue) y programa su tarea cron.
4. Aparece un nuevo menú Vector Search bajo WooCommerce.

Configuración del proveedor

Vaya a WooCommerce → Vector Search. La sección «Embedding provider» lista los tres proveedores disponibles. Seleccione el suyo en el desplegable «Active provider», pegue su clave API en el bloque correspondiente, elija un modelo y haga clic en Test connection. Un mensaje verde confirmando la dimensión del vector (por ejemplo «Connection OK. Embedding dimension: 1536») valida la configuración.

Qué modelo elegir

• OpenAI text-embedding-3-small (1536d): la mejor relación calidad-precio, recomendado por defecto.
• OpenAI text-embedding-3-large (3072d): calidad máxima, unas 6 veces más caro.
• Voyage voyage-3 (1024d): excelente retrieval, entrenado para búsqueda.
• Cohere embed-multilingual-v3.0 (1024d): la elección para catálogos multilingües ES/EN/FR/DE/IT.

Indexación inicial

1. En la misma página Vector Search, haga clic en Queue all products for reindex. Todos los productos publicados entran en la cola.
2. Haga clic en Auto-process until done. El plugin procesa la cola por lotes (25 productos por defecto) hasta vaciarla, en directo desde su navegador.
3. Los contadores «Indexed», «Queued» y «Stuck» se actualizan en tiempo real.

También puede dejar que WP-Cron haga el trabajo en segundo plano: la tarea vsn_process_queue se ejecuta según el intervalo configurado (5 minutos por defecto) y vacía progresivamente la cola.

Funcionamiento de la búsqueda

Una vez completada la indexación, la búsqueda de productos de WooCommerce (frontend y widgets estándar) se intercepta automáticamente. El plugin:

1. Convierte la consulta del visitante en vector mediante el proveedor activo (con caché de 10 minutos).
2. Calcula la similitud coseno contra todos los vectores de producto almacenados.
3. Retiene los productos que superan el umbral mínimo de similitud (0,30 por defecto) dentro del límite máximo de candidatos (200 por defecto).
4. Inyecta los IDs ordenados por relevancia en la consulta de WordPress.

Si el número de resultados es inferior al umbral de fallback (3 por defecto), el plugin se aparta y deja que la búsqueda nativa por palabras clave de WooCommerce se ejecute normalmente. Sus visitantes nunca ven una página vacía por un problema del lado IA.

Ajustes avanzados

Contenido indexado

La sección «Content to index» permite elegir los campos incluidos en el embedding: descripción corta, descripción larga, SKU, categorías, etiquetas y atributos. El título del producto siempre se indexa. Reducir los campos puede afinar la relevancia en ciertos catálogos; incluirlos todos maximiza el recall.

Umbrales y candidatos

• Minimum similarity (0,0 – 1,0): por debajo de esta puntuación coseno, un producto se descarta. Suba hacia 0,4 – 0,5 para filtrar agresivamente, baje hacia 0,2 para ampliar.
• Max candidates: número de productos devueltos a WooCommerce tras la ordenación. La paginación se aplica después normalmente.
• Fallback threshold: número mínimo de resultados vectoriales antes de pasar a palabras clave.

Cola y cron

• Cron interval: frecuencia de procesamiento de la cola (1, 5, 15 minutos o cada hora).
• Batch size (1 – 100): productos procesados por tick. Aumente con prudencia para evitar los rate limits del proveedor.
• Cada producto fallido se reintenta hasta 5 veces, conservando el último mensaje de error en la base. El contador «Stuck» señala los productos que agotaron sus intentos.

API REST

Cinco endpoints están expuestos bajo /wp-json/vsn/v1/, todos reservados a usuarios con la capacidad manage_woocommerce:

• POST /reindex — pone todos los productos en cola.
• POST /process — procesa un lote inmediatamente.
• GET /stats — devuelve los contadores (total, indexados, en cola, bloqueados).
• POST /test — prueba una clave API (parámetros: provider, api_key, model).
• POST /clear — vacía por completo el índice de embeddings.

Ejemplo de reindexación completa desde un script de despliegue:

curl -X POST https://su-tienda.es/wp-json/vsn/v1/reindex 
  -u admin:CONTRASENA_DE_APLICACION

Hooks para desarrolladores

vsn_indexed_text

Personaliza el texto enviado al proveedor para cada producto. Ideal para inyectar campos ACF o metadatos de negocio:

add_filter( 'vsn_indexed_text', function ( $text, $product ) {
    $material = get_post_meta( $product->get_id(), 'material', true );
    if ( $material ) {
        $text .= "nMaterial: " . $material;
    }
    return $text;
}, 10, 2 );

vsn_should_engage

Control fino de cuándo se activa la búsqueda vectorial:

// Desactivar la búsqueda vectorial para consultas de una sola palabra.
add_filter( 'vsn_should_engage', function ( $engage, $query ) {
    $s = (string) $query->get( 's' );
    if ( str_word_count( $s ) < 2 ) {
        return false;
    }
    return $engage;
}, 10, 2 );

Tiendas multilingües

Con WPML o Polylang, cada traducción es un producto WordPress distinto: cada una se embedda por tanto por separado, en su propio idioma. Dos recomendaciones:

• Utilice un modelo multilingüe (Cohere embed-multilingual-v3.0 o Voyage voyage-multilingual-2) para que las consultas y las fichas se proyecten en el mismo espacio semántico sea cual sea el idioma.
• Tras añadir un nuevo idioma o una campaña masiva de traducción, lance una reindexación completa para cubrir los nuevos productos.

Solución de problemas

Productos que permanecen en «Stuck»

Un producto pasa a «Stuck» tras 5 fallos consecutivos. Causas frecuentes: clave API inválida o caducada, rate limit del proveedor, o timeout de red. Verifique su clave con Test connection, corrija, y luego haga clic en Queue all products for reindex — esto pone a cero los contadores de intentos.

La búsqueda parece sin cambios

• Verifique que la casilla Enabled está marcada en los ajustes generales.
• Verifique que el contador «Indexed» corresponde a su número de productos.
• Si utiliza un plugin de búsqueda de terceros (FiboSearch, SearchWP…), puede cortocircuitar la consulta estándar de WordPress antes de la intercepción. Desactívelo o contáctenos para un ajuste de integración.

La cola no se vacía sola

WP-Cron solo se dispara con las visitas. En un sitio de poco tráfico, configure un cron del sistema:

*/5 * * * * curl -s https://su-tienda.es/wp-cron.php > /dev/null 2>&1

Desinstalación

Desactivar el plugin suspende el cron pero conserva los datos. Eliminar el plugin desde la página Plugins dispara uninstall.php, que elimina las dos tablas MySQL, la opción de ajustes y las tareas programadas. Sin residuos en la base.

FAQ

¿Puedo usar el plugin sin clave API?

No — la búsqueda semántica requiere un proveedor. Sin clave, el plugin permanece inerte y la búsqueda nativa de WooCommerce sigue funcionando normalmente.

¿Las claves API se exponen del lado cliente?

No. Todas las llamadas a los proveedores se realizan del lado servidor, desde PHP. La clave nunca aparece en el HTML ni en las peticiones del navegador.

¿Qué volumen de catálogo se soporta?

El escaneo coseno en PHP sigue siendo muy rápido hasta unos 50.000 productos en alojamiento compartido estándar. Más allá, contáctenos para hablar de una integración con un índice approximate-nearest-neighbor dedicado.