Fess 15.9に向けたOpenSearchと既存インデックスの移行準備

Fess 15.9の開発版で、利用するOpenSearchが3.9.0へ更新されました。移行時には、OpenSearch本体とプラグインのバージョンを揃えることに加え、プラグインの取得先と既存の文書インデックスの扱いを確認する必要があります。

この記事は2026年10月4日時点でmainブランチへマージされた変更をもとにした移行準備のメモです。確認したFessの最新リリースは15.8.0で、15.9をリリース済みとして案内するものではありません。対応する開発版を検証する場合、または変更を含むリリースへの移行時に参照してください。

OpenSearchとプラグインを揃える

今回の開発版では、fess-setupの初期値が次のようになっています。

component.opensearch.version=3.9.0
component.opensearch.plugin.version=3.9.0
component.opensearch.plugin.repository=https://maven.codelibs.org/release

対応版のFessに同梱されたセットアップツールでは、次のコマンドでOpenSearchを導入します。

bin/fess-setup install opensearch

既存のOpenSearchへプラグインだけを導入する場合は、インストール先を指定します。

bin/fess-setup install opensearch-plugins --opensearch-home /path/to/opensearch-3.9.0

対象はanalysis-fess、analysis-extension、minhash、configsyncの4プラグインです。3.8.1以降のこれらの配布先はmaven.codelibs.orgです。手動でopensearch-pluginを使う場合、Maven座標形式はMaven Centralだけを参照するため、3.9.0のZIPのURLを指定します。例えばanalysis-fessは次のように導入します。

bin/opensearch-plugin install https://maven.codelibs.org/release/org/codelibs/opensearch/opensearch-analysis-fess/3.9.0/opensearch-analysis-fess-3.9.0.zip

残りの3プラグインも同じ配布先の3.9.0を使い、OpenSearch本体とバージョンを一致させます。公式OpenSearchバンドルにはk-NNが含まれています。独自に構成する場合も、15.9で必要となるk-NNを確認してください。Docker版は15.9.0-SNAPSHOTとOpenSearch 3.9.0の組み合わせへ更新されています。15.8.0の組み合わせはOpenSearch 3.8.0なので、既存の15.8環境へ新しいCompose定義をそのまま適用する前に対応関係を確認します。

既存インデックスへ新しい定義を反映する

15.9は起動時に設定・ログ・ユーザーのインデックスへ不足するフィールドを追加します。一方、文書インデックスのマッピングと解析設定は自動変更しません。15.8以前の文書インデックスでは、所有者・最終更新者の検索や、かなと長音記号の表記揺れの正規化を使うために再インデクシングが必要です。

管理画面の「システム情報」→「メンテナンス」で「エイリアスの更新」と「辞書の初期化」を有効にして、「再インデクシング」を実行します。既存文書を新しいインデックスへコピーする処理なので、マッピングと解析設定の反映だけなら再クロールは不要です。これらのチェックを初期状態のままにせず、実行前に確認してください。

「辞書の初期化」はOpenSearch側の辞書を同梱ファイルで上書きします。同義語などを独自に編集している場合は、事前にダウンロードし、再インデクシング後に必要な変更を反映し直します。

所有者の値を取得するには再クロールも必要

再インデクシングで定義を揃えても、以前に索引したファイルへ所有者の値が追加されるわけではありません。ファイルシステム・SMB・FTPの対象ファイルから値を取得するにはクロールが必要です。

差分クロールでは変更のないファイルを取得し直さないため、「システム」→「全般」の「最終更新日時の確認」を一時的に無効にしてクロールします。対象ファイルの取得が終わったら通常の差分クロール設定へ戻します。文書のコピーと、元ファイルから不足する値の取得を分けて考えると移行作業を整理できます。

切り戻し用のバックアップを残す

OpenSearch 3.9.0で取得したスナップショットは、3.8.0以前へ復元できません。切り戻しに使うアップグレード前のスナップショットと設定・辞書のバックアップを残しておきます。また、辞書はOpenSearchの設定ディレクトリ配下へ配置します。この制限は3.8.0からのものです。

新機能の設定だけでなく、プラグインの配布先、文書インデックスの再構築、必要に応じた再クロールまで含めて検証しておくと、15.9への移行を準備できます。

関連PR

FessのRAGチャットで利用権限・回答言語・再検索回数を設定する

FessのRAGチャットに、利用できるユーザーと参照文書の制限、回答言語の指定、検索クエリーの作り直し回数の設定が追加されました。部署限定のチャットや、日本語で回答する社内検索を構成しやすくなります。

利用者と参照文書を制限する

管理画面の「システム」>「全般」のRAG設定で、利用パーミッションとラベルを指定します。これらはsystem.propertiesの設定項目です。例えば次のように指定します。

