Semantic Search pour FreeScout
Semantic Search est un module FreeScout autonome qui corrige la recherche multi-mots et, une fois votre propre clé IA ajoutée, trouve les conversations par leur sujet. Il est vendu par les créateurs de ReplyRabbit mais ne nécessite pas l'installation de ReplyRabbit.
Vous cherchez la vue d'ensemble ?
Aperçu
La recherche intégrée de FreeScout recherche l'intégralité de votre requête comme une seule phrase dans un seul champ. Une recherche comme frank invoice ne trouve rien, car le nom du client est à un endroit et le mot "facture" à un autre. Semantic Search remplace ce comportement en deux étapes :
- Mode mot-clé (aucune clé nécessaire) : chaque mot de votre recherche doit apparaître quelque part dans la conversation. L'objet, le nom du client, l'adresse e-mail et le texte des messages comptent tous. Ce mode est actif dès que le module est activé.
- Rechercher par sens (votre propre clé IA) : chaque conversation reçoit une empreinte compacte de son sujet, stockée dans votre base de données FreeScout. Une recherche est mise en correspondance sur le sens et sur les mots-clés, et les deux listes sont combinées afin que la meilleure réponse arrive en premier. Ce mode alimente également la Conversations similaires panneau dans la barre latérale de la conversation.
La page de recherche affiche une petite Sémantique ou Mot-clé étiquette à côté du nombre de résultats afin que les agents sachent quel mode a répondu.
Syntaxe de recherche
L'abréviation habituelle des moteurs de recherche fonctionne dans les deux modes :
| Vous saisissez | Ce qu'il fait |
|---|---|
frank invoice | Les deux mots doivent apparaître quelque part dans la conversation. |
"out of stock" | La phrase exacte doit apparaître. |
-refund ou -"out of stock" | Les conversations contenant le mot ou l'expression sont exclues. |
cart OR basket | Un seul des deux mots suffit. OR doit être en majuscules. |
admin@example.com ou example.com | Une adresse e-mail ou un domaine est mis en correspondance exactement. |
La recherche par sens n'ajoute que les conversations qui portent clairement sur le même sujet que les mots saisis. Les phrases entre guillemets, les adresses et -exclusions s'appliquent toujours à ces résultats, donc une recherche d'une adresse e-mail ne se remplit jamais de conversations sans rapport.
Barre de recherche et filtres
Sur la page des résultats de recherche, la zone de recherche se trouve juste à côté du Conversations et Clients onglets, afin que vous puissiez modifier une recherche sans remonter en haut. La liste déroulante de tri se trouve à droite de la Clients onglet.

Cliquez sur le bouton curseurs à côté de la zone de recherche pour ouvrir le Filtres panneau. Vous n'avez pas besoin de mémoriser l'abréviation ci-dessus : les règles de quatre mots l'écrivent dans le champ de recherche pour vous.
| Filtrer | Ce qu'il écrit | Ce qu'il fait |
|---|---|---|
| Tous ces mots | frank invoice | Chaque mot doit apparaître. |
| Cette phrase exacte | "out of stock" | Les mots doivent apparaître ensemble, dans cet ordre. |
| N'importe lequel de ces mots | cart OR basket | Un seul des mots suffit. |
| Aucun de ces mots | -refund | Les conversations contenant le mot sont exclues. |

Les filtres standard de FreeScout (boîte aux lettres, statut, assigné, client, dates, et plus) se trouvent dans le Avancé section en bas du panneau. Elle est repliée pour garder le panneau compact, et s'ouvre d'elle-même lorsqu'un de ces filtres est déjà utilisé. Un petit chiffre sur le bouton des curseurs indique combien de filtres sont actifs. Cliquez Appliquer pour lancer la recherche, ou Tout effacer pour recommencer.

