カテゴリー: CodeLibs

Fessの旧v1 APIでログイン必須・チャット権限を適用する改善案

Fessの旧v1 APIを利用する環境向けに、ログイン必須設定とRAGチャットの利用権限をAPIの入口でも確認する改善案が出ています。対象は互換プラグインfess-webapp-v1-apiです。コアのv2 APIで行う判定に、旧APIの挙動を合わせる変更です。

初期値と利用条件

login.requiredの初期値はfalse、rag.chat.permissionsの初期値は空です。この組み合わせでは、今回のアクセス制御による挙動は変わりません。RAGチャット自体はrag.chat.enabled=falseが初期値で、利用には有効化と対応LLMの設定も必要です。

ログイン必須とチャット利用権限は管理画面の「システム」→「全般」で設定する項目です。設定値の例は次のとおりです。

login.required=true
rag.chat.permissions={group}sales,{user}taro

この例は初期値ではなく、ログインを必須にし、指定したグループまたはユーザーへチャット利用を限定するものです。既存のRAGチャット設定の記事と合わせて、旧APIを使うクライアントの認証方法も確認します。

検索APIとアクセストークン

提案ではlogin.required=trueのとき、ログインしていない呼び出しに401を返します。検索、スクロール検索、サジェスト、ラベル、人気ワードでは、登録済みで有効期限内のアクセストークンをログインの代わりに使用できます。トークンが持つ権限に応じた検索結果になるので、ログイン必須設定と文書の閲覧権限は別に確認します。

お気に入りとチャットはユーザーのログインセッションを使う機能です。ログイン必須設定が有効なとき、トークンだけではログインの代わりになりません。ヘルスチェックの/api/v1/healthはログインなしで利用できるままです。

チャットの401と403

チャットはlogin.requiredの値にかかわらず、rag.chat.permissionsの判定も行う提案です。権限のない匿名ユーザーには401、ログイン済みでも対象権限を持たないユーザーには403を返します。非ストリーミングとストリーミングの両方が対象です。

rag.chat.permissionsが空なら、この追加の利用者制限はかかりません。チャットが回答に利用できる文書の閲覧権限まで外す設定ではありません。

変更後に確認すること

旧v1 APIの互換プラグインを導入していることが前提です。変更を含む版へ更新すると、これまで成功していた匿名リクエストが401になる場合があります。検索連携は有効なトークン、ユーザー機能はログインセッションを使う構成に分けて確認します。

未ログイン、許可ユーザー、許可されていないログインユーザー、期限切れトークンの各条件で応答を確認すると、設定の意図とクライアント側の認証方法が一致しているかを判断できます。

関連PR

Fessにフォルダから探せるファイル検索テーマを追加する

FessのStaticテーマに、共有フォルダやファイルサーバーの文書を探しやすくするfilesearchを追加しました。ファイル管理ツールに近い画面で、フォルダを絞り込み、更新日や種類で並べ替え、選んだ文書のプレビューを確認できます。Fess 15.9以降向けのテーマです。

フォルダ・一覧・プレビューの3つの領域

左側にはホストとフォルダのツリー、中央にはパンくずとファイル一覧、右側にはプレビューを配置します。フォルダを選ぶとその配下を対象に検索します。詳細、リスト、タイルの表示を切り替え、ファイル種類、更新日、サイズ、ラベルで絞り込めます。

検索条件とフォルダはURLへ保存するため、再読み込みや戻る・進む、リンクの共有でも状態を復元します。元のファイルはFessのgo/経由で開き、パスをコピーする操作も用意しています。

PDF、テキスト、画像、キャッシュした本文をプレビューできます。Office文書をブラウザでそのまま描画する機能ではなく、キャッシュされた内容を利用します。

テーマを導入する

fess-themesのソースから、次のコマンドでテーマのZIPを作成します。

./scripts/package.sh filesearch

Fess管理画面のテーマ画面でZIPをアップロードし、デフォルトテーマなどに設定します。theme.defaultはシステムプロパティです。管理画面の全般設定、system.properties、またはJVMの-Dfess.system.theme.default=filesearchを使います。

