Semantic Search per FreeScout
Semantic Search è un modulo FreeScout autonomo che corregge la ricerca a più parole e, una volta aggiunta la tua chiave AI, trova le conversazioni in base a ciò di cui parlano. È venduto dai creatori di ReplyRabbit ma non richiede ReplyRabbit installato.
Cerchi la panoramica?
Panoramica
La ricerca integrata di FreeScout cerca l'intera query come un'unica frase in un unico campo. Una ricerca come frank invoice non trova nulla, perché il nome del cliente è in un punto e la parola "fattura" è in un altro. Semantic Search sostituisce quel comportamento in due fasi:
- Modalità parola chiave (nessuna chiave necessaria): ogni parola della tua ricerca deve comparire da qualche parte nella conversazione. Oggetto, nome del cliente, indirizzo email e testo del messaggio contano tutti. Questo è attivo non appena il modulo è attivo.
- Cerca per significato (la tua chiave AI): ogni conversazione riceve un'impronta compatta di ciò di cui tratta, memorizzata nel tuo database FreeScout. Una ricerca viene confrontata per significato e per parole chiave, e i due elenchi vengono combinati in modo che la risposta migliore venga prima. Questa modalità alimenta anche la Conversazioni simili pannello nella barra laterale della conversazione.
La pagina di ricerca mostra una piccola Semantico oppure Parola chiave etichetta accanto al conteggio dei risultati così gli agenti sanno quale modalità ha risposto.
Sintassi di ricerca
La solita scorciatoia dei motori di ricerca funziona in entrambe le modalità:
| Tu digiti | Cosa fa |
|---|---|
frank invoice | Entrambe le parole devono apparire da qualche parte nella conversazione. |
"out of stock" | La frase esatta deve comparire. |
-refund oppure -"out of stock" | Le conversazioni contenenti la parola o la frase vengono escluse. |
cart OR basket | Basta una delle due parole. OR deve essere in maiuscolo. |
admin@example.com oppure example.com | Un indirizzo email o dominio viene confrontato esattamente. |
Cerca per significato aggiunge solo conversazioni che riguardano chiaramente lo stesso argomento delle parole digitate. Frasi tra virgolette, indirizzi e -exclusions si applicano comunque a quei risultati, quindi una ricerca per un indirizzo email non si riempie mai di conversazioni non correlate.
Barra di ricerca e filtri
Nella pagina dei risultati di ricerca, la casella di ricerca si trova proprio accanto al Conversazioni e Clienti schede, così puoi modificare una ricerca senza tornare in cima. Il menu a discesa di ordinamento si trova a destra della Clienti scheda.

Clicca il pulsante dei cursori accanto alla casella di ricerca per aprire il Filtri pannello. Non devi ricordare la scorciatoia sopra: le quattro regole di parole la scrivono nella casella di ricerca per te.
| Filtro | Cosa scrive | Cosa fa |
|---|---|---|
| Tutte queste parole | frank invoice | Ogni parola deve comparire. |
| Questa frase esatta | "out of stock" | Le parole devono comparire insieme, in questo ordine. |
| Una qualsiasi di queste parole | cart OR basket | Basta una delle parole. |
| Nessuna di queste parole | -refund | Le conversazioni con la parola vengono escluse. |

I filtri standard di FreeScout (casella, stato, assegnato, cliente, date e altro) si trovano in Avanzate sezione in fondo al pannello. È ripiegata per mantenere il pannello compatto e si apre da sola quando uno di quei filtri è già in uso. Un piccolo numero sul pulsante dei cursori mostra quanti filtri sono attivi. Fai clic Applica per eseguire la ricerca, oppure Cancella tutto per ricominciare.