À partir de 1.1.3, le Clients onglet examine aussi chaque mot individuellement. Si aucun client ne correspond à tous les mots, il liste les clients correspondant à l'un d'eux, les correspondances les plus proches en premier, afin que invoice frank trouve quand même un client nommé Frank.
Prérequis
Avant de commencer, assurez-vous de disposer de :
- FreeScout 1.8.101 ou version ultérieure sur PHP 8.1 ou ultérieur.
- Un worker de file d'attente et un planificateur FreeScout fonctionnels (
php artisan queue:worket leschedule:runcron). L'indexation s'exécute sur ceux-ci. - Une licence Semantic Search de votre Compte ReplyRabbit. L'e-mail d'achat contient la clé de licence.
- Facultatif, pour la recherche par sens : une clé API d'OpenAI ou de Google Gemini, ou l'URL de base et le nom du modèle d'embeddings d'un service compatible comme OpenRouter, Ollama ou LM Studio.
Installez le module
Télécharger le ZIP
Se connecter à app.replyrabbit.app avec l'adresse e-mail que vous avez utilisée lors du paiement et ouvrez le Semantic Search carte sur le tableau de bord. Téléchargezsemantic-search.zip.Copiez-le dans le dossier Modules
Décompressezsemantic-search.zipet copiez leSemanticSearchdossier dans leModulesrépertoire de votre installation FreeScout, via SFTP ou le gestionnaire de fichiers de votre hébergeur, à côté des autres modules. FreeScout n'a pas de téléversement intégré pour les modules tiers.Activez le module
Activer Semantic Search depuis la liste des modules. L'activation exécute les migrations de base de données qui créent les deux tables d'index.Essayer une recherche
Recherchez un nom de client plus un sujet, par exemple un prénom et « facture ». Les résultats correspondent désormais à chaque mot partout où il apparaît dans une conversation, et la page de recherche affiche le Mot-clé étiquette.
Le mode mot-clé fonctionne à ce stade sans configuration supplémentaire. Les étapes ci-dessous débloquent la recherche par sens et le panneau des conversations similaires.
Saisissez la clé de licence
Ouvrez la page des paramètres
Dans FreeScout, allez dans Gérer, puis Paramètres, puis Semantic Search.Collez la clé de licence
Dans le Licence section, collez la clé de votre e-mail d'achat et enregistrez. Le statut affiche Sous licence avec l'heure de la dernière vérification.
La licence est liée à l'URL du site de l'installation FreeScout. Si vous déplacez FreeScout vers un nouveau domaine, contactez hey@replyrabbit.app et nous le réinitialiserons.
Configurez la recherche par sens
Choisir un fournisseur
Dans le Fournisseur d'embedding section, choisissez OpenAI, Google, ou Compatible OpenAI. Le modèle par défaut est renseigné pour OpenAI et Google. Pour un service compatible, saisissez l'URL de base et le nom de modèle qu'il attend.Ajoutez la clé et testez-la
Collez la clé API si votre fournisseur en a besoin, puis cliquez sur Tester les embeddings. Le test envoie une courte phrase à l'endpoint d'embedding et vérifie sa réponse. Les clés sont stockées chiffrées, et seul un aperçu masqué est affiché après l'enregistrement.Choisissez les boîtes aux lettres à indexer
Dans le Indexation section, cochez les boîtes aux lettres à inclure. Inclure les notes internes est activé par défaut, car les agents recherchent souvent leurs propres notes. Définissez Jours de remplissage pour définir jusqu'où remonter dans l'indexation (la valeur par défaut est 365 jours).Activer la recherche par sens
Cochez Rechercher par sens et enregistrez. Si le fournisseur, le modèle ou l'URL de base a changé, la page vous indique que les conversations seront réindexées en arrière-plan.Lancer le premier index
Cliquer Indexer maintenant. Le bloc d'état affiche la progression, par exemple "Indexé 1 240 sur 8 900 (14 %)", l'heure de la dernière exécution, la dernière erreur le cas échéant et le coût restant estimé. L'indexation s'exécute par lots d'environ 200 conversations toutes les cinq minutes, donc un grand centre de support prend quelques heures. La recherche continue de fonctionner pendant tout ce temps.
Quel fournisseur ?
Utilisez un point de terminaison d'embedding personnalisé
Saisissez une URL de base d'API telle que https://embeddings.example.com/v1 ou http://10.0.0.25:8001/v1, suivi de l'ID exact du modèle d'embedding servi à cet endroit. La Recherche sémantique ajoute /embeddings à l'URL de base. Les adresses publiques nécessitent HTTPS. Une adresse HTTP privée ou de bouclage doit se trouver sur un réseau de confiance accessible par FreeScout.
Si une passerelle sert à la fois le chat et les embeddings, vous pouvez saisir la même /v1 URL de base ici et dans Paramètres du fournisseur personnalisé de ReplyRabbit. Configurez le modèle d'embedding ici et le modèle de chat dans ReplyRabbit. Si vos serveurs de chat et d'embedding ont des URL distinctes, saisissez chaque URL dans son propre produit. Les produits ne partagent ni tokens ni paramètres.
Le Tester les embeddings l'action doit renvoyer un vecteur d'embedding. Un modèle de chat qui ne fait que répondre /chat/completions ne peut pas alimenter la recherche par sens. Changer l'endpoint ou le modèle démarre un nouveau profil d'index ; changer uniquement le token conserve les vecteurs existants.


