Semantic Search para FreeScout
Semantic Search es un módulo independiente de FreeScout que corrige la búsqueda de varias palabras y, una vez que agregas tu propia clave de IA, encuentra conversaciones por aquello de lo que tratan. Lo venden los creadores de ReplyRabbit pero no necesita ReplyRabbit instalado.
¿Buscas la descripción general?
Resumen
La búsqueda integrada de FreeScout busca toda tu consulta como una sola frase en un solo campo. Una búsqueda como frank invoice no encuentra nada, porque el nombre del cliente está en un sitio y la palabra "invoice" en otro. Semantic Search sustituye ese comportamiento en dos etapas:
- Modo de palabra clave (no se necesita clave): cada palabra de tu búsqueda debe aparecer en algún lugar de la conversación. Cuentan el asunto, el nombre del cliente, la dirección de correo electrónico y el texto del mensaje. Esto está activo en cuanto el módulo está activo.
- Buscar por significado (tu propia clave de IA): cada conversación recibe una huella compacta de su contenido, almacenada en tu base de datos de FreeScout. Una búsqueda se compara por significado y por palabras clave, y las dos listas se combinan para que la mejor respuesta aparezca primero. Este modo también impulsa la Conversaciones similares panel en la barra lateral de la conversación.
La página de búsqueda muestra una pequeña Semántico o Palabra clave etiqueta junto al recuento de resultados para que los agentes sepan qué modo respondió.
Sintaxis de búsqueda
La abreviatura habitual de los motores de búsqueda funciona en ambos modos:
| Tú escribes | Qué hace |
|---|---|
frank invoice | Ambas palabras deben aparecer en algún lugar de la conversación. |
"out of stock" | La frase exacta debe aparecer. |
-refund o -"out of stock" | Las conversaciones que contienen la palabra o frase se excluyen. |
cart OR basket | Cualquiera de las dos palabras es suficiente. OR tiene que ir en mayúsculas. |
admin@example.com o example.com | Una dirección de correo o dominio coincide exactamente. |
Buscar por significado solo agrega conversaciones que tratan claramente de lo mismo que las palabras que escribiste. Las frases entre comillas, las direcciones y -exclusions siguen aplicándose a esos resultados, así que una búsqueda de una dirección de correo electrónico nunca se llena de conversaciones no relacionadas.
Barra de búsqueda y filtros
En la página de resultados de búsqueda, el cuadro de búsqueda está justo al lado del Conversaciones y Clientes pestañas, para que puedas cambiar una búsqueda sin desplazarte de vuelta arriba. El menú desplegable de ordenación está a la derecha de la Clientes pestaña.

Hacer clic en el botón de controles deslizantes junto al cuadro de búsqueda para abrir el Filtros panel. No necesitas recordar la abreviatura anterior: las cuatro reglas de palabras la escriben en el cuadro de búsqueda por ti.
| Filtro | Qué escribe | Qué hace |
|---|---|---|
| Todas estas palabras | frank invoice | Cada palabra debe aparecer. |
| Esta frase exacta | "out of stock" | Las palabras deben aparecer juntas, en este orden. |
| Cualquiera de estas palabras | cart OR basket | Basta con una de las palabras. |
| Ninguna de estas palabras | -refund | Las conversaciones con la palabra se excluyen. |

Los filtros estándar de FreeScout (buzón, estado, asignado, cliente, fechas y más) están en el Avanzado sección en la parte inferior del panel. Está plegada para mantener el panel corto, y se abre sola cuando uno de esos filtros ya está en uso. Un pequeño número en el botón de controles deslizantes muestra cuántos filtros están activos. Haz clic en Aplicar para ejecutar la búsqueda, o Borrar todo para empezar de nuevo.

