FreeScout向けSemantic Search
Semantic Searchは、複数単語検索を修正し、独自のAIキーを追加すると会話の内容で検索できるスタンドアロンのFreeScoutモジュールです。ReplyRabbitの開発元によって販売されていますが、ReplyRabbitのインストールは不要です。
概要をお探しですか?
概要
FreeScoutの組み込み検索は、クエリ全体を1つのフィールド内の1つのフレーズとして探します。次のような検索は frank invoice 何も見つかりません。顧客名が1か所にあり、「invoice」という単語が別の場所にあるためです。Semantic Searchはその動作を2段階で置き換えます:
- キーワードモード (キー不要):検索のすべての単語が会話のどこかに含まれている必要があります。件名、顧客名、メールアドレス、メッセージ本文がすべて対象です。モジュールが有効になるとすぐにオンになります。
- 意味で検索 (独自のAIキー):各会話には、その内容を示すコンパクトなフィンガープリントが作成され、FreeScoutデータベースに保存されます。検索は意味とキーワードで照合され、2つのリストがブレンドされて最良の回答が最初に来ます。このモードは以下も強化します 類似した会話 会話サイドバーのパネル。
検索ページに小さな セマンティック または キーワード 結果数の横にあるラベルで、エージェントがどのモードが回答したかを知ることができます。
検索構文
通常の検索エンジンの省略記法は両方のモードで機能します:
| あなたが入力します | それが行うこと |
|---|---|
frank invoice | 両方の単語が会話のどこかに含まれている必要があります。 |
"out of stock" | 正確なフレーズが含まれている必要があります。 |
-refund または -"out of stock" | 単語またはフレーズを含む会話は除外されます。 |
cart OR basket | どちらかの単語で十分です。 OR 大文字である必要があります。 |
admin@example.com または example.com | メールアドレスまたはドメインは完全一致で照合されます。 |
意味で検索は、入力した単語と同じ内容について明確に扱っている会話のみを追加します。引用されたフレーズ、アドレス、および -exclusions それらの結果にも適用されるため、メールアドレスの検索が無関係な会話で埋め尽くされることはありません。
検索バーとフィルター
検索結果ページでは、検索ボックスがすぐ横に配置されます 会話 および 顧客 タブなので、上部までスクロールバックせずに検索を変更できます。並べ替えドロップダウンは 顧客 タブ。

検索ボックスの横にあるスライダーボタンをクリックして次を開きます フィルター パネル。上記の省略形を覚える必要はありません。4 つの単語ルールが検索ボックスに自動的に書き込みます。
| フィルター | それが書き込むもの | それが行うこと |
|---|---|---|
| これらすべての単語 | frank invoice | すべての単語が含まれている必要があります。 |
| この正確なフレーズ | "out of stock" | 単語はこの順序で一緒に表示される必要があります。 |
| これらの単語のいずれか | cart OR basket | いずれか 1 つの単語で十分です。 |
| これらの単語のいずれでもない | -refund | 単語を含む会話は除外されます。 |

標準のFreeScoutフィルター(メールボックス、ステータス、担当者、顧客、日付など)は次にあります 詳細設定 パネル下部のセクション。パネルを短く保つために折りたたまれており、これらのフィルターのいずれかがすでに使用されている場合は自動的に開きます。スライダーボタンの小さな数字は、アクティブなフィルターの数を示します。クリック 適用 検索を実行するため、または すべてクリア 再開するため。