Le maintenir à jour
Lorsqu'une nouvelle version est publiée, FreeScout l'affiche sur Gérer, puis Modules, et Mettre à jour maintenant l'installe sur place : pas de SFTP, pas de nouveau téléversement. Le ZIP que vous avez téléchargé depuis votre tableau de bord contient le lien de téléchargement de votre propre licence, donc la mise à jour est récupérée derrière la même vérification de licence que le premier téléchargement.
Deux choses à savoir :
- La mise à jour ne fonctionne que pour une copie téléchargée depuis votre tableau de bord, et vous ne devez pas transmettre votre copie : son lien de mise à jour contient la clé de téléchargement de votre propre licence, donc quiconque détenant le ZIP pourrait récupérer des mises à jour sur votre licence. Une copie provenant de quelqu'un d'autre est liée à sa licence et se met à jour sur sa clé.
- Si FreeScout signale une erreur de téléchargement, téléchargez le nouveau ZIP depuis votre tableau de bord et remplacez le dossier manuellement, comme dans les étapes d'installation ci-dessus. Votre index et vos paramètres sont conservés : ils résident dans la base de données, pas dans le dossier du module.
Coût
L'indexation envoie le texte de chaque conversation à votre fournisseur une fois, puis à nouveau si la conversation reçoit une nouvelle réponse. La recherche n'envoie que les mots recherchés.
| Fournisseur | Modèle | Prix | Environ 100 conversations |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD par million de tokens | environ 0,01 USD |
| Google Gemini | gemini-embedding-001 | niveau gratuit, puis tarification par token | généralement gratuit |
| Ollama ou LM Studio | n'importe quel modèle d'embeddings | aucun | aucun |
La page des paramètres affiche une estimation pour les conversations encore en attente d'indexation, afin que vous puissiez vérifier le nombre avant de cliquer Indexer maintenant. La réindexation n'a lieu que lorsque vous changez de fournisseur ou de modèle, ou cliquez sur Tout réindexer.
Panneau des conversations similaires
Avec la recherche par le sens activée, un Conversations similaires panneau apparaît dans la barre latérale de la conversation. Il liste les autres conversations de la même boîte aux lettres qui portent sur le même sujet, avec l'objet, le nom du client et la date. Les agents ne voient que les conversations auxquelles ils ont déjà accès.
Désactivez le panneau pour tout le monde avec le Conversations similaires basculez sur la page de paramètres. Une nouvelle conversation affiche « Nothing similar yet » jusqu'à ce qu'elle soit indexée, ce qui prend quelques minutes.

