vector-search について
プラグインのベクトル検索経路から、コーパス検索向けの HNSW 埋め込みと、少数の優先パターン向けの WASM ルーターを選ぶためのガイドです。量子化検索、階層型埋め込み、調整方法、CLI の代替手段も扱います。
主な機能
- 01大規模コーパス向け HNSW 検索
- 02RaBitQ 量子化検索
- 03テキストの類似度比較
- 04階層データ向け双曲埋め込み
- 05最大 11 パターンの WASM ルーティング
- 06検索調整と CLI コマンド
活用シーン
- 01500 件以上の文書コーパスを検索
- 02大規模なベクトル集合のメモリ削減
- 03少数パターンへのクエリ振り分け
- 04コードツリーなど階層データの検索
MCP 対応
Ruflo の MCP ツールによる埋め込みの生成と検索、量子化インデックス作成、名前空間横断のメモリ検索、WASM パターンルーティングを説明します。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/vector-searchを入力して読み込まれたか確認します。
詳細
ベクトル検索
このプラグインには、異なる2つのベクトル検索経路があります。適切なものを選んでください。互換性はありません。
| 経路 | ツールファミリー | バックエンド | 容量 | レイテンシ |
|---|---|---|---|---|
| 大規模コーパス | embeddings_* | @claude-flow/memory HNSW（Rust/ネイティブ） | 最大数百万ベクトル | N=20kで約1.9倍、N=5kで総当たり検索比約3.2倍～4.7倍（実測値、recall@10 ≈ 0.99）。クロスオーバーを超えるとANNが優位 |
| ホットパスルーター | ruvllm_hnsw_* | WASMベースのルーター（v2.0.1） | 最大約11パターン（ruvllm-tools.ts:58） | 1ミリ秒未満。高優先度のルーティング向けに設計されており、コーパス検索には不向き |
「12,500倍」という見出しは、大規模な embeddings_search 経路に適用されます。WASMルーターはその経路ではありません。
使用する場面
| 必要なこと | 経路 |
|---|---|
| N ≥ 500件のドキュメントからなるコーパスを検索する | embeddings_search |
| メモリに制約のあるコーパス（5,000ベクトル以上） | RaBitQ量子化。「量子化検索」を参照してください |
| 2つの文字列を比較する | embeddings_compare |
| 階層型／分類体系データ | embeddings_hyperbolic（ポアンカレ球） |
| クエリを最大11個のホットパターンのいずれかにルーティングする | ruvllm_hnsw_route |
| 名前空間をまたいで検索する | memory_search_unified |
標準検索
- ステータスを確認する —
mcp__plugin_ruflo-core_ruflo__embeddings_statusで埋め込みエンジンを確認します。 - 初期化する — アクティブでない場合は、
mcp__plugin_ruflo-core_ruflo__embeddings_initを実行します。 - 生成する — テキスト入力には
mcp__plugin_ruflo-core_ruflo__embeddings_generateを実行します。 - 検索する — クエリを指定して
mcp__plugin_ruflo-core_ruflo__embeddings_searchを実行します。 - 比較する — 類似度を測定するには
mcp__plugin_ruflo-core_ruflo__embeddings_compareを実行します。 - 統合検索 — 名前空間をまたいで検索するには
mcp__plugin_ruflo-core_ruflo__memory_search_unifiedを実行します。
量子化検索（メモリを32分の1に削減）
5,000ベクトル以上のコーパスや、メモリに制約のある環境では、RaBitQの1ビット量子化ワークフローを使用します。5,000ベクトル未満の場合は、再構築のコストが削減量を上回るため、代わりに標準の経路を使用してください。
| 手順 | ツール | 用途 |
|---|---|---|
| 1 | embeddings_init | エンジンをウォームアップ |
| 2 | embeddings_rabitq_build | コーパス読み込み後に1ビットインデックスを一度だけ構築 |
| 3 | embeddings_rabitq_search | ハミング距離による事前フィルタリングで上位N件の候補IDを返す（低コスト） |
| 4 | embeddings_search | 候補セットを任意で正確に再ランキングする（フル精度） |
| 5 | embeddings_rabitq_status | インデックスの健全性、メモリ使用量、構築時間 |
注：
embeddings_rabitq_searchが返すのは候補IDのみです。手順4での再ランキングはユーザーの責任です（embeddings-tools.ts:911のdocstringと同様です）。再ランキングしない場合、結果は近似値です。再ランキングすれば、メモリを32分の1に抑えながらフル精度の品質が得られます。
チューニング
HNSWには、再現率とレイテンシのバランスを調整する3つのパラメーターがあります。「12,500倍」という見出しはデフォルト値を前提としています。ワークロードに合わせて慎重に調整してください。
| プロファイル | efSearch | M | 使用する場面 |
|---|---|---|---|
recall-first | 200 | 32 | 計画時のパターン再現率。ミリ秒単位の速度より品質を重視 |
balanced（デフォルト） | 64 | 16 | 汎用的なセマンティック再現 |
latency-first | 16 | 8 | p99レイテンシが重要なホットパスルーティング |
efSearch は ruvllm_hnsw_create で渡します（ruvllm-tools.ts:64）。現在、M はレジストリレベルの設定です。MCPから調整できるようにする必要があれば、今後対応してください。ライトインデックスの efConstruction はデフォルトで200です（hnsw-index.ts:537）。
HNSWパターンルーター（WASM、最大11パターン）
少数の高優先度パターンをルーティングする場合：
mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_create— WASMインデックスを作成（上限約11件）mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_add— パターンを追加mcp__plugin_ruflo-core_ruflo__ruvllm_hnsw_route— 受信したクエリをルーティング
これはコーパスインデックスではありません。厳選されたパターンのセットを対象とする高速分類器として扱ってください。
双曲埋め込み
階層型データ（コードツリー、組織図）には、ポアンカレ球空間に写像する mcp__plugin_ruflo-core_ruflo__embeddings_hyperbolic を使用します。距離はコサイン距離ではなく測地距離です。
CLI の代替手段
npx @claude-flow/cli@latest embeddings search --query "authentication patterns"
npx @claude-flow/cli@latest embeddings init
npx @claude-flow/cli@latest memory search --query "your query"
パフォーマンス
測定値（出典：scripts/benchmark-intelligence.mjs、ruvector NAPI バックエンド、recall@10 ≈ 0.99）。以前の「150×～12,500×」という数値は総当たりフォールバックによるもので、現在は廃止されています。プロジェクトの CLAUDE.md の「V3 Performance Targets」を参照してください。
| 方法 | 総当たりと比較した測定速度向上 |
|---|---|
| 総当たりスキャン | 基準 |
| HNSW（N=5,000） | 約3.2×～4.7×高速 |
| HNSW（N=20,000） | 約1.9×高速 |
| HNSW（損益分岐点未満の小さなN） | 総当たりと同等／低速 |
| RaBitQ 量子化 | メモリを32×削減、N≈14.7kでクエリあたり0.60 ms |
ruvllm_hnsw_route（n≤11） | ルートあたり1 ms未満、固定コスト |