Desde la 1.1.3, el Clientes pestaña también examina cada palabra por separado. Si ningún cliente coincide con todas las palabras, enumera los clientes que coinciden con cualquiera de ellas, primero las coincidencias más cercanas, para que invoice frank sigue encontrando a un cliente llamado Frank.
Requisitos previos
Antes de empezar, asegúrate de tener:
- FreeScout 1.8.101 o posterior en PHP 8.1 o posterior.
- Un worker y un planificador de cola de FreeScout en funcionamiento (
php artisan queue:worky elschedule:runcron). La indexación se ejecuta en ellos. - Una licencia de Semantic Search de tu Cuenta de ReplyRabbit. El correo de compra contiene la clave de licencia.
- Opcional, para búsqueda por significado: una clave de API de OpenAI o Google Gemini, o la URL base y el nombre del modelo de embeddings de un servicio compatible como OpenRouter, Ollama o LM Studio.
Instala el módulo
Descargar el ZIP
Inicia sesión en app.replyrabbit.app con la dirección de correo electrónico que usaste al pagar y abre el Semantic Search tarjeta en el panel. Descargasemantic-search.zip.Cópialo en la carpeta Modules
Descomprimesemantic-search.zipy copia elSemanticSearchcarpeta en laModulesdirectorio de tu instalación de FreeScout, por SFTP o el gestor de archivos de tu host, junto a los demás módulos. FreeScout no tiene carga desde la aplicación para módulos de terceros.Activa el módulo
Activar Semantic Search desde la lista de Módulos. La activación ejecuta las migraciones de base de datos que crean las dos tablas de índice.Prueba una búsqueda
Busca un nombre de cliente más un tema, por ejemplo un nombre y "factura". Los resultados ahora coinciden con cada palabra dondequiera que aparezca en una conversación, y la página de búsqueda muestra el Palabra clave etiqueta.
El modo de palabra clave funciona en este punto sin configuración adicional. Los pasos siguientes desbloquean la búsqueda por significado y el panel de conversaciones similares.
Introduce la clave de licencia
Abre la página de ajustes
En FreeScout, ve a Gestionar, luego Configuración, luego Semantic Search.Pega la clave de licencia
En el Licencia sección, pega la clave de tu correo de compra y guarda. El estado muestra Con licencia con la hora de la última comprobación.
La licencia está vinculada a la URL del sitio de la instalación de FreeScout. Si mueves FreeScout a un nuevo dominio, contacta con hey@replyrabbit.app y lo restableceremos.
Configura la búsqueda por significado
Elegir un proveedor
En el Proveedor de embeddings sección, elige OpenAI, Google, o Compatible con OpenAI. El modelo predeterminado se rellena para OpenAI y Google. Para un servicio compatible, introduce la URL base y el nombre del modelo que espera.Añade la clave y pruébala
Pega la clave de API si tu proveedor necesita una y luego haz clic en Probar embeddings. La prueba envía una frase corta al endpoint de embeddings y comprueba su respuesta. Las claves se almacenan cifradas y solo se muestra una vista previa enmascarada tras guardar.Elige los buzones que indexar
En el Indexando sección, marca los buzones que deseas incluir. Incluir notas internas está activado por defecto, porque los agentes suelen buscar en sus propias notas. Configura Días de relleno hasta qué punto atrás indexar (el valor predeterminado es 365 días).Activa la búsqueda por significado
Marca Buscar por significado y guarda. Si el proveedor, el modelo o la URL base cambiaron, la página te indica que las conversaciones se reindexarán en segundo plano.Inicia el primer índice
Hacer clic Indexar ahora. El bloque de estado muestra el progreso, como "Indexadas 1.240 de 8.900 (14%)", la hora de la última ejecución, el último error si lo hay y el coste restante estimado. La indexación se ejecuta en lotes de unas 200 conversaciones cada cinco minutos, así que un escritorio grande tarda unas horas. La búsqueda sigue funcionando todo el tiempo.
¿Qué proveedor?
Usa un endpoint de embeddings personalizado
Introduce una URL base de API como https://embeddings.example.com/v1 o http://10.0.0.25:8001/v1, seguido del ID exacto del modelo de embeddings servido allí. La Búsqueda semántica añade /embeddings a la URL base. Las direcciones públicas requieren HTTPS. Una dirección HTTP privada o de bucle invertido debe estar en una red de confianza a la que FreeScout pueda acceder.
Si una pasarela sirve tanto el chat como los embeddings, puedes introducir el mismo /v1 URL base aquí y en Configuración del proveedor personalizado de ReplyRabbit. Configura aquí el modelo de embeddings y el modelo de chat en ReplyRabbit. Si tus servidores de chat y de embeddings tienen URL separadas, introduce cada URL en su propio producto. Los productos no comparten tokens ni ajustes.
El Probar embeddings la acción debe devolver un vector de embedding. Un modelo de chat que solo responde /chat/completions no puede impulsar la búsqueda por significado. Cambiar el endpoint o el modelo inicia un nuevo perfil de índice; cambiar solo el token mantiene los vectores existentes.


