Semantic Search para FreeScout
O Semantic Search é um módulo autônomo do FreeScout que corrige a pesquisa com várias palavras e, depois que você adiciona sua própria chave de IA, encontra conversas pelo assunto delas. Ele é vendido pelos criadores do ReplyRabbit, mas não precisa do ReplyRabbit instalado.
Procurando a visão geral?
Visão geral
A pesquisa integrada do FreeScout procura toda a sua consulta como uma única frase em um único campo. Uma pesquisa como frank invoice não encontra nada, porque o nome do cliente está em um lugar e a palavra "invoice" está em outro. O Semantic Search substitui esse comportamento em duas etapas:
- Modo palavra-chave (nenhuma chave necessária): cada palavra da sua busca deve aparecer em algum lugar da conversa. Assunto, nome do cliente, endereço de e-mail e texto da mensagem contam. Isto fica ativo assim que o módulo está ativo.
- Pesquisar por significado (sua própria chave de IA): cada conversa recebe uma impressão digital compacta do seu tema, armazenada no seu banco de dados do FreeScout. Uma busca é correspondida por significado e por palavras-chave, e as duas listas são combinadas para que a melhor resposta venha primeiro. Este modo também alimenta a Conversas semelhantes painel na barra lateral da conversa.
A página de pesquisa mostra um pequeno Semântico ou Palavra-chave rótulo ao lado da contagem de resultados para que os agentes saibam qual modo respondeu.
Sintaxe de pesquisa
A abreviação usual de mecanismos de busca funciona em ambos os modos:
| Você digita | O que ele faz |
|---|---|
frank invoice | Ambas as palavras devem aparecer em algum lugar da conversa. |
"out of stock" | A frase exata deve aparecer. |
-refund ou -"out of stock" | Conversas que contêm a palavra ou frase são omitidas. |
cart OR basket | Qualquer uma das palavras é suficiente. OR deve estar em maiúsculas. |
admin@example.com ou example.com | Um endereço de e-mail ou domínio é correspondido exatamente. |
Pesquisar por significado só adiciona conversas que tratam claramente do mesmo assunto que as palavras digitadas. Frases entre aspas, endereços e -exclusions ainda se aplicam a esses resultados, então uma busca por um endereço de e-mail nunca se enche de conversas não relacionadas.
Barra de pesquisa e filtros
Na página de resultados de pesquisa, a caixa de pesquisa fica bem ao lado do Conversas e Clientes abas, para que você possa alterar uma busca sem rolar de volta ao topo. O menu suspenso de ordenação fica à direita do Clientes aba.

Clique no botão de controles deslizantes ao lado da caixa de pesquisa para abrir o Filtros painel. Você não precisa lembrar da abreviação acima: as quatro regras de palavras a escrevem na caixa de busca para você.
| Filtro | O que ele escreve | O que ele faz |
|---|---|---|
| Todas estas palavras | frank invoice | Cada palavra deve aparecer. |
| Esta frase exata | "out of stock" | As palavras devem aparecer juntas, nesta ordem. |
| Qualquer uma destas palavras | cart OR basket | Uma das palavras é suficiente. |
| Nenhuma destas palavras | -refund | Conversas com a palavra são omitidas. |

Os filtros padrão do FreeScout (caixa de correio, status, atribuído, cliente, datas e mais) ficam no Avançado seção na parte inferior do painel. Ela fica recolhida para manter o painel curto e abre sozinha quando um desses filtros já está em uso. Um pequeno número no botão de controles deslizantes mostra quantos filtros estão ativos. Clique Aplicar para executar a busca, ou Limpar tudo para começar de novo.

