FessのDocker環境で本体とテーマのバージョン系列をそろえる

FessのDocker環境で本体のイメージを15.9へ固定しても、セットアップが取得するテーマは15.10向けのまま、という組み合わせがありました。CodeSearchとFileSearchの15.9.xブランチでは、テーマも15.9.xから取得するように初期値が修正されています。

安定版では構成リポジトリーも15.9.xを選ぶ

両リポジトリーのmainは15.10の開発系列を追います。mainのイメージ指定だけ15.9へ書き換えると、fess-themesのmainから15.10向けテーマを取得してしまいます。Fess 15.9で新しく環境を用意するなら、修正を含む15.9.xブランチを選びます。

CodeSearchの場合は次のように取得します。DockerとCompose v2、Gitのほか、セットアップで使うcurl、unzipなどを用意します。

git clone --branch 15.9.x https://github.com/codelibs/docker-codesearch.git
cd docker-codesearch
bash ./bin/setup.sh
docker compose up -d
bash ./bin/verify.sh

このブランチでは.envのFESS_VERSION=15.9.0に対応して、テーマ取得用のFESS_THEMES_BRANCHも未設定時に15.9.xになります。検証スクリプトは、生成した設定とコード検索用フィールドの反映を確認します。検索対象リポジトリーの登録とクロールは別途必要です。

FileSearchでは次のように開始します。

git clone --branch 15.9.x https://github.com/codelibs/docker-filesearch.git
cd docker-filesearch
bash ./bin/setup.sh
docker compose up -d

こちらの本体イメージ初期値はghcr.io/codelibs/fess:15.9.0-noble、テーマ取得用の変数名はFESS_THEMES_REFで、未設定時に15.9.xを使います。初期設定とサンプルのクロールは、起動後にREADMEのbin/configure.shの手順で行います。既存の本番データへサンプル設定をそのまま流し込む手順ではありません。

上書き設定は初期値より優先される

両者で変数名が違う点に注意します。明示して実行する場合は次の対応です。

# docker-codesearchの作業ディレクトリーで
FESS_THEMES_BRANCH=15.9.x bash ./bin/setup.sh

# docker-filesearchの作業ディレクトリーで
FESS_THEMES_REF=15.9.x bash ./bin/setup.sh

CodeSearchのFESS_THEMES_BRANCHはスクリプトへ環境変数として渡します。Composeが読む.envに追記するだけでは、その値が必ずsetup.shへ渡るとは限りません。FileSearchはsetup.sh自身が.envを読み込むため、すでにFESS_THEMES_REF=mainを保存している場合はそちらの修正も必要です。

FileSearchのFESS_THEMES_DIRは初期値で未指定です。指定している場合はローカルのテーマをコピーするので、FESS_THEMES_REFの初期値変更は取得元に影響しません。CodeSearchのFESS_THEMES_SKIP_FETCHは初期値が0で、1かつ既存コピーがある場合は再取得しません。

既存環境ではテーマのコピーと実体を確認する

初期値が直っても、稼働中のテーマが自動で入れ替わるわけではありません。構成ブランチと保存済み設定、ローカルの変更を控えたうえで、修正を取り込み、setup.shを再実行します。両スクリプトとも通常はテーマのコピーを置き換えるので、独自変更は先に退避します。

取得後はtheme.ymlのminFessVersionと本体の系列を確認します。PRの検証では、CodeSearchは15.9.11、FileSearchは15.9.6のテーマが取得されていますが、15.9.xは更新されるブランチであり、パッチ番号を永久に固定する設定ではありません。

検索画面を再読み込みし、ログイン、検索、絞り込みを確認します。FileSearchではフォルダーツリーとプレビューも確認します。今回の変更だけで検索インデックスの移行や既存文書の再クロールが完了するわけではなく、旧バージョンからの移行には各READMEの手順も必要です。

関連PR

Fessのセマンティック検索で疑問符と追加条件の扱いを見直す

日本語の質問を「?」で終えると、セマンティック検索が実行されない場合がありました。FessのPR #3677・#3678・#3683では、こうした入力、引用符、追加の除外条件の扱いを修正しています。

疑問符を含む質問も埋め込みへ渡す

これまではデフォルトフィールドのワイルドカードを含むとベクトル検索を省略していました。空白のない「パスワードを変更するには?」も、その末尾が1文字ワイルドカードと解釈され、キーワード検索だけになる例です。