種類と場所によるソートを利用する場合は、fess_config.propertiesに以下を設定します。

query.additional.sort.fields=filetype,url

サムネイルのthumbnail.enabled=trueもシステムプロパティです。キャッシュによるプレビューを広げる場合は、crawler.document.cache.supported.mimetypesへ対象のMIMEタイプを追加し、再クロールでキャッシュを作成してください。

キーボードと小さい画面での操作

一覧は矢印キーで移動でき、Enterで元ファイルを開き、Spaceでプレビューを切り替えます。フォルダツリーもキーボードで開閉できます。小さい画面ではツリーやプレビューを引き出し式の表示にし、スマートフォン幅でヘルプやログインへアクセスするメニューも用意しました。

追加後の修正では、ページ変更で存在しないフォルダが増える問題、閉じたオプション欄へTab移動する問題、表示件数をサーバーが制限した場合のページングなども改善しています。お気に入りは追加操作に対応し、追加済みの星を「解除できる」表示にはしません。

大きなフォルダでの制限

フォルダツリーはホスト・URLのファセットから組み立てます。大量のファイルがある場合、件数は下限を示す≥表示になり、サブフォルダがすべて列挙されない場合があります。

「フォルダで表示」はテーマ内で親フォルダに移動する機能です。OSのファイル管理画面を直接開くものではありません。最近の検索はブラウザ内のlocalStorageへ保存し、Fessのログインユーザー別検索履歴とは別に扱います。

関連PR

Fessのゼロヒット検索を調べて関連クエリーを検索ログから生成する

Fessの検索ログに、ゼロヒットの原因を詳しく調べる機能と、利用者の検索語の言い換えから関連クエリーを生成する機能が追加されました。以前紹介した分析ダッシュボードに加え、検索改善を実施するための操作が増えています。

ゼロヒットのログへ移動する

概要・クエリータブに表示するゼロヒットの検索語から、該当するログ一覧を開けます。一覧のヒット数フィルターで「すべて」「ゼロヒットのみ」「1件以上」を切り替え、同じ条件でCSVを出力できます。ゼロヒットの表には最終検索日時も表示します。

利用者の分析にはロール・グループごとの検索数、ユーザー数、ゼロヒット率が加わりました。1回の検索をそのユーザーの複数のロール・グループへ計上するため、各行の合計は全体の検索数と一致しない場合があります。個人用の検索ロールは表から除外します。

検索ログから関連クエリーを生成する

管理画面の関連クエリーで「検索ログから生成」を実行します。同じセッションで短時間に行った検索の組み合わせを、検索語の言い換えとして集計します。例えば最初の検索語の後に、より具体的な語で検索してヒットした場合が候補になります。

主な初期値は次のとおりです。fess_config.propertiesで調整できます。

related_query.generate.days=30
related_query.generate.term.size=100
related_query.generate.query.size=5
related_query.generate.min.sessions=3
related_query.generate.session.interval=10

過去30日、仮想ホストごとに最大100語、1語につき最大5件の関連語が対象です。元の語と関連語の両方に3以上の異なるセッションが必要で、検索し直す間隔は10分以内です。検索ログとユーザー情報の記録が有効であることが前提になります。既存の登録語は変更せず、新規の語だけを作成します。

生成結果を確認して運用する

関連クエリーは公開され、検索語のOR展開にも利用します。生成時にはsuggest.search.log.permissionsに従ってゲスト公開できるログだけを対象とし、フィールド指定やワイルドカードなどの検索構文、NGワード、ヒットしない後続検索を除外します。作成後は通常の関連クエリーとして編集・削除できます。

全ログを無制限に解析する機能ではありません。1語あたりのログ取得は初期値で1000件、セッション200件、後続ログ2000件に制限し、語の長さは2〜50文字です。登録件数は関連クエリーキャッシュの上限にも従います。処理は同期実行で同時実行を拒否するため、大量のログがある場合は期間と件数を絞って実行してください。

ゼロヒット率が高いからといって、関連語の追加だけで解決するとは限りません。クロール対象や文書の閲覧権限、必要なコンテンツが存在するかも、ログを手がかりに確認するとよさそうです。

利用できるバージョン

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

関連PR