A partir da 1.1.3, o Clientes aba também analisa cada palavra individualmente. Se nenhum cliente corresponder a todas as palavras, ela lista clientes que correspondem a qualquer uma delas, com as correspondências mais próximas primeiro, então invoice frank ainda encontra um cliente chamado Frank.
Pré-requisitos
Antes de começar, certifique-se de ter:
- FreeScout 1.8.101 ou mais recente no PHP 8.1 ou posterior.
- Um worker de fila e agendador do FreeScout em funcionamento (
php artisan queue:worke oschedule:runcron). A indexação é executada neles. - Uma licença do Semantic Search do seu Conta ReplyRabbit. O e-mail de compra contém a chave de licença.
- Opcional, para busca por significado: uma chave de API do OpenAI ou Google Gemini, ou a URL base e o nome do modelo de embeddings de um serviço compatível, como OpenRouter, Ollama ou LM Studio.
Instale o módulo
Baixar o ZIP
Entre em app.replyrabbit.app com o endereço de e-mail que você usou no checkout e abra o Semantic Search cartão no painel. Baixesemantic-search.zip.Copie para a pasta Modules
Descompactesemantic-search.zipe copie oSemanticSearchpasta para aModulesdiretório da sua instalação do FreeScout, via SFTP ou pelo gerenciador de arquivos do seu host, ao lado dos outros módulos. O FreeScout não tem upload no aplicativo para módulos de terceiros.Ative o módulo
Ativar Semantic Search da lista de Módulos. A ativação executa as migrações de banco de dados que criam as duas tabelas de índice.Faça uma pesquisa
Pesquise por um nome de cliente mais um tópico, por exemplo um primeiro nome e "fatura". Os resultados agora correspondem a cada palavra onde quer que ela apareça em uma conversa, e a página de pesquisa mostra o Palavra-chave rótulo.
O modo palavra-chave funciona neste ponto sem configuração adicional. As etapas abaixo desbloqueiam a busca por significado e o painel de conversas semelhantes.
Digite a chave de licença
Abra a página de configurações
No FreeScout, vá para Gerenciar, então Configurações, então Semantic Search.Cole a chave de licença
No Licença seção, cole a chave do seu e-mail de compra e salve. O status mostra Licenciado com o horário da última verificação.
A licença está vinculada à URL do site da instalação do FreeScout. Se você mover o FreeScout para um novo domínio, entre em contato hey@replyrabbit.app e nós o redefiniremos.
Configure a busca por significado
Escolha um provedor
No Provedor de embeddings seção, escolha OpenAI, Google, ou Compatível com OpenAI. O modelo padrão é preenchido para OpenAI e Google. Para um serviço compatível, insira a URL base e o nome do modelo que ele espera.Adicione a chave e teste-a
Cole a chave de API se o seu provedor precisar de uma e clique em Testar embeddings. O teste envia uma frase curta ao endpoint de embedding e verifica sua resposta. As chaves são armazenadas criptografadas, e apenas uma prévia mascarada é mostrada após salvar.Escolha as caixas de correio a indexar
No Indexando seção, marque as caixas de correio a incluir. Incluir notas internas está ativado por padrão, porque os agentes costumam pesquisar suas próprias notas. Defina Dias de preenchimento retroativo até onde voltar na indexação (o padrão é 365 dias).Ative a pesquisa por significado
Marque Pesquisar por significado e salve. Se o provedor, modelo ou URL base mudou, a página informa que as conversas serão reindexadas em segundo plano.Inicie o primeiro índice
Clique Indexar agora. O bloco de status mostra o progresso, como "Indexed 1,240 of 8,900 (14%)", a hora da última execução, o último erro, se houver, e o custo restante estimado. A indexação é executada em lotes de cerca de 200 conversas a cada cinco minutos, então uma central grande leva algumas horas. A busca continua funcionando o tempo todo.
Qual provedor?
Use um endpoint de embeddings personalizado
Digite uma URL base de API como https://embeddings.example.com/v1 ou http://10.0.0.25:8001/v1, seguido do ID exato do modelo de embedding servido ali. A Pesquisa Semântica adiciona /embeddings para a URL base. Endereços públicos exigem HTTPS. Um endereço HTTP privado ou de loopback deve estar em uma rede confiável que o FreeScout possa alcançar.
Se um gateway atender tanto chat quanto embeddings, você pode inserir a mesma /v1 URL base aqui e em Configurações de provedor personalizado do ReplyRabbit. Configure o modelo de embedding aqui e o modelo de chat no ReplyRabbit. Se seus servidores de chat e de embedding tiverem URLs separadas, insira cada URL em seu próprio produto. Os produtos não compartilham tokens nem configurações.
O Testar embeddings a ação deve retornar um vetor de embedding. Um modelo de chat que apenas responde /chat/completions não pode alimentar a busca por significado. Alterar o endpoint ou o modelo inicia um novo perfil de índice; alterar apenas o token mantém os vetores existentes.