Mantenerlo actualizado
Cuando se publica una nueva versión, FreeScout la muestra en Gestionar, luego Módulos, y Actualizar ahora lo instala en su sitio: sin SFTP, sin volver a subir. El ZIP que descargaste de tu panel lleva el enlace de descarga de tu propia licencia, así que la actualización se obtiene tras la misma comprobación de licencia que la primera descarga.
Dos cosas que debes saber:
- La actualización solo funciona para una copia descargada desde tu panel, y no debes pasar tu copia: su enlace de actualización contiene la clave de descarga de tu propia licencia, así que cualquiera que tenga el ZIP podría obtener actualizaciones con tu licencia. Una copia de otra persona está vinculada a su licencia y se actualiza con su clave.
- Si FreeScout informa un error de descarga, descarga el nuevo ZIP desde tu panel y reemplaza la carpeta manualmente, como en los pasos de instalación anteriores. Tu índice y tu configuración se conservan: viven en la base de datos, no en la carpeta del módulo.
Coste
La indexación envía el texto de cada conversación a tu proveedor una vez, y de nuevo si la conversación recibe una nueva respuesta. La búsqueda envía solo las palabras de búsqueda.
| Proveedor | Modelo | Precio | Unas 100 conversaciones |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD por millón de tokens | aproximadamente 0.01 USD |
| Google Gemini | gemini-embedding-001 | nivel gratuito, luego precio por token | normalmente gratis |
| Ollama o LM Studio | cualquier modelo de embeddings | ninguno | ninguno |
La página de ajustes muestra una estimación de las conversaciones que aún esperan ser indexadas, para que puedas comprobar el número antes de hacer clic en Indexar ahora. La reindexación solo ocurre cuando cambias el proveedor o el modelo, o haces clic en Reindexar todo.
Panel de conversaciones similares
Con la búsqueda por significado activada, una Conversaciones similares aparece un panel en la barra lateral de la conversación. Enumera otras conversaciones del mismo buzón que tratan sobre lo mismo, con el asunto, el nombre del cliente y la fecha. Los agentes solo ven conversaciones a las que ya tienen acceso.
Desactiva el panel para todos con el Conversaciones similares actívalo en la página de configuración. Una nueva conversación muestra "Aún nada similar" hasta que se haya indexado, lo que tarda unos minutos.

