Show HN: RAGベクトルのstale(陳腐化)、orphaned(孤立)、削除済みだが取得可能なものを検出するツール
Show HN: Find stale, orphaned, deleted-but-retrievable RAG vectors (github.com)
要約
このツールは、pgvector、Qdrant、Chromaの単一インデックスに対して、RAG(Retrieval-Augmented Generation)におけるベクトルの陳腐化、孤立、重複、および削除後も取得可能な状態(機能的リーク)を検出します。ソースドキュメントの変更や削除を追跡し、インデックスの整合性を維持するための読み取り専用のチェックを提供します。
全文翻訳
rag-staleness-check
単一のpgvector、Qdrant、またはChromaインデックスに対する、読み取り専用のStale(陳腐)、Orphaned(孤立)、Duplicate(重複)、およびRetrievable(取得可能)チェック。
既存のベクトルデータベースを指し示すと、以下の項目が報告されます。
- Staleness(陳腐化): インデックス化されたチャンクのソースドキュメントが、インデックス作成後に変更されている場合。これには、ドキュメントごとの
last_modifiedを持つマニフェストが必要で、エンジンは行ごとのlast_modified値を保存する必要があります。 - Orphans(孤立): ソースドキュメントがマニフェストに全く存在しなくなったインデックス化されたチャンク。
- Duplicates(重複): ほぼ同一のチャンク(デフォルトでコサイン類似度が0.98以上)、およびチャンクごとのコンテンツハッシュを保存している場合は、厳密なハッシュチェック。
- Retrievable-after-delete(削除後の取得可能性): 削除済みと見なしているIDに対する基本的なプローブ。IDによるベクトルの取得可能性(ストレージレイヤーの永続性)と、トップK検索結果にまだ表示されるかどうか(機能的な漏洩)をチェックします。
このツールは読み取り専用であり、エンジンの書き込み、削除、upsertメソッドを呼び出すことはありません。Read-only guarantee(読み取り専用保証)で、その強制方法と、強制が及ばない範囲について説明しています。
Scope(範囲)
各実行は1つのエンジンを対象とし、比較対象となる正解データはありません。そのため、以下の機能は実行しません。
- マルチエンジンの実行(エンジンごとに一度実行します)
- GDPR第17条の報告(署名された証拠や検証可能な消去レポートなど)
- エンジン固有の詳細チェック(pgvectorのデッドタプルとVACUUM、Qdrantのオプティマイザー閾値、ChromaのオンディスクHNSWの成長など)
- 精度/再現率スコアリング。検出されたものを報告しますが、その検出の正確さは評価しません。
Install(インストール)
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+が必要です。
Usage(使用方法)
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がないなど)、理由とともに"skipped": trueが報告されるため、意味のないクリーンな0%が表示されることはありません。
--dsn エンジン別
| Engine(エンジン) | --dsn フォーマット | 例 |
|---|---|---|
pgvector | Postgres DSN | postgresql://user:pw@localhost:5432/db |
qdrant | Base URL | http://localhost:6333 |
chroma | host:port | localhost:8000 |
Schema mapping(スキーママッピング)
このツールは、フラグで渡された情報以外、テーブル、カラム、ペイロード、またはメタデータ名について一切仮定しません。
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またはカバレッジゼロと報告されます。
QdrantおよびChromaの場合、--collection(必須)に加え、ペイロードまたはメタデータフィールド名が必要です: --doc-id-field(デフォルトdoc_id)、--last-modified-field(デフォルトlast_modified)、および--content-hash-field(デフォルトcontent_sha256)。
Manifest(マニフェスト)(--source)
存在するべきドキュメントのリストを含むJSONファイルです。StalenessとOrphansの結合キーであり、現在の状態を判断するためのツールの唯一の真実の情報源です。
{
"manifest_version": 1,
"documents": [
{
"doc_id": "handbook/engineering/on-call.md",
"last_modified": "2026-06-01T00:00:00Z",
"content_sha256": "optional, doc-level, informational only"
}
]
}
doc_idは、インジェストパイプラインが各チャンクのdoc-idカラムまたはフィールドに書き込んだものと一致する必要があります(上記のスキーママッピングを参照)。last_modifiedはStalenessチェックにのみ必要です。ここでのcontent_sha256はドキュメントごとで情報提供のみを目的としており、重複検出では使用されません(下記参照)。完全な例はexamples/docs_manifest.jsonにあります。
Deleted-ids probe(削除済みIDプローブ)(--deleted-ids)
削除済みと見なしているIDのJSON配列です。
["chunk-abc123", "chunk-def456"]
各IDについて、プローブはIDによるベクトルの取得可能性(ストレージレイヤーの永続性)をチェックし、取得可能な場合はトップKセルフクエリで返されるかどうか(機能的な漏洩)をチェックします。この2つを区別することは価値があります。EDPB Guidelines 05/2019(忘れられる権利に関するガイドライン)の下では、消去は検証可能で不可逆的でなければならず、検索結果からレコードを隠すだけでは、ベクトルがまだ保存されている場合には不十分です。findings.jsonのretrievable.framingフィールドは、実行ごとにこれを繰り返します。
Read-only guarantee(読み取り専用保証)
このツールは、エンジンの書き込み、削除、upsertメソッドを呼び出すことは決してありません。これを強制する2つの方法があります。
- 静的テスト:
tests/test_no_write_methods.pyは、src/rag_staleness_check/下のすべてのファイルを解析し、書き込み/削除/upsertスタイルのメソッドの呼び出し、またはexecute()/executemany()に渡されたSQL書き込みステートメントが見つかった場合にビルドを失敗させます。これは部分文字列のgrepではなく構文ツリーを走査するため、このREADMEやdocstringでの誤検知を防ぎます。 - pgvectorの場合、実行時チェック。すべての接続は
SET default_transaction_read_only = onで開かれ、rag_staleness_check.readonly.assert_pg_read_only()は、クエリの前にSHOW default_transaction_read_onlyを読み取り、それが'on'でない限り続行を拒否します。これは、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;
Telemetry(テレメトリ)
デフォルトのテレメトリはありません。何も収集または送信されません。--share-anonymous-scorecardは明示的なオプトインであり、共有される匿名化されたペイロード(集計カウントとエンジンタイプのみ。DSN、ホスト名、doc_id、chunk_idは含まれません)を表示します。バックエンドはまだ設定されていないため、ネットワークを介して何も送信されません。このフラグは将来のオプトインエンドポイントのために予約されています。環境変数DO_NOT_TRACKが設定されている場合、フラグが渡されていても共有はオフになります。
このツールは、Chromaに接続する際にChromaDB自体のクライアントテレメトリ(anonymized_telemetry=False)もオフにします。chromadbパッケージはデフォルトでオンになっているPostHogベースのテレメトリを ship しており、これをオンのままにしておくと、このツールのコード自体は通信しませんが、--engine chromaでのノーテレメトリの約束が破られることになります。
chromadb==0.6.3での1つの化粧的な不具合: 設定は有効になります(client._system.settings.anonymized_telemetry is False)、しかし起動イベント(ClientStartEvent)は、それを無視するコードパスを通過し、リクエストが行われる前に、呼び出しを構築中にcapture() takes 1 positional argument but 3 were givenで失敗します。その行が表示されることがありますが、何も送信されていません。
Known limitations(既知の制限事項)
- 重複検出の厳密ハッシュパスでは、エンジンに保存されたチャンクごとのコンテンツハッシュ(
--pg-content-hash-column/--content-hash-field)が必要です。これが無い場合、チェックはコサインANNのみにフォールバックし、duplicates結果のwarningフィールドにその旨が記載されます。 - Chromaの
snapshot_stats()はライブカウントのみを報告します。オンディスクHNSWディレクトリを測定するには、Chromaホストへのファイルシステムアクセスが必要ですが、これは他者のデプロイメントに対しては得られないため、含まれていません。 qdrant-clientは独自の互換性チェックを実行し、クライアントのマイナーバージョンがサーバーのマイナーバージョンから1以上離れている場合に警告を発する可能性があります(例: "Qdrant client version 1.18.0 is incompatible with server version 1.15.5")。この警告は致命的ではなく、チェックは実行されます。ノイズが多い場合は、qdrant-clientをサーバーのマイナーバージョンにピン留めしてください。- このツールはカウントとペアを報告し、精度や再現率を報告しません。クライアントサイドには自己評価のための正解データがありません。
- 重複検出には、各候補のベクトルが必要です。
get_vectorが何も返さないチャンクは、クエリ対象がないため、コサインANNパスから除外されます。これは「重複ではない」とはカウントされません。
Dependency notes(依存関係に関する注記)
qdrant-clientとchromaはオプションの追加機能です(pip install rag-staleness-check[qdrant]/[chroma]/[all])。そのため、pgvectorのみのユーザーはChromaの重い依存関係をプルしません。- いずれも正確なバージョンにはピン留めされていません。このツールは既に実行中のデプロイメントに接続し、サーバーバージョンはユーザーが制御するため、このツールは制御しません。ハードピンは異なるバージョンのユーザーを壊します。
License(ライセンス)
Apache-2.0。詳細はLICENSEを参照してください。
Contributing(貢献)
IssueやPRを歓迎します。1つのオープンなアイデアとして、表面的なテキストから重複を検出する--method minhashモード(datasketch経由)があり、コサイン埋め込みアプローチの代替または補完として利用できます。