适用于 FreeScout 的 Semantic Search
Semantic Search 是一个独立的 FreeScout 模块,可修复多词搜索,并且一旦您添加自己的 AI 密钥,就能按对话主题查找对话。它由 ReplyRabbit 的制作者销售,但不需要安装 ReplyRabbit。
在找概览?
概览
FreeScout 的内置搜索将您的整个查询作为一个字段中的一个短语来查找。像这样的搜索 frank invoice 找不到任何内容,因为客户姓名在一个地方,而“发票”一词在另一个地方。Semantic Search 分两个阶段取代该行为:
- 关键词模式 (无需密钥):搜索中的每个词都必须出现在对话的某处。主题、客户姓名、电子邮件地址和消息文本都计入。模块激活后即启用。
- 按含义搜索 (你自己的 AI 密钥):每个对话都会获得一个关于其内容的紧凑指纹,存储在你的 FreeScout 数据库中。搜索会同时按含义和关键词进行匹配,两个列表会混合排序,使最佳答案排在前面。此模式还支持 相似对话 面板,位于对话侧边栏中。
搜索页面显示一个小型 语义 或 关键词 结果计数旁边的标签,以便代理知道哪个模式回答了。
搜索语法
常见的搜索引擎简写在两种模式下都有效:
| 你输入 | 它做什么 |
|---|---|
frank invoice | 两个词都必须出现在对话中的某处。 |
"out of stock" | 确切短语必须出现。 |
-refund 或 -"out of stock" | 包含该词或短语的对话被排除。 |
cart OR basket | 任一词都足够。 OR 必须大写。 |
admin@example.com 或 example.com | 电子邮件地址或域名会精确匹配。 |
按含义搜索仅添加与您输入的词语明显关于同一事物的对话。引用的短语、地址和 -exclusions 仍会应用于这些结果,因此搜索电子邮件地址绝不会被无关对话填满。
搜索栏和过滤器
在搜索结果页面上,搜索框就位于 对话 和 客户 选项卡,因此你可以更改搜索而无需滚动回顶部。排序下拉菜单位于 客户 选项卡。

点击搜索框旁边的滑块按钮以打开 过滤器 面板。你不需要记住上面的简写:四条单词规则会为你把它写入搜索框。
| 过滤 | 它写什么 | 它做什么 |
|---|---|---|
| 所有这些词 | frank invoice | 每个词都必须出现。 |
| 这个确切的短语 | "out of stock" | 这些词必须按此顺序一起出现。 |
| 这些词中的任意一个 | cart OR basket | 其中一个词就足够了。 |
| 不包含这些词 | -refund | 包含该词的对话被排除。 |

标准 FreeScout 筛选器(邮箱、状态、负责人、客户、日期等)位于 高级 部分,位于面板底部。它默认折叠以保持面板简短,当其中某个筛选器已在使用时会自动展开。滑块按钮上的小数字显示有多少个筛选器处于活动状态。点击 应用 以运行搜索,或 全部清除 以重新开始。