1.1.3以降、 顧客 タブは各単語を個別にも調べます。すべての単語に一致する顧客がいない場合は、いずれかに一致する顧客を最も近い一致順に一覧表示するため、 invoice frank Frank という名前の顧客を引き続き見つけます。
前提条件
始める前に、次を確認してください:
- PHP 8.1以降のFreeScout 1.8.101以降。
- 動作する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フォルダを以下にModulesFreeScoutインストールのディレクトリに、SFTPまたはホストのファイルマネージャー経由で、他のモジュールの隣に配置します。FreeScoutにはサードパーティモジュール用のアプリ内アップロードはありません。モジュールを有効化
有効化 Semantic Search モジュール一覧から。有効化により、2つのインデックステーブルを作成するデータベースマイグレーションが実行されます。検索を試す
顧客名とトピック(例: 名と「invoice」)で検索します。結果は会話内のどこに現れてもすべての単語に一致するようになり、検索ページに キーワード ラベル。
キーワードモードはこの時点で追加設定なしで機能します。以下の手順で、意味による検索と類似会話パネルが利用可能になります。
ライセンスキーを入力
設定ページを開く
FreeScoutで次に移動してください 管理)、次に 設定)、次に Semantic Search.ライセンスキーを貼り付けます
次の場所で ライセンス セクションで、購入メールのキーを貼り付けて保存します。ステータスが表示されます ライセンス済み 最後のチェック時刻とともに。
ライセンスはFreeScoutインストールのサイトURLに紐付けられています。FreeScoutを新しいドメインに移動する場合は、お問い合わせください hey@replyrabbit.app そしてリセットします。
意味による検索をセットアップ
プロバイダーを選択
次の場所で Embeddingプロバイダー セクションで選択する OpenAI, Google)、または OpenAI互換)。OpenAIとGoogleではデフォルトモデルが入力されています。互換サービスでは、ベースURLとそれが期待するモデル名を入力してください。キーを追加してテスト
プロバイダーがキーを必要とする場合はAPIキーを貼り付け、次にクリックします 埋め込みをテスト)。テストは埋め込みエンドポイントに短い文を1つ送信し、その応答を確認します。キーは暗号化して保存され、保存後はマスクされたプレビューのみが表示されます。インデックスするメールボックスを選択
次の場所で インデックス作成中 セクションで、含めるメールボックスにチェックを入れます。 内部メモを含める はデフォルトでオンです。エージェントはしばしば自分のノートを検索するためです。設定: バックフィル日数 インデックスを作成する期間の範囲 (デフォルトは 365 日)。意味による検索をオンにする
チェック 意味で検索 そして保存します。プロバイダー、モデル、またはベースURLが変更された場合、ページは会話がバックグラウンドで再インデックスされることを通知します。最初のインデックスを開始
クリック 今すぐインデックス)。ステータスブロックには「Indexed 1,240 of 8,900 (14%)」などの進捗、最終実行時刻、最後のエラー(ある場合)、推定残りコストが表示されます。インデックス作成は約5分ごとに約200会話のバッチで実行されるため、大規模なデスクでは数時間かかります。検索はその間ずっと機能し続けます。
どのプロバイダーですか?
カスタム埋め込みエンドポイントを使用してください
次のようなAPIベースURLを入力します https://embeddings.example.com/v1 または http://10.0.0.25:8001/v1)、その後にそこで提供される正確な埋め込みモデルIDが続きます。セマンティック検索は以下を追加します /embeddings ベース URL に。パブリックアドレスには HTTPS が必要です。プライベートまたはループバックの HTTP アドレスは、FreeScout が到達できる信頼されたネットワーク上にある必要があります。
1つのゲートウェイがチャットと埋め込みの両方を提供する場合は、同じものを入力できます /v1 ここおよび以下のベースURL ReplyRabbitのカスタムプロバイダー設定)。埋め込みモデルはここで設定し、チャットモデルはReplyRabbitで設定します。チャットサーバーと埋め込みサーバーのURLが別々の場合は、それぞれのURLをそれぞれの製品に入力してください。製品間でトークンや設定は共有されません。
その 埋め込みをテスト アクションは埋め込みベクトルを返す必要があります。単に答えるだけのチャットモデルは /chat/completions 意味による検索を強化できません。エンドポイントまたはモデルを変更すると新しいインデックスプロファイルが開始され、トークンのみを変更すると既存のベクトルが保持されます。