Dalla 1.1.3, il Clienti scheda esamina anche ogni parola singolarmente. Se nessun cliente corrisponde a tutte le parole, elenca i clienti che corrispondono a una qualsiasi di esse, con le corrispondenze più vicine per prime, così invoice frank trova comunque un cliente di nome Frank.
Prerequisiti
Prima di iniziare, assicurati di avere:
- FreeScout 1.8.101 o successivo su PHP 8.1 o successivo.
- Un worker e uno scheduler della coda FreeScout funzionanti (
php artisan queue:worke laschedule:runcron). L'indicizzazione viene eseguita su di essi. - Una licenza Semantic Search dal tuo Account ReplyRabbit. L'email di acquisto contiene la chiave di licenza.
- Opzionale, per la ricerca per significato: una chiave API di OpenAI o Google Gemini, oppure l'URL di base e il nome del modello di embedding di un servizio compatibile come OpenRouter, Ollama o LM Studio.
Installa il modulo
Scarica lo ZIP
Accedi su app.replyrabbit.app con l'indirizzo email che hai usato al checkout e apri il Semantic Search scheda sulla dashboard. Scaricasemantic-search.zip.Copialo nella cartella Modules
Decomprimisemantic-search.zipe copia laSemanticSearchcartella nellaModulesdirectory della tua installazione FreeScout, tramite SFTP o il file manager del tuo host, accanto agli altri moduli. FreeScout non ha un caricamento in-app per i moduli di terze parti.Attiva il modulo
Attiva Semantic Search dall'elenco Moduli. L'attivazione esegue le migrazioni del database che creano le due tabelle di indice.Prova una ricerca
Cerca un nome di cliente più un argomento, ad esempio un nome e "fattura". I risultati ora corrispondono a ogni parola ovunque appaia in una conversazione, e la pagina di ricerca mostra il Parola chiave etichetta.
La modalità parola chiave funziona a questo punto senza ulteriori configurazioni. I passaggi seguenti sbloccano la ricerca per significato e il pannello delle conversazioni simili.
Inserisci la chiave di licenza
Apri la pagina delle impostazioni
In FreeScout, vai su Gestisci, poi Impostazioni, poi Semantic Search.Incolla la chiave di licenza
Nel Licenza sezione, incolla la chiave dalla tua email di acquisto e salva. Lo stato mostra Con licenza con l'ora dell'ultimo controllo.
La licenza è legata all'URL del sito dell'installazione FreeScout. Se sposti FreeScout su un nuovo dominio, contatta hey@replyrabbit.app e lo reimposteremo.
Configura la ricerca per significato
Scegli un provider
Nel Provider di embedding sezione, scegli OpenAI, Google, oppure Compatibile con OpenAI. Il modello predefinito è compilato per OpenAI e Google. Per un servizio compatibile, inserisci l'URL di base e il nome del modello che si aspetta.Aggiungi la chiave e testala
Incolla la chiave API se il tuo provider ne richiede una, quindi clicca Verifica gli embedding. Il test invia una breve frase all'endpoint di embedding e controlla la risposta. Le chiavi sono memorizzate crittografate e dopo il salvataggio viene mostrata solo un'anteprima mascherata.Scegli le caselle di posta da indicizzare
Nel Indicizzazione sezione, spunta le caselle di posta da includere. Includi note interne è attivo per impostazione predefinita, perché gli agenti spesso cercano nelle proprie note. Imposta Giorni di backfill per quanto indietro indicizzare (il valore predefinito è 365 giorni).Attiva la ricerca per significato
Spunta Cerca per significato e salva. Se il provider, il modello o l'URL di base sono cambiati, la pagina ti avvisa che le conversazioni verranno reindicizzate in background.Avvia il primo indice
Clicca Indicizza ora. Il blocco di stato mostra l'avanzamento come "Indicizzati 1.240 di 8.900 (14%)", l'ora dell'ultima esecuzione, l'ultimo errore se presente e il costo rimanente stimato. L'indicizzazione viene eseguita in batch di circa 200 conversazioni ogni cinque minuti, quindi un desk grande richiede alcune ore. La ricerca continua a funzionare per tutto il tempo.
Quale provider?
Usa un endpoint di embedding personalizzato
Inserisci un URL di base API come https://embeddings.example.com/v1 oppure http://10.0.0.25:8001/v1, seguito dall'ID esatto del modello di embedding servito lì. La Ricerca semantica aggiunge /embeddings all'URL di base. Gli indirizzi pubblici richiedono HTTPS. Un indirizzo HTTP privato o di loopback deve trovarsi su una rete attendibile raggiungibile da FreeScout.
Se un gateway serve sia chat che embeddings, puoi inserire lo stesso /v1 URL di base qui e in Impostazioni del provider personalizzato di ReplyRabbit. Configura qui il modello di embedding e in ReplyRabbit il modello di chat. Se i tuoi server di chat e di embedding hanno URL separati, inserisci ciascun URL nel proprio prodotto. I prodotti non condividono token o impostazioni.
Il Verifica gli embedding l'azione deve restituire un vettore di embedding. Un modello chat che risponde solo /chat/completions non può alimentare la ricerca per significato. Cambiare l'endpoint o il modello avvia un nuovo profilo di indice; cambiare solo il token mantiene i vettori esistenti.