从 1.1.3 起, 客户 选项卡也会单独查看每个词。如果没有客户匹配所有词,它会列出匹配任意词的客户,最接近的匹配优先,因此 invoice frank 仍能找到名为 Frank 的客户。
前提条件
开始之前,请确保你有:
- FreeScout 1.8.101 或更新版本,运行在 PHP 8.1 或更高版本上。
- 一个可正常工作的 FreeScout 队列工作进程和调度器(
php artisan queue:work以及schedule:runcron)。索引在它们上运行。 - 一个来自您的 Semantic Search 许可证 ReplyRabbit 账户。购买电子邮件包含许可证密钥。
- 可选,用于按含义搜索:来自 OpenAI 或 Google Gemini 的 API 密钥,或兼容服务(如 OpenRouter、Ollama 或 LM Studio)的基础 URL 和嵌入模型名称。
安装模块
下载 ZIP
登录于 app.replyrabbit.app 使用您在结账时使用的电子邮件地址,并打开 Semantic Search 仪表板上的卡片。下载semantic-search.zip.将其复制到 Modules 文件夹
解压semantic-search.zip并复制SemanticSearch文件夹放入Modules您的 FreeScout 安装目录,通过 SFTP 或您主机的文件管理器,放在其他模块旁边。FreeScout 没有用于第三方模块的应用内上传功能。激活模块
激活 Semantic Search 从模块列表。激活会运行创建两个索引表的数据库迁移。尝试搜索
搜索客户姓名加主题,例如名字和“发票”。结果现在会匹配对话中出现的每个词,搜索页面显示 关键词 标签。
关键词模式此时无需进一步设置即可工作。以下步骤将解锁按含义搜索和相似对话面板。
输入许可证密钥
打开设置页面
在 FreeScout 中,转到 管理,然后 设置,然后 Semantic Search.粘贴许可证密钥
在 许可证 部分,粘贴你购买邮件中的密钥并保存。状态显示 已授权 以及上次检查的时间。
许可证与 FreeScout 安装的站点 URL 绑定。如果您将 FreeScout 移动到新域,请联系 hey@replyrabbit.app 我们会重置它。
按含义设置搜索
选择提供方
在 嵌入提供商 部分,选择 OpenAI, Google,或 OpenAI 兼容。OpenAI 和 Google 的默认模型已填写。对于兼容服务,请输入基础 URL 及其期望的模型名称。添加密钥并进行测试
如果您的提供商需要,请粘贴 API 密钥,然后点击 测试嵌入。测试会向嵌入端点发送一个短句并检查其响应。密钥会加密存储,保存后仅显示掩码预览。选择要索引的邮箱
在 索引中 部分,勾选要包含的邮箱。 包含内部备注 默认开启,因为代理经常搜索自己的备注。设置 回填天数 以确定索引回溯多远(默认是 365 天)。开启按含义搜索
勾选 按含义搜索 并保存。如果提供商、模型或基础 URL 已更改,页面会告诉你对话将在后台重新索引。开始首次索引
点击 立即索引。状态块会显示进度,例如"已索引 1,240 / 8,900(14%)"、上次运行时间、上次错误(如有)以及预计剩余成本。索引每五分钟以约 200 个对话为一批运行,因此大型服务台需要几个小时。搜索全程保持可用。
哪个提供商?
使用自定义嵌入端点
输入 API 基础 URL,例如 https://embeddings.example.com/v1 或 http://10.0.0.25:8001/v1,后跟该处提供的精确嵌入模型 ID。语义搜索会添加 /embeddings 到基础 URL。公共地址需要 HTTPS。私有或回环 HTTP 地址必须位于 FreeScout 可访问的可信网络上。
如果一个网关同时服务聊天和嵌入,你可以输入相同的 /v1 此处和以下位置的基础 URL ReplyRabbit 的自定义提供商设置处理。在此处配置嵌入模型,并在 ReplyRabbit 中配置聊天模型。如果你的聊天服务器和嵌入服务器具有不同的 URL,请在每个产品中分别输入各自的 URL。这些产品不共享令牌或设置。
该 测试嵌入 action 必须返回嵌入向量。仅回答的聊天模型 /chat/completions 无法支持按含义搜索。更改端点或模型会启动新的索引配置文件;仅更改 Token 会保留现有向量。


保持更新
当新版本发布时,FreeScout 会在以下位置显示 管理,然后 模块,以及 立即更新 就地安装:无需 SFTP,无需重新上传。您从仪表板下载的 ZIP 带有您自己许可证的下载链接,因此更新会在与首次下载相同的许可证检查后获取。
需要了解两件事:
- 更新仅适用于从你的仪表板下载的副本,并且你不应传递你的副本:其更新链接包含你自己许可证的下载密钥,因此任何持有该 ZIP 的人都可以使用你的许可证获取更新。来自他人的副本绑定到他们的许可证,并使用他们的密钥更新。
- 如果 FreeScout 报告下载错误,请从你的仪表板下载新的 ZIP 并手动替换文件夹,如上述安装步骤。你的索引和设置会保留:它们存储在数据库中,而不是模块文件夹中。
成本
索引会将每个对话的文本发送给你的提供商一次,如果对话有新回复则再次发送。搜索仅发送搜索词。
| 提供商 | 模型 | 价格 | 约 100 个对话 |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 每百万 token 0.02 美元 | 约 0.01 美元 |
| Google Gemini | gemini-embedding-001 | 免费层级,然后按令牌定价 | 通常免费 |
| Ollama 或 LM Studio | 任何嵌入模型 | 无 | 无 |
设置页面会显示仍在等待索引的对话的估算数量,以便你在点击前核对数字 立即索引。仅当你更改提供商或模型,或点击 重新索引所有内容.
相似对话面板
开启按含义搜索后,一个 相似对话 面板会出现在对话侧边栏中。它会列出同一邮箱中讨论同一主题的其他对话,并显示主题、客户姓名和日期。坐席只能看到他们已有权限访问的对话。
使用以下选项为所有人关闭面板 相似对话 在设置页面上开启。新对话会显示“暂无相似内容”,直到它被索引,这需要几分钟。