最新の状態に保つ
新しいバージョンがリリースされると、FreeScoutはそれを表示します 管理)、次に モジュール)、および 今すぐ更新 その場でインストールします:SFTPなし、再アップロードなし。ダッシュボードからダウンロードしたZIPには独自のライセンスのダウンロードリンクが含まれているため、更新は最初のダウンロードと同じライセンスチェックの背後で取得されます。
知っておくべき2つのこと:
- 更新はダッシュボードからダウンロードしたコピーでのみ機能し、コピーを渡すべきではありません。更新リンクには自分のライセンスのダウンロードキーが含まれているため、ZIPを保持する誰でもあなたのライセンスで更新を取得できます。他人からのコピーはその人のライセンスに紐付けられ、その人のキーで更新されます。
- FreeScoutがダウンロードエラーを報告する場合は、ダッシュボードから新しいZIPをダウンロードし、上記のインストール手順のようにフォルダを手動で置き換えてください。インデックスと設定は保持されます。これらはモジュールフォルダではなくデータベースに保存されているためです。
コスト
インデックス作成は各会話のテキストをプロバイダーに一度送信し、会話に新しい返信が付くと再度送信します。検索は検索語のみを送信します。
| プロバイダー | モデル | 価格 | 約100件の会話 |
|---|---|---|---|
| OpenAI | text-embedding-3-small | 100万トークンあたり0.02 USD | 約 0.01 USD |
| Google Gemini | gemini-embedding-001 | 無料枠、その後トークンごとの価格設定 | 通常は無料 |
| Ollama または LM Studio | 任意の埋め込みモデル | なし | なし |
設定ページには、インデックス待ちの会話の推定値が表示されるため、クリックする前に数値を確認できます 今すぐインデックス)。再インデックスは、プロバイダーまたはモデルを変更したとき、またはクリックしたときにのみ行われます すべてを再インデックス.
類似した会話パネル
意味による検索がオンの場合、 類似した会話 パネルが会話サイドバーに表示されます。同じメールボックス内で同じ内容に関する他の会話が、件名、顧客名、日付とともに一覧表示されます。エージェントは、すでにアクセス権を持つ会話のみを表示できます。
次で全員に対してパネルをオフにします 類似した会話 設定ページで切り替えます。新しい会話は、インデックスが作成される (数分かかります) まで「まだ類似するものはありません」と表示されます。

