Semantic Search für FreeScout
Semantic Search ist ein eigenständiges FreeScout-Modul, das die Suche mit mehreren Wörtern behebt und, sobald du deinen eigenen KI-Schlüssel hinzufügst, Konversationen nach ihrem Thema findet. Es wird von den Machern von ReplyRabbit verkauft, benötigt aber keine Installation von ReplyRabbit.
Suchen Sie die Übersicht?
Übersicht
Die integrierte Suche von FreeScout sucht Ihre gesamte Abfrage als einen Ausdruck in einem Feld. Eine Suche wie frank invoice findet nichts, weil der Kundenname an einer Stelle steht und das Wort "Rechnung" an einer anderen. Semantic Search ersetzt dieses Verhalten in zwei Stufen:
- Schlüsselwortmodus (kein Schlüssel erforderlich): Jedes Wort Ihrer Suche muss irgendwo in der Unterhaltung vorkommen. Betreff, Kundenname, E-Mail-Adresse und Nachrichtentext zählen alle. Dies ist aktiv, sobald das Modul aktiv ist.
- Nach Bedeutung suchen (Ihr eigener KI-Schlüssel): Jede Unterhaltung erhält einen kompakten Fingerabdruck ihres Themas, der in Ihrer FreeScout-Datenbank gespeichert wird. Eine Suche wird nach Bedeutung und nach Schlüsselwörtern abgeglichen, und die beiden Listen werden so vermischt, dass die beste Antwort zuerst kommt. Dieser Modus treibt auch die Ähnliche Gespräche Panel in der Seitenleiste der Konversation.
Die Suchseite zeigt ein kleines Semantisch oder Schlüsselwort Label neben der Ergebnisanzahl, damit Agenten wissen, welcher Modus geantwortet hat.
Suchsyntax
Die übliche Suchmaschinen-Kurzschrift funktioniert in beiden Modi:
| Sie geben ein | Was es tut |
|---|---|
frank invoice | Beide Wörter müssen irgendwo im Gespräch vorkommen. |
"out of stock" | Der exakte Ausdruck muss erscheinen. |
-refund oder -"out of stock" | Gespräche, die das Wort oder die Phrase enthalten, werden ausgelassen. |
cart OR basket | Eines der beiden Wörter genügt. OR muss in Großbuchstaben sein. |
admin@example.com oder example.com | Eine E-Mail-Adresse oder Domain wird exakt abgeglichen. |
Die Suche nach Bedeutung fügt nur Konversationen hinzu, die eindeutig dasselbe Thema behandeln wie die von dir eingegebenen Wörter. Zitierte Phrasen, Adressen und -exclusions gelten weiterhin für diese Ergebnisse, sodass eine Suche nach einer E-Mail-Adresse nie mit unzusammenhängenden Konversationen gefüllt wird.
Suchleiste und Filter
Auf der Suchergebnisseite sitzt das Suchfeld direkt neben dem Gespräche und Kunden Tabs, sodass Sie eine Suche ändern können, ohne nach oben scrollen zu müssen. Das Sortier-Dropdown befindet sich rechts neben dem Kunden Tab.

Auf die Schieberegler-Schaltfläche neben dem Suchfeld klicken, um das zu öffnen Filter Panel. Sie müssen sich die obige Kurzform nicht merken: Die Vier-Wort-Regeln schreiben sie für Sie in das Suchfeld.
| Filter | Was es schreibt | Was es tut |
|---|---|---|
| Alle diese Wörter | frank invoice | Jedes Wort muss erscheinen. |
| Dieser exakte Ausdruck | "out of stock" | Die Wörter müssen zusammen und in dieser Reihenfolge erscheinen. |
| Eines dieser Wörter | cart OR basket | Eines der Wörter reicht aus. |
| Keines dieser Wörter | -refund | Gespräche mit dem Wort werden ausgelassen. |