Ligne de commande
Deux commandes aident lorsque vous gérez FreeScout via SSH :
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status affiche les mêmes chiffres de couverture que la page de paramètres. reindex lance un lot immédiatement au lieu d'attendre le planificateur, ce qui est utile pour le premier index sur un grand service.
Dépannage
| Symptôme | Ce qu'il faut vérifier |
|---|---|
| La page de recherche affiche Mot-clé au lieu de Sémantique | Confirmer Rechercher par sens est coché, le statut de la licence est Sous licence, et le bloc d'état n'affiche aucune erreur récente. Si la clé a échoué, la recherche revient au mode mots-clés jusqu'à sa correction. |
| Aucun libellé ne s'affiche du tout sur la page de recherche | La recherche a été confiée à la recherche propre à FreeScout. Cela se produit pour les recherches qui ne sont qu'un nombre (numéros de ticket ou de commande), que le cœur gère déjà bien. |
| Tester les embeddings échoue | Vérifiez que la clé n'a pas d'espaces en début ou en fin et qu'elle appartient au bon fournisseur. Pour un service compatible, confirmez que l'URL de base est accessible depuis le serveur FreeScout et que le nom du modèle d'embeddings correspond exactement à ce que le service attend. |
| L'état indique « Rien d'indexé pour l'instant » | Assurez-vous que le worker de file d'attente et le cron du planificateur sont en cours d'exécution. Cliquez sur Indexer maintenant et actualisez après une minute. Sur un hébergement mutualisé, le premier lot peut prendre quelques minutes avant de démarrer. |
| L'indexation s'arrête en cours de route | Lisez la dernière erreur sur le bloc de statut. Les limites de débit et les erreurs de quota du fournisseur en sont la cause habituelle ; l'indexation reprend à la prochaine exécution planifiée. |
| Les résultats de recherche sont lents sur un très grand centre de support | Le mode mot-clé vérifie chaque mot recherché dans le texte des messages, ce qui est plus lourd que la correspondance sur une seule phrase du cœur. Limitez les recherches à quelques mots, ou réduisez les boîtes aux lettres incluses dans l'indexation. |
| Le panneau des conversations similaires est vide | La conversation n'a pas encore été indexée, ou le panneau est désactivé dans les paramètres. Les nouvelles conversations sont indexées en quelques minutes. |
Confidentialité et traitement des données
La recherche par mot-clé s'exécute entièrement dans votre base de données FreeScout et n'envoie rien nulle part. Avec la recherche par sens activée, le texte de chaque conversation indexée (objet, messages clients, réponses des agents et notes internes si incluses) est envoyé au fournisseur que vous avez configuré. Un endpoint public utilise HTTPS ; un endpoint HTTP privé reste sur le réseau que vous configurez. La clé est facultative pour un endpoint compatible. Seule l'empreinte renvoyée est stockée.
Le seul contact avec replyrabbit.app est la vérification de licence, qui envoie la clé de licence, l'URL du site FreeScout et la version du module. Aucun texte de conversation, mot de recherche ni donnée client ne nous est envoyé.
Si le texte des conversations doit rester sur vos propres serveurs, utilisez un fournisseur local ou un point de terminaison compatible sur votre réseau privé de confiance, ou restez en mode mots-clés. Avec un point de terminaison public compatible, le texte transite par HTTPS. Les points de terminaison HTTP privés ne sont autorisés que sur un réseau de confiance.
FAQ
Ai-je besoin de ReplyRabbit pour utiliser Semantic Search ?
Non. Semantic Search est un module FreeScout distinct des mêmes créateurs. Il s'installe et fonctionne de manière autonome. ReplyRabbit est uniquement l'endroit où vous l'achetez, le téléchargez et gérez la clé de licence.
Semantic Search fonctionne-t-il sans clé IA ?
Oui. Le mode par mots-clés est actif dès l'activation du module, sans clé ni paramètres. Chaque mot de votre recherche doit apparaître quelque part dans la conversation, dans l'objet, le nom du client, l'adresse e-mail ou le texte du message. La clé IA ajoute uniquement la recherche par sens et le panneau des conversations similaires.
Quels fournisseurs IA puis-je utiliser ?
OpenAI (text-embedding-3-small par défaut), Google Gemini (gemini-embedding-001 par défaut), ou tout service compatible OpenAI comme OpenRouter, Ollama ou LM Studio où vous saisissez vous-même l'URL de base et le modèle. Z.AI n'est pas pris en charge car il n'a pas de service d'embeddings.
Combien coûte la clé IA ?
Avec OpenAI text-embedding-3-small à 0,02 USD par million de jetons, indexer environ 100 conversations coûte environ 0,01 USD. Un service avec 10 000 conversations paie environ 1 USD pour tout indexer une fois, puis quelques centimes par mois pour les nouveaux e-mails. La page des paramètres affiche une estimation avant la première exécution de l'indexation.
Où sont stockées les données de recherche ?
Dans deux tables de votre base de données FreeScout existante. Chaque conversation indexée ajoute environ un demi-kilooctet. Aucun serveur de recherche séparé n'est nécessaire, et rien n'est stocké sur replyrabbit.app.
Fonctionne-t-il sur PostgreSQL ?
Oui. La recherche par mots-clés et la recherche par sens fonctionnent toutes deux sur MySQL, MariaDB et PostgreSQL.
Que se passe-t-il si ma clé cesse de fonctionner ou si la licence expire ?
La recherche revient d'elle-même en mode mots-clés, afin que les agents continuent d'obtenir des résultats. La page des paramètres indique la raison. La recherche par mots-clés ne dépend jamais de la licence ni de la clé.