コマンドライン
SSH経由でFreeScoutを管理する場合に役立つ2つのコマンド:
php artisan semanticsearch:status
php artisan semanticsearch:reindex --limit=2000status 設定ページと同じカバレッジ数値を表示します。 reindex スケジューラを待たずにバッチをすぐに実行します。大規模なデスクでの最初のインデックス作成に便利です。
トラブルシューティング
| 症状 | 確認すべきこと |
|---|---|
| 検索ページに表示されます キーワード の代わりに セマンティック | 確認 意味で検索 がチェックされている場合、ライセンスステータスは ライセンス済み)、ステータスブロックに最近のエラーが表示されていないこと。キーが失敗した場合、修正されるまで検索はキーワードモードにフォールバックします。 |
| 検索ページにラベルがまったく表示されません | 検索はFreeScout自身の検索に引き渡されました。これは数字のみの検索(チケット番号や注文番号)で発生し、コアがすでにうまく処理します。 |
| 埋め込みをテスト 失敗する | キーの前後にスペースがなく、正しいプロバイダーのものであることを確認してください。互換サービスを使用する場合は、ベースURLがFreeScoutサーバーから到達可能であり、埋め込みモデル名がサービスが期待するものと正確に一致することを確認してください。 |
| ステータスに「まだインデックスされていません」と表示される | キューワーカーとスケジューラcronが実行されていることを確認してください。クリック 今すぐインデックス そして1分後に更新してください。共有ホスティングでは、最初のバッチが開始するまで数分かかることがあります。 |
| インデックス作成が途中で停止 | ステータスブロックの最後のエラーを確認してください。通常の原因はプロバイダーからのレート制限とクォータエラーです。インデックス作成は次回のスケジュール実行で再開します。 |
| 非常に大規模なデスクでは検索結果が遅い | キーワードモードはすべての検索語をメッセージテキストに対してチェックするため、コアの単一フレーズマッチよりも負荷が高くなります。検索は数語に抑えるか、インデックスに含めるメールボックスを減らしてください。 |
| 類似した会話パネルが空です | 会話はまだインデックスされていないか、設定でパネルがオフになっています。新しい会話は数分以内にインデックスされます。 |
プライバシーとデータの取り扱い
キーワード検索はFreeScoutデータベース内で完全に実行され、どこにも送信されません。意味による検索を有効にすると、インデックスされた各会話のテキスト(件名、顧客メッセージ、エージェントの返信、含める場合は内部メモ)が、設定したプロバイダーに送信されます。公開エンドポイントはHTTPSを使用し、プライベートHTTPエンドポイントは設定したネットワーク内に留まります。互換性のあるエンドポイントではキーは任意です。返されたフィンガープリントのみが保存されます。
replyrabbit.appとの唯一の通信はライセンスチェックで、ライセンスキー、FreeScoutサイトURL、モジュールバージョンを送信します。会話テキスト、検索語、顧客データは当社に送信されません。
会話テキストを自社サーバーに留める必要がある場合は、ローカルプロバイダー、信頼できるプライベートネットワーク上の互換エンドポイントを使用するか、キーワードモードのままにしてください。互換性のあるパブリックエンドポイントでは、テキストはHTTPS経由で送信されます。プライベートHTTPエンドポイントは信頼できるネットワーク上でのみ許可されます。
FAQ
Semantic Searchを使うにはReplyRabbitが必要ですか?
いいえ。Semantic Search は同じ開発元による別の FreeScout モジュールです。単独でインストールして動作します。ReplyRabbit はそれを購入し、ダウンロードし、ライセンスキーを管理する場所にすぎません。
Semantic SearchはAIキーなしで動作しますか?
はい。キーワードモードはモジュールを有効化した瞬間から、キーも設定も不要で利用できます。検索のすべての単語が、件名、顧客名、メールアドレス、またはメッセージ本文のいずれかに含まれている必要があります。AIキーは意味による検索と類似会話パネルのみを追加します。
どのAIプロバイダーを使用できますか?
OpenAI(デフォルトはtext-embedding-3-small)、Google Gemini(デフォルトはgemini-embedding-001)、またはOpenRouter、Ollama、LM StudioなどベースURLとモデルを自分で入力するOpenAI互換サービス。Z.AIは埋め込みサービスがないためサポートされていません。
AIキーの費用はいくらですか?
OpenAI text-embedding-3-smallを100万トークンあたり0.02 USDで使用すると、約100件の会話のインデックス作成にはおよそ0.01 USDかかります。10,000件の会話があるデスクでは、すべてを一度インデックス化するのに約1 USD、その後は新着メールに対して月に数セントかかります。設定ページには最初のインデックス実行前に見積もりが表示されます。
検索データはどこに保存されますか?
既存のFreeScoutデータベース内の2つのテーブルに保存されます。インデックスされた会話ごとに約0.5キロバイトが追加されます。別の検索サーバーは不要で、replyrabbit.appには何も保存されません。
PostgreSQLで動作しますか?
はい。キーワード検索と意味による検索はどちらもMySQL、MariaDB、PostgreSQLで動作します。
キーが機能しなくなった場合、またはライセンスが失効した場合はどうなりますか?
検索は自動的にキーワードモードに戻るため、エージェントは引き続き結果を得られます。設定ページに理由が表示されます。キーワード検索はライセンスやキーに依存しません。