rag.chat.permissions={group}sales,{user}taro
rag.chat.labels=manual,faq

両方とも初期値は空です。パーミッションが空なら従来どおり利用可能な全員が対象、ラベルが空ならユーザーが閲覧できる全ての文書が対象です。パーミッションは列挙したいずれかに一致すれば利用できます。{role}guestを指定すれば匿名ユーザーも対象になります。

ラベルには表示名ではなくラベル値を指定します。指定したラベルのいずれかに属する文書と、もともとの閲覧権限の両方を満たす文書だけを参照します。ユーザーがチャットで選んだラベルともANDで組み合わせます。通常検索だけでなく、URL要約や文書を指定するチャットにも制限を適用します。

利用権限のない匿名ユーザーは401、ログイン済みユーザーは403となります。制限対象のユーザーには標準テーマのチャットリンクも表示しません。空でない不正なパーミッション設定から利用対象を解決できない場合は、全員を拒否します。

回答言語と検索回数を指定する

次の2項目はfess_config.propertiesに設定します。前述の全般設定とは保存先が異なります。

rag.chat.response.language=browser
rag.chat.query.regeneration.max.count=2

回答言語の初期値browserはブラウザーやUIの言語に従い、英語の場合は言語指示を加えません。jaなら日本語、enなら英語で回答するよう指示します。noneは言語指示を加えない設定で、通常は質問の言語に沿った回答になります。不正な言語コードは警告を出し、browserへ戻ります。LLMへの指示なので、必ず指定言語で回答する保証ではありません。

検索クエリーの再生成は初期値で最大2回です。ヒットがないとき、ストリーミングでは関連性評価で文書が残らないときにも、LLMにクエリーを作り直させて検索します。0で再生成を無効にできます。空のクエリーや同じリクエスト内で検索済みのクエリーが返った場合も打ち切ります。

利用時の制限

RAG自体はrag.chat.enabled=falseが初期値です。有効化と対応LLMの設定が前提になります。再生成回数を増やすとLLM呼び出し回数と待ち時間も増えます。非ストリーミングでは関連性評価を行わず、ヒットがない場合だけ再検索します。文書指定のチャットでは検索の再生成を行いません。

ラベル値の存在は保存時に検証しないため、設定後に対象ユーザーで文書取得を確認してください。独自の検索プラグインが標準の検索クエリー構築を利用しない場合は、追加フィルターへの対応確認も必要です。

利用できるバージョン

Fess 15.9.0に含まれる予定の機能になります。現時点では、まだ、リリースしていないので、今後のテストで変更される可能性もあります。

関連PR

Fessで最近の検索を条件ごと再実行する

Fessにログインしているユーザーが、自分の最近の検索をもう一度実行できるようにしました。同じキーワードで何度も資料を探すときに、ラベルや並び順などの条件も復元できます。

検索欄から履歴を選ぶ

標準のbootstrapテーマでは、空の検索欄をクリックするか、下矢印キーを押すと最近の検索を表示します。履歴を選ぶと、キーワードと保存された条件で検索をやり直します。

ページを開いて自動的に検索欄へフォーカスしただけでは履歴を表示しません。文字を入力し始めると通常のサジェストへ切り替わります。

同じ条件の検索はまとめて、新しいものから表示します。キーワードのない検索や2ページ目以降のリクエストは履歴の一覧対象にしません。現在の仮想ホストに対応した履歴を取得します。

設定とAPI

fess_config.propertiesに次の設定を追加しました。

search.history.enabled=true
search.history.size=10

デフォルトは有効で、最大10件を返します。ただし、検索ログを無効にしている場合は、この機能も利用できません。

APIはGET /api/v2/search-historyです。ログインセッションのユーザーIDを使い、検索ログから本人の履歴を取り出します。クライアントが任意に指定できるCookieやパラメーターでユーザーを決める方式ではありません。ゲストやアクセストークンによる呼び出しは対象外です。

保存する条件はキーワード、fields.*のフィルター、ex_q、並び順、明示的に指定した言語です。他のテーマで使う場合は、このAPIを利用する表示機能が必要になります。

履歴がすぐに出ない場合

検索ログは定期的にまとめて保存するため、検索直後の履歴反映には最大でおおむね1分かかります。また、今回の変更前のログには検索条件を保存したsearchParamsがないため、古い検索は履歴に表示しません。保存期間は既存の検索ログの削除設定に従います。

あわせて、起動時に設定・ログ・ユーザー系インデックスへ不足する標準フィールドを追加する処理を入れました。これにより、アップグレード済み環境でもsearchParamsを想定した定義で追加できます。既存フィールドの型は変更せず、検索文書インデックスは対象外です。

よく使う検索を条件ごと再利用できるようになり、繰り返し資料を探す際の操作を減らせます。

関連PR