変更後はデフォルトフィールドのワイルドカード・前方一致・曖昧検索の語を、記号を含むテキストとして埋め込みへ渡します。検索フィールドではない「Q:」なども、条件として誤適用せず文字列として扱います。site:やlabel:など、認識されるフィールドの条件は引き続き絞り込みに使います。

「?」や「*」だけで文字・数字を含まない入力、フレーズ、除外語、ブースト、範囲、正規表現、sort:、allintitle:・allinurl:などには制限が残ります。すべての検索式がセマンティック検索になる変更ではありません。新しく対象となる質問も埋め込みプロバイダーへ送られる点を、外部サービスを使う構成では確認します。

追加の除外条件をベクトル側にも適用する

QueryHelperのadditionalQueryは、標準では未設定です。独自に「-label:internal」などを追加した構成で、キーワード側だけが除外し、ベクトル側から対象文書が戻る問題を修正します。追加条件は埋め込み文字列に混ぜず、ベクトル検索の条件として適用します。既存の閲覧ロールや仮想ホストの権限チェックを新設する変更ではありません。

追加クエリーに通常の語や変換不能な式が含まれる場合は、条件を捨てて検索を続けず、警告を出してセマンティック側を省略します。導入時は既存の追加条件を調べ、internal文書が戻らないこと、通常の文書は見つかることを同じ検索で比較します。

引用符を含む入力とAPIクライアント

PR #3678は、閉じ忘れた二重引用符を含む検索の再試行時に引用符もエスケープします。fields.*の値に含む引用符とバックスラッシュも、文字として保ちます。独自クライアントで値を事前エスケープしていた場合、そのバックスラッシュが残るため、通常のURLエンコードと検索構文のエスケープを混同しないよう見直します。ex_qは検索式を渡す契約のままで、不正な引用符が自動修復されるわけではありません。

この変更だけでベクトル検索が有効になるわけではなく、起動時のcontent_chunker.search.enabled=trueに加え、チャンク生成と利用可能な埋め込みプロバイダーが必要です。rank.fusion.engine.enabledの初期値はfalseで、このPRを理由に変更する必要はありません。修正を含む環境で、自然文・条件付き自然文・キーワードのみになる式を分けて確認します。PRの小規模インデックスによる検証を、大規模な近似検索の精度保証とは扱いません。

関連PR

Fessの人気ワードキャッシュとサジェストの反映タイミングを確認する

Fessでサジェストの設定を変えても画面に反映されない場合、サジェストのインデックス更新と人気ワードのキャッシュを分けて確認します。人気ワードのキャッシュ有効期間を、説明どおりの「秒」で扱う修正がマージされました。

初期値60が60秒として動く

fess_config.propertiesには次の初期値があります。

suggest.popular.word.cache.expire=60
suggest.popular.word.cache.size=1000

有効期間の説明は秒でしたが、従来の実装は分として読み、初期値60で最大60分キャッシュしていました。修正後は60秒です。これは書き込みからのキャッシュ期限で、1分ごとに必ずジョブを実行する設定ではありません。

従来の実効値60分に合わせたい場合は、修正後の環境で有効期間を秒数の3600にします。更新を早めるほどキャッシュの再取得が増えるので、設定変更後は負荷も確認します。

ワードの登録だけではインデックスは更新されない

除外ワードや追加ワードの登録・編集・削除、CSVアップロードは、登録済みのサジェスト候補へ即時反映する操作ではありません。「Suggest Indexer」ジョブの実行で反映されます。既定の実行時刻は毎日12:00ですが、運用環境でスケジュールを変更している場合は実際の設定を優先します。

すぐに反映したい場合は、管理画面の「システム > スケジューラ」から「Suggest Indexer」を開き、「今すぐ開始」を実行します。ジョブの成否を確認してから、同じ利用者・権限・ラベル条件で表示を試します。SuggestJobは実行後に人気ワードキャッシュもクリアします。

追加ワードCSVの権限欄も確認する

文書では次のヘッダーと例へ修正されています。

"SuggestWord","Reading","Permissions","Labels","Boost"
"fess","ふぇす","{role}role1","label1","100"

パーミッションは{role}、{user}、{group}の接頭辞を付けます。role1だけではそのロールの指定になりません。これはデータストアスクリプトのRrole1という検索ロール表記とは用途が違います。

キャッシュの修正だけで、失敗したジョブや不正な権限指定まで直るわけではありません。更新されないときは「ワードの設定 → Suggest Indexerの成功 → 利用者条件 → 人気ワードキャッシュ」の順で確認すると、待つべき箇所を判断しやすくなります。

関連PR