Show HN: RAGベクトルのstale（陳腐化）、orphaned（孤立）、削除済みだが取得可能なものを検出するツール

rag-staleness-check 単一のpgvector、Qdrant、またはChromaインデックスに対する読み取り専用のstale（陳腐化）、orphan（孤立）、duplicate（重複）、retrievability（取得可能性）チェック。RAGproof "decayed RAG index" teardownのオープンソース部分です（完全な解説記事 + マルチエンジンレジャー検証済み手法）。このツールは、既にインデックス化された自身のベクトルデータベースに対して実行され、以下の情報を提供します。 staleness（陳腐化）：ソースドキュメントが変更されたインデックス化されたチャンク（ドキュメントごとのlast_modifiedを持つマニフェストと、行ごとのlast_modifiedを格納するエンジン自体が必要です）。 orphans（孤立）：マニフェストにソースドキュメントがもはや存在しないインデックス化されたチャンク。 duplicates（重複）：ほぼ同一のチャンク（コサイン類似度 >= しきい値、デフォルト0.98）。チャンクごとのコンテンツハッシュを格納している場合は、厳密なハッシュチェックも行います。 retrievable_after_delete（削除後取得可能）：基本的なプローブです。削除済みとみなしたIDについて、ベクトルがIDによって物理的に取得可能か（ストレージレイヤーの永続性）、トップk検索結果にまだ表示されるか（機能的リーク）を確認します。 これは読み取り専用です。エンジンに対して書き込み/削除/アップサートメソッドを呼び出すことはありません。「Read-only guarantee」セクションで、それがどのように強制され、その限界について説明しています。 このツールが行わないこと これは単一エンジン、レジャーフリー、セルフサービスのスライスです。以下は含まれていません。 マルチエンジンオーケストレーション（各エンジンに対して自分で一度実行してください）。 GDPR第17条のレポートパック（署名付き証拠、検証可能な消去レポート）。 エンジン固有の詳細チェック（pgvectorのデッドタプル/VACUUMの詳細、Qdrantのオプティマイザーしきい値の詳細、Chromaのディスク上のHNSW成長）。 レジャーベースの精度/再現率ハーネス。ここには正解データはなく、このツールは検出したものを報告しますが、その検出の正確さではありません。 これらはプライベートな有料RAGproof監査にあり、すべての検出結果を3つのエンジンすべてで同時にgit履歴から派生した正解レジャーとクロスバリデーションします。 インストール pip install rag-staleness-check # pgvectorのみ pip install "rag-staleness-check[qdrant]" # + Qdrant pip install "rag-staleness-check[chroma]" # + Chroma pip install "rag-staleness-check[all]" # すべて または、インストールせずに： pipx run rag-staleness-check --engine pgvector --dsn "$DSN" --source ./docs_manifest.json Python 3.10+が必要です。 使用方法 rag-staleness-check \ --engine pgvector \ --dsn "postgresql://readonly_user:pw@localhost:5432/mydb" \ --pg-table chunks \ --pg-doc-id-column doc_id \ --pg-last-modified-column last_modified \ --pg-content-hash-column content_sha256 \ --source ./docs_manifest.json \ --deleted-ids ./deleted_ids.json \ --out findings.json これは標準出力にスコアカードを表示し、完全な結果を --out（デフォルトはfindings.json）に書き込みます。チェックに必要な入力が不足している場合（--sourceがない、行ごとのメタデータが設定されていない、--deleted-idsがないなど）、それは誤解を招くようなクリーンな0%をサイレントに表示する代わりに、「skipped": true」と理由を報告します。 --dsn 各エンジン エンジン --dsn フォーマット 例 pgvector Postgres DSN postgresql://user:pw@localhost:5432/db qdrant Base URL http://localhost:6333 chroma host:port localhost:8000 スキーママッピング テーブル/カラムまたはペイロード/フィールド名は独自のものであり、このツールはフラグを通じて伝えられたもの以外はスキーマについて何も仮定しません。 pgvector (--pg-*): --pg-table (必須), --pg-id-column (デフォルト id), --pg-vector-column (デフォルト embedding), --pg-doc-id-column, --pg-last-modified-column, --pg-content-hash-column。最後の3つはオプションであり、省略するとstaleness / orphans / duplicatesチェックの厳密なハッシュパスがskipped / zero-coverageと報告される原因となります。 Qdrant / Chroma (--collection 必須、およびペイロード/フィールド名): --doc-id-field (デフォルト doc_id), --last-modified-field (デフォルト last_modified), --content-hash-field (デフォルト content_sha256)。 マニフェスト (--source) どのドキュメントが存在すべきかを記述したJSONファイル。これはstalenessとorphansの結合キーです。このツールにはレジャーはなく、マニフェストが「現在の状態」の唯一の情報源です。 { "manifest_version": 1, "documents": [ { "doc_id": "handbook/engineering/on-call.md", "last_modified": "2026-06-01T00:00:00Z", "content_sha256": "オプション、ドキュメントレベル、情報提供のみ" } ] } doc_idは、インジェストパイプラインが各インデックス化されたチャンクのdoc-idカラム/フィールドに書き込んだ値と一致する必要があります（上記のスキーママッピングを参照）。last_modifiedは、stalenessチェックを実行したい場合にのみ必要です。ここでのcontent_sha256はドキュメントレベルであり、純粋に情報提供用です。重複検出の入力ではありません（下記参照）。完全な例はexamples/docs_manifest.jsonにあります。 削除済みIDプローブ (--deleted-ids) 削除済みとみなしているIDのJSON配列：["chunk-abc123", "chunk-def456"] それぞれについて、ベクトルがIDによってまだ取得可能か（ストレージレイヤーの永続性）、そしてもしそうなら、トップkセルフクエリにまだ表示されるか（機能的リーク）をチェックします。この区別は重要です。EDPBガイドライン05/2019によると、消去は検証可能で不可逆的でなければなりません。検索結果からレコードを抑制するだけでは、基盤となるベクトルがまだ存在する場合、それだけでは十分ではありません。findings.jsonのretrievable.framingフィールドがこれを実行ごとに詳しく説明します。 読み取り専用保証 このツールはエンジンに対して書き込み/削除/アップサートメソッドを呼び出すことは決してありません。これは2つの方法で強制されます。 構造的に、静的テストを通じて - tests/test_no_write_methods.py はsrc/rag_staleness_check/下のすべてのファイルの実際の構文ツリーをウォークし、書き込み/削除/アップサート形式のメソッドが呼び出された場合、またはSQL書き込みステートメントがexecute()/executemany()に渡された場合にビルドを失敗させます。これは単なる部分文字列grepではなく、実際の構文を解析します。 実行時に、pgvectorの場合 - すべての接続はSET default_transaction_read_only = on で開かれ、rag_staleness_check.readonly.assert_pg_read_only() はクエリ実行前にSHOW default_transaction_read_only を再チェックし、オンでない場合は続行を拒否します。これは、コネクションプーラー（例：PgBouncer）がセッションレベルのSETをサイレントに飲み込むことに対する防御策です。 QdrantとChromaは、クライアントに「このセッション/APIキーは読み取り専用か」をチェックする公開された方法を提供していません。それはデプロイメント側のRBACであり、クライアントライブラリが報告できるものではありません。これら2つのエンジンでは、強制は上記の静的テストと、デプロイメント側のスコープ設定です。エンジンがサポートしている場合は、読み取り専用スコープのAPIキー/トークンで接続してください。pgvectorの実行時アサーションに相当するものはQdrantとChromaにはありません。同等性がない場合にそれを暗示するのではなく、ここでフラグを立てています。pgvectorで追加の保証を得るには、このツールだけに依存するのではなく、ロックダウンされたロールを通じて接続してください： CREATE ROLE rag_staleness_check_readonly NOSUPERUSER LOGIN PASSWORD '...'; GRANT CONNECT ON DATABASE mydb TO rag_staleness_check_readonly; GRANT USAGE ON SCHEMA public TO rag_staleness_check_readonly; GRANT SELECT ON chunks TO rag_staleness_check_readonly; テレメトリ デフォルトのテレメトリはありません。何も自動的に収集または送信されません。--share-anonymous-scorecardは、共有される正確な匿名化されたペイロード（集計カウント + エンジンタイプのみ - DSN、ホスト名、doc_id、chunk_idは決して含まれません）を表示する明示的なオプトインです。まだバックエンドは設定されていないため、実際にネットワークを介して何も送信されません。このフラグは、将来のオプトイン送信エンドポイントのために予約されています。環境変数DO_NOT_TRACKが設定されている場合、フラグが渡されていてもこれがオフになります。 別途、このツールはChromaに接続する際にchromadb自体のクライアントサイドテレメトリ（anonymized_telemetry=False）を無効にします。chromadbパッケージは、上記とは独立して、デフォルトでオンになっているPostHogベースのテレメトリをバンドルしています。これを有効のままにしておくと、このツールのコード自体がネットワークに接続しないにもかかわらず、--engine chromaユーザーにとって「デフォルトのテレメトリなし」という約束を静かに破ることになります。1つの化粧品のしわ：chromadb==0.6.3では、設定は有効になります（client._system.settings.anonymized_telemetryがFalseであることを確認済み）が、起動イベント（ClientStartEvent）がそれを一貫して尊重しないコードパスを通じて発火しようとし、リクエストを構築する前にcapture() takes 1 positional argument but 3 were given というエラーが発生します。