Die Standard-FreeScout-Filter (Mailbox, Status, zugewiesen, Kunde, Daten und mehr) befinden sich in der Erweitert Abschnitt am unteren Rand des Panels. Er ist eingeklappt, um das Panel kurz zu halten, und öffnet sich von selbst, wenn einer dieser Filter bereits verwendet wird. Eine kleine Zahl auf der Schieberegler-Schaltfläche zeigt an, wie viele Filter aktiv sind. Klicken Sie auf Anwenden um die Suche auszuführen, oder Alle löschen um erneut zu beginnen.

Ab 1.1.3 die Kunden Tab betrachtet auch jedes Wort einzeln. Wenn kein Kunde zu allen Wörtern passt, listet er Kunden auf, die zu einem der Wörter passen, die nächsten Treffer zuerst, sodass invoice frank findet trotzdem einen Kunden namens Frank.
Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:
- FreeScout 1.8.101 oder neuer auf PHP 8.1 oder später.
- Ein funktionierender FreeScout-Queue-Worker und Scheduler (
php artisan queue:workund dieschedule:runCron). Die Indexierung läuft darauf. - Eine Semantic Search-Lizenz von Ihrem ReplyRabbit-Konto. Die Kauf-E-Mail enthält den Lizenzschlüssel.
- Optional, für die Suche nach Bedeutung: ein API-Schlüssel von OpenAI oder Google Gemini oder die Basis-URL und der Embedding-Modellname eines kompatiblen Dienstes wie OpenRouter, Ollama oder LM Studio.
Installiere das Modul
ZIP herunterladen
Anmelden unter app.replyrabbit.app mit der E-Mail-Adresse, die Sie beim Checkout verwendet haben, und öffnen Sie die Semantic Search Karte im Dashboard. Herunterladensemantic-search.zip.Kopieren Sie es in den Ordner Modules
Entpackensemantic-search.zipund kopieren Sie denSemanticSearchOrdner in denModulesVerzeichnis Ihrer FreeScout-Installation, über SFTP oder den Dateimanager Ihres Hosts, neben den anderen Modulen. FreeScout hat keinen In-App-Upload für Drittanbieter-Module.Aktivieren Sie das Modul
Aktivieren Semantic Search aus der Modulliste. Die Aktivierung führt die Datenbankmigrationen aus, die die beiden Index-Tabellen erstellen.Eine Suche ausprobieren
Suche nach einem Kundennamen plus einem Thema, zum Beispiel einem Vornamen und "Rechnung". Die Ergebnisse stimmen jetzt mit jedem Wort überein, wo immer es in einer Konversation erscheint, und die Suchseite zeigt die Schlüsselwort Label.
Der Schlüsselwortmodus funktioniert an dieser Stelle ohne weitere Einrichtung. Die folgenden Schritte schalten die Suche nach Bedeutung und das Panel für ähnliche Konversationen frei.
Geben Sie den Lizenzschlüssel ein
Öffnen Sie die Einstellungsseite
Gehen Sie in FreeScout zu Verwalten, dann Einstellungen, dann Semantic Search.Fügen Sie den Lizenzschlüssel ein
In der Lizenz Abschnitt, fügen Sie den Schlüssel aus Ihrer Kauf-E-Mail ein und speichern Sie. Der Status zeigt Lizenziert mit dem Zeitpunkt der letzten Prüfung.
Die Lizenz ist an die Site-URL der FreeScout-Installation gebunden. Wenn du FreeScout auf eine neue Domain verschiebst, kontaktiere hey@replyrabbit.app und wir setzen es zurück.
Suche nach Bedeutung einrichten
Einen Anbieter auswählen
In der Embedding-Provider Abschnitt, wählen Sie OpenAI, Google, oder OpenAI-kompatibel. Das Standardmodell ist für OpenAI und Google vorausgefüllt. Geben Sie für einen kompatiblen Dienst die Basis-URL und den erwarteten Modellnamen ein.Fügen Sie den Schlüssel hinzu und testen Sie ihn
Fügen Sie den API-Schlüssel ein, falls Ihr Anbieter einen benötigt, und klicken Sie dann auf Embeddings testen. Der Test sendet einen kurzen Satz an den Embedding-Endpunkt und prüft dessen Antwort. Schlüssel werden verschlüsselt gespeichert, und nach dem Speichern wird nur eine maskierte Vorschau angezeigt.Wählen Sie die zu indexierenden Postfächer
In der Indizierung Abschnitt, aktivieren Sie die Postfächer, die einbezogen werden sollen. Interne Notizen einschließen ist standardmäßig an, weil Agenten oft ihre eigenen Notizen durchsuchen. Setzen Sie Backfill-Tage bis wie weit zurück indexiert werden soll (der Standard ist 365 Tage).Suche nach Bedeutung einschalten
Ankreuzen Nach Bedeutung suchen und speichern Sie. Wenn sich Anbieter, Modell oder Basis-URL geändert haben, teilt Ihnen die Seite mit, dass Konversationen im Hintergrund neu indiziert werden.Ersten Index starten
Klicken Jetzt indizieren. Der Statusblock zeigt den Fortschritt wie "1.240 von 8.900 indiziert (14 %)", die letzte Laufzeit, den letzten Fehler falls vorhanden und die geschätzten verbleibenden Kosten. Die Indizierung läuft in Stapeln von etwa 200 Unterhaltungen alle fünf Minuten, sodass ein großer Desk einige Stunden dauert. Die Suche funktioniert die ganze Zeit weiter.
Welcher Anbieter?
Verwenden Sie einen benutzerdefinierten Embedding-Endpunkt
Geben Sie eine API-Basis-URL ein, z. B. https://embeddings.example.com/v1 oder http://10.0.0.25:8001/v1, gefolgt von der genauen Embedding-Modell-ID, die dort bereitgestellt wird. Semantic Search fügt hinzu /embeddings an die Basis-URL. Öffentliche Adressen erfordern HTTPS. Eine private oder Loopback-HTTP-Adresse muss sich in einem vertrauenswürdigen Netzwerk befinden, das FreeScout erreichen kann.
Wenn ein Gateway sowohl Chat als auch Embeddings bedient, können Sie denselben eingeben /v1 Basis-URL hier und in ReplyRabbits Einstellungen für benutzerdefinierte Anbieter. Konfigurieren Sie das Embedding-Modell hier und das Chat-Modell in ReplyRabbit. Wenn Ihre Chat- und Embedding-Server separate URLs haben, geben Sie jede URL in ihrem eigenen Produkt ein. Die Produkte teilen keine Token oder Einstellungen.
Die Embeddings testen action muss einen Embedding-Vektor zurückgeben. Ein Chat-Modell, das nur antwortet /chat/completions kann die Suche nach Bedeutung nicht betreiben. Das Ändern des Endpunkts oder Modells startet ein neues Indexprofil; das Ändern nur des Tokens behält die vorhandenen Vektoren.