Mantenerlo aggiornato
Quando viene rilasciata una nuova versione, FreeScout la mostra su Gestisci, poi Moduli, e Aggiorna ora lo installa sul posto: niente SFTP, niente nuovo caricamento. Lo ZIP che hai scaricato dalla tua dashboard contiene il link di download della tua licenza, quindi l'aggiornamento viene recuperato dietro lo stesso controllo di licenza del primo download.
Due cose da sapere:
- L'aggiornamento funziona solo per una copia scaricata dalla tua dashboard, e non dovresti passare la tua copia: il suo link di aggiornamento contiene la chiave di download della tua licenza, quindi chiunque possieda lo ZIP potrebbe scaricare aggiornamenti sulla tua licenza. Una copia di qualcun altro è legata alla sua licenza e si aggiorna con la sua chiave.
- Se FreeScout segnala un errore di download, scarica il nuovo ZIP dalla tua dashboard e sostituisci la cartella manualmente, come nei passaggi di installazione sopra. Il tuo indice e le impostazioni sopravvivono: risiedono nel database, non nella cartella del modulo.
Costo
L'indicizzazione invia il testo di ogni conversazione al tuo provider una volta, più di nuovo se la conversazione riceve una nuova risposta. La ricerca invia solo le parole cercate.
| Provider | Modello | Prezzo | Circa 100 conversazioni |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD per milione di token | circa 0,01 USD |
| Google Gemini | gemini-embedding-001 | piano gratuito, poi prezzo per token | di solito gratuito |
| Ollama o LM Studio | qualsiasi modello di embedding | nessuno | nessuno |
La pagina delle impostazioni mostra una stima per le conversazioni ancora in attesa di indicizzazione, così puoi controllare il numero prima di cliccare Indicizza ora. La reindicizzazione avviene solo quando cambi il provider o il modello, oppure clicchi Reindicizza tutto.
Pannello delle conversazioni simili
Con la ricerca per significato attiva, un Conversazioni simili il pannello appare nella barra laterale della conversazione. Elenca altre conversazioni nella stessa casella di posta che riguardano lo stesso argomento, con oggetto, nome del cliente e data. Gli agenti vedono solo le conversazioni a cui hanno già accesso.
Disattiva il pannello per tutti con il Conversazioni simili attiva nella pagina delle impostazioni. Una nuova conversazione mostra "Nothing similar yet" finché non è stata indicizzata, il che richiede alcuni minuti.

