wiki-retrieve

関連する記述を取得する

この拡張機能は、wiki/ から検索データを .vault-meta/ に生成します。正規のノートは変更しません。選択した Vault は必ず明示的に指定してください。

インストール済み製品のルートは、Vault や現在の作業ディレクトリではなく、このスキル自体の場所を基準に解決してください。

PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
PREFIX="$PRODUCT_ROOT/scripts/contextual-prefix.py"
BM25="$PRODUCT_ROOT/scripts/bm25-index.py"
RETRIEVE="$PRODUCT_ROOT/scripts/retrieve.py"
RERANK="$PRODUCT_ROOT/scripts/rerank.py"
test -f "$PREFIX" && test -f "$BM25" && test -f "$RETRIEVE" && test -f "$RERANK"

パイプライン

1. contextual-prefix.py はページを段落の境界で分割し、元のチャンクと短いページレベルのプレフィックスを保存します。
2. bm25-index.py は、コンテキスト情報を付与したテキストに対して、標準ライブラリのみを使うローカル BM25 インデックスを構築します。
3. retrieve.py は BM25 候補を選び、必要に応じて再ランキングし、無効なレコードを除外してページ単位で重複を排除し、パスと抜粋を返します。
4. 呼び出し元は返されたページを読み取り、統合を行います。検索結果そのものは根拠ではありません。

ローカルで準備する

まずプレビューし、その後、ネットワークへの送信なしで合成プレフィックスを構築します。

python3 "$PREFIX" --vault "$VAULT" --all --no-llm --peek
python3 "$PREFIX" --vault "$VAULT" --all --no-llm
python3 "$BM25" --vault "$VAULT" build
python3 "$RETRIEVE" --vault "$VAULT" "wiki" --top 1 --no-rerank --explain

チャンクファイルとインデックスファイルは、破棄可能なランタイム状態です。増分プレフィックス生成では、チャンクのハッシュ、ページのハッシュ、プロバイダー／モデルのプロファイルが引き続き一致するレコードをスキップします。このプロファイルのない旧形式のレコードは、明示的なビルド時に再生成されます。全件スキャンが完了すると、削除済みページの余分なレコードが削除されます。また、プレフィックス生成処理はチャンクセットを変更する前に BM25 インデックスを無効化し、古くなったデータが混在するインデックスが提供されないようにします。 プレフィックス生成と BM25 のビルド処理は、他のすべての書き込み処理と Vault 全体の排他ロックを共有します。Vault が使用中の場合は、安全側に倒して処理を失敗させ、不完全なインデックスが公開されないようにします。

コンテキスト情報付きプレフィックスのプライバシー

合成プレフィックスには、ローカルのフロントマターとページテキストのみを使用します。明示的な Anthropic API プロファイルでは、ページ本文を端末外に送信することがあり、ユーザーの同意に加えて --allow-egress と設定済みの API キーが必要です。Claude CLI による生成段階や、暗黙的なサブプロセスへのフォールバックはありません。API キーやインストール済みバイナリを根拠に、同意があると判断してはなりません。まず対象範囲をプレビューし、どのプロバイダーにどのデータが送られるのかを明示してください。

リモートの Ollama エンドポイントにも明示的な承認と --allow-remote-ollama が必要です。デフォルトの再ランカーは localhost のみを受け付けます。

ローカルモデルのプレフィックスは、個別に明示して選択するオプションです。インストール済みの正確な name:tag を使用してください。サーバーは起動されず、モデルもインストールまたはプルされません。

python3 "$PREFIX" --vault "$VAULT" --all --local-ollama --ollama-model installed:tag --peek
python3 "$PREFIX" --vault "$VAULT" --all --local-ollama --ollama-model installed:tag

プレフィックスアダプターは、ページテキストを送信する前に、サーバーでクラウド機能が無効になっていることと、ローカルモデルの ID を検証します。事前確認に対応していない場合や事前確認を利用できない場合、新規または変更されたチャンクに限り、合成プレフィックスにフォールバックします。同じエンドポイントとモデルのプレフィックスはそのまま維持されるため、一時的な障害が発生しても、変更のない Vault のチャンクと BM25 インデックスは変更されません。この要件により、古い Ollama サーバーは対象外となる場合があります。 再ランキングとタイル分割では、クエリ、ページ、チャンク、埋め込みキャッシュの処理前にも、同じローカル限定の証明を使用します。--allow-remote-ollama が承認するのはエンドポイントであり、サーバーによるクラウドへの処理委任ではありません。 正確なポリシー、クラウドモデルの選択、検証の制限については、プレフィックスプロバイダーを参照してください。再ランカーには独自のモデルおよびエンドポイントのポリシーがあります。ローカルプレフィックスを選択しても、再ランキングは有効になりません。