Aktuell halten
Wenn eine neue Version veröffentlicht wird, zeigt FreeScout sie auf Verwalten, dann Module, und Jetzt aktualisieren installiert es direkt: kein SFTP, kein erneuter Upload. Die ZIP-Datei, die Sie aus Ihrem Dashboard heruntergeladen haben, enthält den Download-Link Ihrer eigenen Lizenz, sodass das Update hinter derselben Lizenzprüfung wie der erste Download abgerufen wird.
Zwei Dinge zu wissen:
- Das Update funktioniert nur für eine Kopie, die aus Ihrem Dashboard heruntergeladen wurde, und Sie sollten Ihre Kopie nicht weitergeben: Ihr Update-Link enthält den Download-Schlüssel Ihrer eigenen Lizenz, sodass jeder, der die ZIP hat, Updates auf Ihre Lizenz abrufen könnte. Eine Kopie von jemand anderem ist an dessen Lizenz gebunden und aktualisiert sich mit dessen Schlüssel.
- Wenn FreeScout einen Download-Fehler meldet, laden Sie die neue ZIP-Datei von Ihrem Dashboard herunter und ersetzen Sie den Ordner manuell, wie in den Installationsschritten oben. Ihre Index- und Einstellungen bleiben erhalten: Sie liegen in der Datenbank, nicht im Modulordner.
Kosten
Die Indizierung sendet den Text jeder Konversation einmal an Ihren Anbieter, plus erneut, wenn die Konversation eine neue Antwort erhält. Die Suche sendet nur die Suchwörter.
| Anbieter | Modell | Preis | Etwa 100 Konversationen |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD pro Million Token | etwa 0,01 USD |
| Google Gemini | gemini-embedding-001 | kostenlose Stufe, dann Preis pro Token | normalerweise kostenlos |
| Ollama oder LM Studio | jedes Embedding-Modell | keine | keine |
Die Einstellungsseite zeigt eine Schätzung für die Konversationen, die noch auf die Indexierung warten, sodass Sie die Zahl prüfen können, bevor Sie klicken Jetzt indizieren. Eine Neuindizierung erfolgt nur, wenn Sie den Anbieter oder das Modell ändern oder auf klicken Alles neu indizieren.
Panel für ähnliche Gespräche
Bei aktivierter Suche nach Bedeutung wird ein Ähnliche Gespräche Panel erscheint in der Seitenleiste der Konversation. Es listet andere Konversationen im selben Postfach auf, die dasselbe Thema betreffen, mit Betreff, Kundenname und Datum. Agenten sehen nur Konversationen, auf die sie bereits Zugriff haben.
Schalten Sie das Panel für alle aus mit der Ähnliche Gespräche Schalter auf der Einstellungsseite. Eine neue Konversation zeigt "Nothing similar yet", bis sie indexiert wurde, was einige Minuten dauert.

