Fess 15.7のStaticテーマでセマンティック検索を分かりやすく可視化する

Fessでセマンティック（ベクトル）検索を手軽に試せるように、docker-semanticsearchを大きく刷新しました。Fess 15.7とOpenSearch 3.7を組み合わせ、docker compose upだけで、BM25（キーワード検索）とベクトル検索を組み合わせたハイブリッド検索が動く環境をそのまま立ち上げられるようにしています。

今回のポイントは、Fess 15.7で追加された静的テーマ（Static Theme）の仕組みを活用し、検索結果の見た目を分かりやすくしたことです。デフォルトで採用している「SemanticLens」テーマでは、各検索結果がキーワード検索・セマンティック検索・ハイブリッドのどれによってヒットしたのかをバッジで表示します。これにより、セマンティック検索が実際にどう効いているのかが一目で分かるようになりました。

セマンティック検索とハイブリッド検索

Fessのセマンティック検索は、埋め込みモデルで文章をベクトル化し、意味の近さで検索するベクトル検索です。従来のBM25によるキーワード検索と組み合わせ、RRF（Reciprocal Rank Fusion）で両者のランキングを統合することで、表記ゆれや言い換えに強いハイブリッド検索を実現します。docker-semanticsearchでは、多言語対応の埋め込みモデルparaphrase-multilingual-MiniLM-L12-v2（384次元）をデフォルトで使用します。

必要な環境

  • Docker および Git
  • Linuxの場合はOpenSearch向けにvm.max_map_countを262144以上に設定（Docker Desktopでは自動設定）

利用する主なコンポーネントは以下のとおりです。

  • Fess 15.7.0
  • OpenSearch 3.7.0（fess-opensearch）
  • fess-webapp-semantic-search 15.7.0

セットアップと起動

リポジトリをクローンし、セットアップスクリプトを実行してから起動します。

git clone https://github.com/codelibs/docker-semanticsearch.git
cd docker-semanticsearch
bash ./bin/setup.sh
docker compose up -d

bin/setup.shは、データディレクトリの作成、system.propertiesの初期生成、そして静的テーマの同期を行います。初回起動時はOpenSearchが埋め込みモデルをダウンロードするため、準備が整うまで数分かかります。進捗は次のコマンドで確認できます。

docker compose logs -f init-semantic init-fess-index
docker compose ps -a

fess01がhealthyになり、セットアップ用のコンテナが正常終了すれば準備完了です。検索画面はhttp://localhost:8080/、管理画面はhttp://localhost:8080/admin（初期アカウントはadmin / admin）でアクセスできます。あとは管理画面のクローラー設定でクロール対象を登録してクロールを実行すれば、取り込んだドキュメントが自動的にベクトル化され、検索できるようになります。

Staticテーマで検索結果を可視化する

今回の刷新で一番大きいのが、検索画面の作り方を変えたことです。以前は独自のJSPテーマで検索画面を組んでいましたが、Fess 15.7で追加された静的テーマ（HTML/CSS/JavaScriptだけで検索画面を構成できる仕組み）に切り替えました。テーマはfess-themesリポジトリからbin/setup.shが同期します。

利用するテーマは.envのTHEME_NAMEで指定でき、デフォルトはsemanticlens（SemanticLens）です。SemanticLensは、各検索結果に「その結果がどの検索器（keyword / semantic / hybrid）によって生成されたか」を示すバッジと凡例を表示します。ハイブリッド検索では複数の検索器のランキングが統合されるため、通常のテーマでは「なぜこの結果が出てきたのか」までは分かりません。SemanticLensを使うと、セマンティック検索で拾えた結果とキーワード検索でヒットした結果を見分けられるので、動作の理解やチューニングに役立ちます。

SemanticLens以外にも、以下の静的テーマが選べます。

  • semanticlens（デフォルト。検索器バッジを表示）
  • nomadkit
  • docsearch
  • docuforge
  • rawblock
  • voicebox

テーマを切り替えるときは.envのTHEME_NAMEを変更してからbin/setup.shを実行します。なお、bin/setup.shは既存のsystem.propertiesを上書きしないため、すでに起動済みの環境でテーマを変える場合は、data/fess/opt/fess/system.propertiesのtheme.defaultを直接書き換える（または管理画面のAdmin > Generalで変更する）必要があります。

セマンティック検索は自動でセットアップされる

以前のdocker-semanticsearchは、モデルの登録や設定値の手貼り、再インデックスといった手順をすべて手動で行う必要がありました。今回のバージョンでは、これらをコンテナ起動時に自動化しています。

  • セマンティック検索プラグインは、FessのFESS_PLUGINS環境変数で自動的にインストールされます。
  • init-semanticコンテナが、OpenSearchに埋め込みモデルを登録・デプロイし、チャンク分割と埋め込みを行うニューラル取り込みパイプライン（neural_pipeline）を作成します。
  • 生成されたモデルIDは、Fess起動時にJVMのシステムプロパティとして自動的に注入されます。
  • init-fess-indexコンテナが、ドキュメントインデックスにベクトル用のマッピングを付与するための再インデックスを一度だけ実行します。

これらはいずれも冪等に作られているので、docker compose upを実行するだけで、管理画面での手作業なしにハイブリッド検索が使える状態になります。

まとめ

docker-semanticsearchをFess 15.7 + OpenSearch 3.7に対応させ、docker compose upだけでセマンティック検索（ハイブリッド検索）を試せるようにしました。さらに、Fess 15.7のStaticテーマ「SemanticLens」を採用することで、どの検索器で結果がヒットしたのかがバッジで分かるようになり、セマンティック検索の挙動を見た目でつかめるようになっています。

詳細やソースコードはdocker-semanticsearchを参照してください。

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です