Riga di comando
Due comandi aiutano quando gestisci FreeScout via SSH:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status stampa gli stessi numeri di copertura della pagina delle impostazioni. reindex esegue subito un batch invece di attendere lo scheduler, il che è utile per il primo indice su una scrivania grande.
Risoluzione dei problemi
| Sintomo | Cosa controllare |
|---|---|
| La pagina di ricerca mostra Parola chiave invece di Semantico | Conferma Cerca per significato è spuntato, lo stato della licenza è Con licenza, e il blocco di stato non mostra errori recenti. Se la chiave non funziona, la ricerca torna alla modalità per parole chiave finché non viene risolta. |
| Nessuna etichetta viene mostrata nella pagina di ricerca | La ricerca è stata affidata alla ricerca interna di FreeScout. Questo accade per le ricerche che sono solo un numero (numeri di ticket o d'ordine), che il core gestisce già bene. |
| Verifica gli embedding fallisce | Verifica che la chiave non abbia spazi iniziali o finali e appartenga al provider corretto. Per un servizio compatibile, conferma che l'URL di base sia raggiungibile dal server FreeScout e che il nome del modello di embedding sia esattamente quello atteso dal servizio. |
| Lo stato dice "Niente ancora indicizzato" | Assicurati che il worker della coda e il cron dello scheduler siano in esecuzione. Clicca Indicizza ora e aggiorna dopo un minuto. Su hosting condiviso il primo batch può impiegare qualche minuto per avviarsi. |
| L'indicizzazione si interrompe a metà | Leggi l'ultimo errore nel blocco di stato. I limiti di frequenza e gli errori di quota del provider sono la causa abituale; l'indicizzazione riprende alla prossima esecuzione pianificata. |
| I risultati di ricerca sono lenti su un desk molto grande | La modalità parola chiave verifica ogni parola di ricerca nel testo del messaggio, il che è più oneroso della corrispondenza a singola frase del core. Mantieni le ricerche a poche parole o riduci le caselle di posta incluse nell'indicizzazione. |
| Il pannello delle conversazioni simili è vuoto | La conversazione non è ancora stata indicizzata, oppure il pannello è disattivato nelle impostazioni. Le nuove conversazioni vengono indicizzate entro pochi minuti. |
Privacy e gestione dei dati
La ricerca per parola chiave avviene interamente nel tuo database FreeScout e non invia nulla da nessuna parte. Con la ricerca per significato attiva, il testo di ogni conversazione indicizzata (oggetto, messaggi dei clienti, risposte degli agenti e note interne se incluse) viene inviato al provider che hai configurato. Un endpoint pubblico usa HTTPS; un endpoint HTTP privato resta nella rete che configuri. La chiave è opzionale per un endpoint compatibile. Viene memorizzata solo l'impronta restituita.
L'unico contatto con replyrabbit.app è il controllo della licenza, che invia la chiave di licenza, l'URL del sito FreeScout e la versione del modulo. Nessun testo di conversazione, parola di ricerca o dato del cliente viene inviato a noi.
Se il testo delle conversazioni deve restare sui tuoi server, usa un provider locale o un endpoint compatibile sulla tua rete privata fidata, oppure resta in modalità keyword. Con un endpoint pubblico compatibile, il testo viaggia su HTTPS. Gli endpoint HTTP privati sono consentiti solo su una rete fidata.
FAQ
Devo avere ReplyRabbit per usare Semantic Search?
No. Semantic Search è un modulo FreeScout separato degli stessi creatori. Si installa e funziona in modo autonomo. ReplyRabbit è solo il luogo dove lo acquisti, lo scarichi e gestisci la chiave di licenza.
Semantic Search funziona senza una chiave AI?
Sì. La modalità parola chiave è attiva dal momento in cui attivi il modulo, senza chiave e senza impostazioni. Ogni parola della tua ricerca deve comparire da qualche parte nella conversazione, nell'oggetto, nel nome del cliente, nell'indirizzo email o nel testo del messaggio. La chiave AI aggiunge solo la ricerca per significato e il pannello conversazioni simili.
Quali provider AI posso usare?
OpenAI (text-embedding-3-small per impostazione predefinita), Google Gemini (gemini-embedding-001 per impostazione predefinita), o qualsiasi servizio compatibile con OpenAI come OpenRouter, Ollama o LM Studio in cui inserisci tu stesso l'URL di base e il modello. Z.AI non è supportato perché non dispone di un servizio di embeddings.
Quanto costa la chiave AI?
Con OpenAI text-embedding-3-small a 0,02 USD per milione di token, indicizzare circa 100 conversazioni costa circa 0,01 USD. Un desk con 10.000 conversazioni paga circa 1 USD per indicizzare tutto una volta, poi pochi centesimi al mese per la nuova posta. La pagina delle impostazioni mostra una stima prima che venga eseguito il primo indice.
Dove sono archiviati i dati di ricerca?
In due tabelle all'interno del tuo database FreeScout esistente. Ogni conversazione indicizzata aggiunge circa mezzo kilobyte. Non serve un server di ricerca separato e nulla viene archiviato su replyrabbit.app.
Funziona su PostgreSQL?
Sì. La ricerca per parola chiave e la ricerca per significato funzionano entrambe su MySQL, MariaDB e PostgreSQL.
Cosa succede se la mia chiave smette di funzionare o la licenza scade?
La ricerca torna automaticamente alla modalità per parole chiave, così gli agenti continuano a ottenere risultati. La pagina delle impostazioni mostra il motivo. La ricerca per parole chiave non dipende mai dalla licenza o dalla chiave.