Línea de comandos
Dos comandos ayudan cuando gestionas FreeScout por SSH:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status muestra los mismos números de cobertura que la página de configuración. reindex ejecuta un lote de inmediato en lugar de esperar al programador, lo que es útil para el primer índice en un escritorio grande.
Resolución de problemas
| Síntoma | Qué comprobar |
|---|---|
| La página de búsqueda muestra Palabra clave en lugar de Semántico | Confirmar Buscar por significado está marcado, el estado de la licencia es Con licencia, y el bloque de estado no muestra ningún error reciente. Si la clave falló, la búsqueda recurre al modo de palabras clave hasta que se corrija. |
| No se muestra ninguna etiqueta en la página de búsqueda | La búsqueda se delegó a la búsqueda propia de FreeScout. Esto ocurre con búsquedas que son solo un número (números de ticket o de pedido), que el núcleo ya maneja bien. |
| Probar embeddings falla | Comprobar que la clave no tiene espacios al principio ni al final y que pertenece al proveedor correcto. Para un servicio compatible, confirmar que la URL base es accesible desde el servidor de FreeScout y que el nombre del modelo de embeddings es exactamente lo que espera el servicio. |
| El estado dice "Aún no hay nada indexado" | Asegúrate de que el trabajador de la cola y el cron del programador estén en ejecución. Haz clic en Indexar ahora y actualiza después de un minuto. En alojamiento compartido, el primer lote puede tardar unos minutos en comenzar. |
| La indexación se detiene a mitad | Lea el último error en el bloque de estado. Los límites de velocidad y los errores de cuota del proveedor suelen ser la causa; la indexación se reanuda en la siguiente ejecución programada. |
| Los resultados de búsqueda son lentos en un escritorio muy grande | El modo de palabra clave comprueba cada palabra de búsqueda contra el texto del mensaje, lo que es más pesado que la coincidencia de frase única del núcleo. Limita las búsquedas a unas pocas palabras o reduce los buzones incluidos en la indexación. |
| El panel de conversaciones similares está vacío | La conversación aún no se ha indexado, o el panel está desactivado en la configuración. Las conversaciones nuevas se indexan en unos minutos. |
Privacidad y tratamiento de datos
La búsqueda por palabra clave se ejecuta completamente dentro de tu base de datos de FreeScout y no envía nada a ningún sitio. Con la búsqueda por significado activada, el texto de cada conversación indexada (asunto, mensajes del cliente, respuestas del agente y notas internas si se incluyen) se envía al proveedor que configuraste. Un endpoint público usa HTTPS; un endpoint HTTP privado permanece en la red que configures. La clave es opcional para un endpoint compatible. Solo se almacena la huella devuelta.
El único contacto con replyrabbit.app es la comprobación de licencia, que envía la clave de licencia, la URL del sitio de FreeScout y la versión del módulo. No se nos envía texto de conversaciones, palabras de búsqueda ni datos de clientes.
Si el texto de las conversaciones debe permanecer en tus propios servidores, usa un proveedor local o un endpoint compatible en tu red privada de confianza, o quédate en el modo de palabras clave. Con un endpoint público compatible, el texto viaja por HTTPS. Los endpoints HTTP privados solo se permiten en una red de confianza.
Preguntas frecuentes
¿Necesito ReplyRabbit para usar Semantic Search?
No. Semantic Search es un módulo de FreeScout independiente de los mismos creadores. Se instala y funciona por sí solo. ReplyRabbit es solo donde lo compras, lo descargas y gestionas la clave de licencia.
¿Semantic Search funciona sin una clave de IA?
Sí. El modo de palabras clave está activo desde el momento en que activas el módulo, sin clave y sin configuración. Cada palabra de tu búsqueda tiene que aparecer en algún lugar de la conversación, en el asunto, el nombre del cliente, la dirección de correo electrónico o el texto del mensaje. La clave de IA solo añade la búsqueda por significado y el panel de conversaciones similares.
¿Qué proveedores de IA puedo usar?
OpenAI (text-embedding-3-small por defecto), Google Gemini (gemini-embedding-001 por defecto), o cualquier servicio compatible con OpenAI como OpenRouter, Ollama o LM Studio donde introduces tú mismo la URL base y el modelo. Z.AI no es compatible porque no tiene servicio de embeddings.
¿Cuánto cuesta la clave de IA?
Con OpenAI text-embedding-3-small a 0.02 USD por millón de tokens, indexar unas 100 conversaciones cuesta aproximadamente 0.01 USD. Un servicio con 10,000 conversaciones paga alrededor de 1 USD por indexarlo todo una vez, y luego unos pocos centavos al mes por el correo nuevo. La página de ajustes muestra una estimación antes de que se ejecute la primera indexación.
¿Dónde se almacenan los datos de búsqueda?
En dos tablas dentro de tu base de datos de FreeScout existente. Cada conversación indexada añade aproximadamente medio kilobyte. No se necesita un servidor de búsqueda separado y nada se almacena en replyrabbit.app.
¿Funciona en PostgreSQL?
Sí. La búsqueda por palabras clave y la búsqueda por significado funcionan tanto en MySQL, MariaDB como en PostgreSQL.
¿Qué pasa si mi clave deja de funcionar o la licencia caduca?
La búsqueda vuelve al modo de palabras clave por sí sola, para que los agentes sigan obteniendo resultados. La página de configuración muestra el motivo. La búsqueda por palabras clave nunca depende de la licencia ni de la clave.