命令行
通过 SSH 管理 FreeScout 时,有两个命令会有所帮助:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status 打印与设置页面相同的覆盖范围数字。 reindex 立即运行一批任务,而不是等待调度器,这对大型服务台的首次索引很有用。
故障排除
| 症状 | 应检查什么 |
|---|---|
| 搜索页面显示 关键词 而不是 语义 | 确认 按含义搜索 已勾选,许可证状态为 已授权,且状态块未显示最近的错误。如果密钥失败,搜索会回退到关键词模式,直到修复为止。 |
| 搜索页面上完全不显示任何标签 | 搜索已交给 FreeScout 自带的搜索处理。这适用于仅为一个数字的搜索(工单号或订单号),核心功能已能很好地处理这类搜索。 |
| 测试嵌入 失败 | 检查密钥没有前导或尾随空格,并且属于正确的提供方。对于兼容服务,确认 FreeScout 服务器可以访问基础 URL,并且嵌入模型名称与服务期望的完全一致。 |
| 状态显示“尚未索引任何内容” | 确保队列工作进程和调度器 cron 正在运行。点击 立即索引 并在一分钟后刷新。在共享主机上,第一批可能需要几分钟才能开始。 |
| 索引中途停止 | 在状态块上读取最后的错误。提供商的速率限制和配额错误是常见原因;索引会在下一次计划运行时恢复。 |
| 在非常大的服务台上搜索结果很慢 | 关键词模式会针对消息文本检查每个搜索词,这比核心的单一短语匹配更重。请将搜索限制在几个词,或减少索引中包含的邮箱。 |
| 相似对话面板为空 | 对话尚未被索引,或面板在设置中已关闭。新对话会在几分钟内被索引。 |
隐私和数据处理
关键词搜索完全在你的 FreeScout 数据库内运行,不会向任何地方发送任何内容。开启按含义搜索后,每个已索引对话的文本(主题、客户消息、代理回复以及内部备注,如果包含)会发送到你配置的提供商。公共端点使用 HTTPS;私有 HTTP 端点保留在你配置的网络上。对于兼容端点,密钥是可选的。仅存储返回的指纹。
与 replyrabbit.app 的唯一联系是许可证检查,它会发送许可证密钥、FreeScout 站点 URL 和模块版本。不会向我们发送任何对话文本、搜索词或客户数据。
如果对话文本必须保留在你自己的服务器上,请使用本地提供商或受信任私有网络上的兼容端点,或保持关键词模式。使用兼容的公共端点时,文本通过 HTTPS 传输。私有 HTTP 端点仅允许在受信任的网络上使用。
常见问题
使用语义搜索需要 ReplyRabbit 吗?
不需要。Semantic Search 是同一开发者提供的独立 FreeScout 模块。它可独立安装和运行。ReplyRabbit 只是你购买、下载和管理许可证密钥的地方。
语义搜索在没有 AI 密钥的情况下工作吗?
是的。激活模块后关键词模式即刻可用,无需密钥也无需设置。搜索中的每个词都必须出现在对话的某个位置,包括主题、客户姓名、电子邮件地址或消息文本。AI 密钥仅增加按含义搜索和相似对话面板。
我可以使用哪些 AI 提供商?
OpenAI(默认使用 text-embedding-3-small)、Google Gemini(默认使用 gemini-embedding-001),或任何 OpenAI 兼容服务,如 OpenRouter、Ollama 或 LM Studio,您需要自行输入基础 URL 和模型。不支持 Z.AI,因为它没有嵌入服务。
AI 密钥费用是多少?
使用 OpenAI text-embedding-3-small,每百万令牌 0.02 美元,索引约 100 个对话大约花费 0.01 美元。拥有 10,000 个对话的服务台一次性索引全部内容约需 1 美元,之后每月新邮件只需几美分。设置页面会在首次索引运行前显示估算值。
搜索数据存储在哪里?
在你现有 FreeScout 数据库内的两个表中。每个索引对话增加约半千字节。不需要单独的搜索服务器,并且不会在 replyrabbit.app 上存储任何内容。
它能在 PostgreSQL 上运行吗?
是的。关键词搜索和按含义搜索在 MySQL、MariaDB 和 PostgreSQL 上均可使用。
如果我的密钥停止工作或许可证失效会怎样?
搜索会自动回退到关键词模式,因此客服人员仍能获得结果。设置页面显示原因。关键词搜索从不依赖许可证或密钥。