Kommandozeile
Zwei Befehle helfen, wenn Sie FreeScout über SSH verwalten:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status gibt dieselben Abdeckungszahlen aus wie die Einstellungsseite. reindex führt einen Batch sofort aus, anstatt auf den Scheduler zu warten, was für den ersten Index auf einem großen Desk nützlich ist.
Fehlerbehebung
| Symptom | Was zu prüfen ist |
|---|---|
| Die Suchseite zeigt Schlüsselwort statt Semantisch | Bestätigen Nach Bedeutung suchen angehakt ist, ist der Lizenzstatus Lizenziert, und der Statusblock zeigt keinen aktuellen Fehler. Wenn der Schlüssel fehlgeschlagen ist, fällt die Suche auf den Schlüsselwortmodus zurück, bis er behoben ist. |
| Auf der Suchseite wird überhaupt kein Label angezeigt | Die Suche wurde an FreeScouts eigene Suche übergeben. Das passiert bei Suchen, die nur aus einer Zahl bestehen (Ticket- oder Bestellnummern), die der Kern bereits gut abdeckt. |
| Embeddings testen schlägt fehl | Prüfen, ob der Schlüssel keine führenden oder nachfolgenden Leerzeichen hat und zum richtigen Anbieter gehört. Bei einem kompatiblen Dienst bestätigen, dass die Basis-URL vom FreeScout-Server erreichbar ist und der Name des Embedding-Modells genau dem entspricht, was der Dienst erwartet. |
| Status zeigt "Noch nichts indexiert" | Stellen Sie sicher, dass der Queue-Worker und der Scheduler-Cron laufen. Klicken Sie auf Jetzt indizieren und aktualisieren Sie nach einer Minute. Bei Shared Hosting kann es einige Minuten dauern, bis der erste Batch startet. |
| Indizierung stoppt mittendrin | Lesen Sie den letzten Fehler im Statusblock. Ratenbegrenzungen und Kontingentfehler des Anbieters sind die übliche Ursache; die Indizierung wird beim nächsten geplanten Lauf fortgesetzt. |
| Suchergebnisse sind auf einem sehr großen Desk langsam | Der Schlüsselwortmodus prüft jedes Suchwort gegen den Nachrichtentext, was aufwändiger ist als die Einzelphrasen-Suche des Kerns. Halte Suchen auf wenige Wörter beschränkt oder reduziere die in die Indexierung einbezogenen Postfächer. |
| Panel für ähnliche Gespräche ist leer | Die Konversation wurde noch nicht indexiert, oder das Panel ist in den Einstellungen deaktiviert. Neue Konversationen werden innerhalb weniger Minuten indexiert. |
Datenschutz und Datenverarbeitung
Die Schlüsselwortsuche läuft vollständig in deiner FreeScout-Datenbank und sendet nichts irgendwohin. Bei aktivierter Suche nach Bedeutung wird der Text jeder indexierten Konversation (Betreff, Kundennachrichten, Agentenantworten und interne Notizen, falls einbezogen) an den von dir konfigurierten Anbieter gesendet. Ein öffentlicher Endpunkt verwendet HTTPS; ein privater HTTP-Endpunkt bleibt in dem von dir konfigurierten Netzwerk. Der Schlüssel ist für einen kompatiblen Endpunkt optional. Nur der zurückgegebene Fingerprint wird gespeichert.
Der einzige Kontakt mit replyrabbit.app ist die Lizenzprüfung, die den Lizenzschlüssel, die FreeScout-Site-URL und die Modulversion sendet. Es werden keine Konversationstexte, Suchbegriffe oder Kundendaten an uns gesendet.
Wenn Konversationstext auf Ihren eigenen Servern bleiben muss, verwenden Sie einen lokalen Anbieter oder einen kompatiblen Endpunkt in Ihrem vertrauenswürdigen privaten Netzwerk oder bleiben Sie im Keyword-Modus. Bei einem kompatiblen öffentlichen Endpunkt wird der Text über HTTPS übertragen. Private HTTP-Endpunkte sind nur in einem vertrauenswürdigen Netzwerk zulässig.
FAQ
Brauche ich ReplyRabbit, um Semantic Search zu nutzen?
Nein. Semantic Search ist ein separates FreeScout-Modul derselben Entwickler. Es wird eigenständig installiert und ausgeführt. ReplyRabbit ist nur der Ort, an dem Sie es kaufen, herunterladen und den Lizenzschlüssel verwalten.
Funktioniert Semantic Search ohne KI-Schlüssel?
Ja. Der Keyword-Modus ist ab der Aktivierung des Moduls verfügbar, ohne Schlüssel und ohne Einstellungen. Jedes Wort Ihrer Suche muss irgendwo in der Konversation erscheinen, im Betreff, Kundennamen, in der E-Mail-Adresse oder im Nachrichtentext. Der KI-Schlüssel ergänzt lediglich die Suche nach Bedeutung und das Panel für ähnliche Konversationen.
Welche KI-Anbieter kann ich verwenden?
OpenAI (standardmäßig text-embedding-3-small), Google Gemini (standardmäßig gemini-embedding-001) oder einen beliebigen OpenAI-kompatiblen Dienst wie OpenRouter, Ollama oder LM Studio, bei dem Sie Basis-URL und Modell selbst eingeben. Z.AI wird nicht unterstützt, da es keinen Embeddings-Dienst hat.
Wie viel kostet der KI-Schlüssel?
Mit OpenAI text-embedding-3-small zu 0,02 USD pro Million Tokens kostet die Indexierung von etwa 100 Gesprächen ungefähr 0,01 USD. Ein Desk mit 10.000 Gesprächen zahlt rund 1 USD, um alles einmal zu indexieren, danach ein paar Cent pro Monat für neue E-Mails. Die Einstellungsseite zeigt eine Schätzung, bevor der erste Index läuft.
Wo werden die Suchdaten gespeichert?
In zwei Tabellen innerhalb Ihrer bestehenden FreeScout-Datenbank. Jede indizierte Konversation fügt etwa einen halben Kilobyte hinzu. Es ist kein separater Suchserver erforderlich, und nichts wird auf replyrabbit.app gespeichert.
Funktioniert es auf PostgreSQL?
Ja. Keyword-Suche und Suche nach Bedeutung funktionieren beide auf MySQL, MariaDB und PostgreSQL.
Was passiert, wenn mein Schlüssel nicht mehr funktioniert oder die Lizenz abläuft?
Die Suche fällt selbstständig auf den Keyword-Modus zurück, sodass Agenten weiterhin Ergebnisse erhalten. Die Einstellungsseite zeigt den Grund. Die Keyword-Suche hängt niemals von der Lizenz oder dem Schlüssel ab.