Mantendo atualizado
Quando uma nova versão é lançada, o FreeScout a mostra em Gerenciar, então Módulos, e Atualizar agora instala no local: sem SFTP, sem novo upload. O ZIP que você baixou do seu painel carrega o link de download da sua própria licença, então a atualização é buscada por trás da mesma verificação de licença do primeiro download.
Duas coisas a saber:
- A atualização só funciona para uma cópia baixada do seu painel, e você não deve repassar sua cópia: o link de atualização contém a chave de download da sua própria licença, então qualquer pessoa com o ZIP poderia buscar atualizações na sua licença. Uma cópia de outra pessoa está vinculada à licença dela e atualiza com a chave dela.
- Se o FreeScout reportar um erro de download, baixe o novo ZIP do seu painel e substitua a pasta manualmente, como nas etapas de instalação acima. Seu índice e configurações sobrevivem: eles ficam no banco de dados, não na pasta do módulo.
Custo
A indexação envia o texto de cada conversa ao seu provedor uma vez, e novamente se a conversa receber uma nova resposta. A busca envia apenas as palavras de busca.
| Provedor | Modelo | Preço | Cerca de 100 conversas |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 0,02 USD por milhão de tokens | aproximadamente 0,01 USD |
| Google Gemini | gemini-embedding-001 | nível gratuito, depois preço por token | geralmente gratuito |
| Ollama ou LM Studio | qualquer modelo de embeddings | nenhum | nenhum |
A página de configurações mostra uma estimativa para as conversas que ainda aguardam indexação, para que você possa verificar o número antes de clicar Indexar agora. A reindexação só acontece quando você muda o provedor ou modelo, ou clica em Reindexar tudo.
Painel de conversas semelhantes
Com a pesquisa por significado ativada, um Conversas semelhantes painel aparece na barra lateral da conversa. Ele lista outras conversas na mesma caixa de correio que tratam do mesmo assunto, com o assunto, o nome do cliente e a data. Os agentes só veem conversas às quais já têm acesso.
Desative o painel para todos com o Conversas semelhantes ative na página de configurações. Uma nova conversa mostra "Nothing similar yet" até ser indexada, o que leva alguns minutos.