クエリ

読み取り専用で検索する場合は、事前構築済みの BM25 インデックスを使用します。

python3 "$RETRIEVE" --vault "$VAULT" "$QUERY" --top 5 --no-rerank --explain

明示的に再ランキングを要求する場合は、--no-rerank を省略してください。デフォルトでは Ollama の多言語対応モデル nomic-embed-text-v2-moe（約 958 MB）を使用します。この製品がモデルを自動的にダウンロードすることはありません。インストール済みのより小型で英語向けの v1.5 モデルを使うには、--model nomic-embed-text を明示的に指定してください。Nomic モデルでは、クエリに search_query:、候補テキストに search_document: を使用します。Nomic v2 の入力コンテキストは 512 トークンで、Ollama はデフォルトで、それより長い埋め込み入力を切り詰めます。BM25 は引き続きチャンク全体をスコアリングします。埋め込みは、モデル、検証済みダイジェスト、入力スキーム、プレフィックスを付加した入力そのもののハッシュが完全に一致する場合にキャッシュされます。ローカルの Ollama サービスが見つからない場合、HTTP 応答が不正な場合、選択したモデルが見つからない場合、ベクトルが使用できない場合、またはいずれかの候補の埋め込みに失敗した場合は、結果セット全体を元の BM25 順に戻します。コサイン類似度と BM25 のスコア尺度が混在することはありません。

クエリ入力は正規化後の 8,000 文字までに制限され、結果数は 1～1,000 である必要があります。サイズ超過のクエリや無効な上限値は、検索結果が空だったかのように見せるのではなく、対処方法が分かる使用方法エラーになります。タグなしのモデル指定は、インストール済みのタグなしの名前またはその :latest エイリアスにのみ一致します。ほかのタグを選択する場合は、明示的に指定してください。

必要に応じて、直接診断を実行してください。

python3 "$BM25" --vault "$VAULT" stats
python3 "$BM25" --vault "$VAULT" query "$QUERY" --top 10
python3 "$RERANK" --vault "$VAULT" "$QUERY" --peek
python3 "$RERANK" --vault "$VAULT" "$QUERY" --model nomic-embed-text --peek

整合性ルール

• 相対パスのチャンクパスとページパスのみを受け入れ、解決後の参照先がそれぞれ $VAULT/.vault-meta/chunks/ と $VAULT/wiki/ の配下にあることを確認します。
• ハッシュのない旧形式のチャンクレコードは拒否し、キャッシュレコードの構築または提供前に、チャンク本文、ページ、インデックスの各ハッシュが一致することを必須とします。
• 絶対パス、シンボリックリンクによる配下からの逸脱、ページの欠落、チャンク ID の不一致、ページハッシュの変更、古いインデックスとチャンクのハッシュの組み合わせを拒否します。
• 候補セット全体を再ランキングしてから、ページ単位で重複を除去し、その後に --top を適用します。
• インデックスが空であれば、正当な検索結果なしの状態です。インデックスが存在しない、または破損している場合、retrieve.py は固定の再構築コマンドを表示して終了コード 10 で終了します。呼び出し側は標準の Vault クエリ／テキスト検索経路にフォールバックし、検索結果を捏造しません。
• 再現可能な Vault 固有のベンチマークによって算出されていない限り、ベンチマークのパーセンテージを引用しないでください。

事前構築済みインデックスを、bench --queries FILE --vault VAULT を使って明示的なラベルと照合して評価します。再現率、MRR、ラベルの欠落、負例については、オフライン検索評価を参照してください。この測定は読み取り専用で、インデックスを暗黙に再構築したり、モデルを呼び出したりすることはありません。

チェックポイント

キャッシュの準備状況とプライバシーの境界を確認し、語彙的ランキングと意味的ランキングのどちらが必要かを検討し、返されたパスとソースの鮮度を検証します。維持管理しているローカルのクエリセットを使って検索漏れを測定し、改善を続けてください。