Linha de comando
Dois comandos ajudam quando você gerencia o FreeScout via SSH:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status imprime os mesmos números de cobertura da página de configurações. reindex executa um lote imediatamente em vez de esperar o agendador, o que é útil para o primeiro índice em uma mesa grande.
Solução de problemas
| Sintoma | O que verificar |
|---|---|
| A página de pesquisa mostra Palavra-chave em vez de Semântico | Confirmar Pesquisar por significado está marcado, o status da licença é Licenciado, e o bloco de status não mostra nenhum erro recente. Se a chave falhou, a busca recorre ao modo de palavras-chave até que seja corrigida. |
| Nenhum rótulo aparece na página de pesquisa | A pesquisa foi encaminhada para a pesquisa própria do FreeScout. Isso acontece para pesquisas que são apenas um número (números de ticket ou pedido), que o núcleo já trata bem. |
| Testar embeddings falha | Verifique se a chave não tem espaços no início ou no fim e se pertence ao provedor correto. Para um serviço compatível, confirme se a URL base é acessível a partir do servidor do FreeScout e se o nome do modelo de embeddings é exatamente o que o serviço espera. |
| O status diz "Nada indexado ainda" | Certifique-se de que o worker da fila e o cron do agendador estejam em execução. Clique em Indexar agora e atualize após um minuto. Em hospedagem compartilhada, o primeiro lote pode levar alguns minutos para começar. |
| A indexação para no meio | Leia o último erro no bloco de status. Limites de taxa e erros de cota do provedor são a causa habitual; a indexação é retomada na próxima execução agendada. |
| Os resultados da pesquisa estão lentos em um desk muito grande | O modo palavra-chave verifica cada palavra de busca no texto da mensagem, o que é mais pesado que a correspondência de frase única do núcleo. Mantenha as buscas com poucas palavras ou reduza as caixas de correio incluídas na indexação. |
| O painel de conversas semelhantes está vazio | A conversa ainda não foi indexada, ou o painel está desativado nas configurações. Novas conversas são indexadas em alguns minutos. |
Privacidade e tratamento de dados
A busca por palavra-chave roda inteiramente dentro do seu banco de dados do FreeScout e não envia nada a lugar nenhum. Com a busca por significado ativada, o texto de cada conversa indexada (assunto, mensagens do cliente, respostas do agente e notas internas, se incluídas) é enviado ao provedor que você configurou. Um endpoint público usa HTTPS; um endpoint HTTP privado permanece na rede que você configurar. A chave é opcional para um endpoint compatível. Apenas a impressão digital retornada é armazenada.
O único contato com replyrabbit.app é a verificação de licença, que envia a chave de licença, a URL do site do FreeScout e a versão do módulo. Nenhum texto de conversa, palavra de busca ou dado de cliente é enviado para nós.
Se o texto da conversa precisar permanecer nos seus próprios servidores, use um provedor local ou um endpoint compatível na sua rede privada confiável, ou fique no modo de palavras-chave. Com um endpoint público compatível, o texto trafega por HTTPS. Endpoints HTTP privados são permitidos apenas em uma rede confiável.
FAQ
Preciso do ReplyRabbit para usar a Semantic Search?
Não. O Semantic Search é um módulo separado do FreeScout dos mesmos criadores. Ele se instala e funciona por conta própria. O ReplyRabbit é apenas onde você o compra, baixa e gerencia a chave de licença.
A Semantic Search funciona sem uma chave de IA?
Sim. O modo de palavra-chave fica ativo desde o momento em que você ativa o módulo, sem chave e sem configurações. Cada palavra da sua busca precisa aparecer em algum lugar da conversa, no assunto, no nome do cliente, no endereço de e-mail ou no texto da mensagem. A chave de IA só adiciona a busca por significado e o painel de conversas semelhantes.
Quais provedores de IA posso usar?
OpenAI (text-embedding-3-small por padrão), Google Gemini (gemini-embedding-001 por padrão) ou qualquer serviço compatível com OpenAI, como OpenRouter, Ollama ou LM Studio, onde você insere a URL base e o modelo por conta própria. O Z.AI não é compatível porque não tem serviço de embeddings.
Quanto custa a chave de IA?
Com o OpenAI text-embedding-3-small a 0,02 USD por milhão de tokens, indexar cerca de 100 conversas custa aproximadamente 0,01 USD. Um atendimento com 10.000 conversas paga cerca de 1 USD para indexar tudo uma vez, depois alguns centavos por mês para novos e-mails. A página de configurações mostra uma estimativa antes da primeira indexação ser executada.
Onde os dados de pesquisa são armazenados?
Em duas tabelas dentro do seu banco de dados FreeScout existente. Cada conversa indexada adiciona cerca de meio kilobyte. Nenhum servidor de busca separado é necessário, e nada é armazenado em replyrabbit.app.
Funciona no PostgreSQL?
Sim. A busca por palavra-chave e a busca por significado funcionam no MySQL, MariaDB e PostgreSQL.
O que acontece se minha chave parar de funcionar ou a licença expirar?
A pesquisa volta ao modo de palavra-chave por conta própria, para que os agentes continuem recebendo resultados. A página de configurações mostra o motivo. A pesquisa por palavra-chave nunca depende da licença ou da chave.