turbovec

turbovec は、Python バインディングを備えた Rust で記述されたオープンソースのインプロセス ベクター インデックスです。 Google Research の TurboQuant アプローチを実装して、別個のコードブック トレーニング フェーズなしで密なベクトルを圧縮し、アーキテクチャ固有の SIMD カーネルでパックされたコードを検索します。その実用的な魅力は、オンライン取り込み、2 ビットまたは 4 ビットのストレージ、永続性、安定した外部 ID、削除サポート、ホワイトリストでフィルターされた検索、一般的な RAG フレームワーク用のアダプターの組み合わせです。

正しく分類することが重要です。 turbovec はインデックス ライブラリであり、ホストされたベクター データベースや完全な検索サービスではありません。それ自体では、分散レプリケーション、マルチノード シャーディング、バックアップ、認証、テナント管理、ネットワーク APIs、ハイブリッド語彙検索、可観測性、またはコントロール プレーンを提供しません。チームは、周囲の懸念事項を自分のものにする代わりに、ローカル制御とメモリ効率を獲得します。

TurboQuant 圧縮の仕組み

根底にある洞察は、ランダムな直交回転により、高次元の単位ベクトルの座標が予測可能な分布に従うということです。 turbovec は、まず各ベクトルのノルムを方向から分離します。 1 つの共有ランダム回転を適用し、事前計算された Lloyd–Max バケットを使用して回転された座標を量子化します。 2 ビットは座標ごとに 4 つの値を提供します。 4 ビットで 16 になります。コードはビットパックされており、ベクトルごとの補正により、量子化によって生じる体系的な内積収縮が除去されます。

プロジェクトは TQ+ キャリブレーションを追加します。最初の追加では、経験的な分位数を使用して各座標のシフトとスケールを推定し、その後の取り込みのためにそれらの値を凍結します。これは従来の積量子化トレーニングとは異なりますが、最初のバッチがキャリブレーションに影響します。したがって、小さな、または代表的ではない最初の追加は、運用環境の初期化が不十分になる可能性があります。代表的なサンプルをインデックスにシードし、分布ドリフトをテストします。

マーケティングの近道を使わない記憶計算

1,536 次元の float32 ベクトルは、生の座標に 6,144 バイトを使用します。その座標コードは、メタデータの前に 2 ビットで 384 バイト、または 4 ビットで 768 バイトを必要とします。これは、理論上の座標ペイロードの 16 倍または 8 倍の削減に相当します。リポジトリの見出しには、約 31 GB を必要とする 1,000 万個の文書の float32 コーパスが約 4 GB に収まると書かれています。この例は特定の次元と表現を反映しているため、すべてのコーパスに一般化すべきではありません。

キャパシティ プランニングでは、外部 ID、ベクトルごとの補正/ノルム値、キャリブレーション データ、アライメント、アロケーター オーバーヘッド、削除されたスロット、アプリケーション メタデータ、クエリ バッファー、および元のドキュメント ストアを追加する必要があります。埋め込みが RAG メモリの請求額全体になることはほとんどありません。実際の永続インデックスをロードし、同時クエリを処理した後、常駐セットのサイズを測定します。

API がサポートするもの

numpyをnpとしてインポート
turbovec から IdMapIndex をインポート

インデックス = IdMapIndex(寸法=1536、ビット幅=4)
Index.add_with_ids(vectors.astype(np.float32), ids.astype(np.uint64))
スコア、result_ids =index.search(query.astype(np.float32)、k=10)
インデックス.削除(ドキュメントID)
Index.write("corpus.tvim")
復元 = IdMapIndex.load("corpus.tvim")

Python API は、非 float32 ベクトルを黙って変換するのではなく、意図的に拒否します。内部スロットは削除やメンテナンス後に変更される可能性があるため、安定した ID が重要です。永続性によりローカルでの再起動が実用的になりますが、アプリケーションには引き続きアトミック パブリケーション、チェックサム、バックアップ/バージョン ポリシー、ライブラリ アップグレード間の互換性テストが必要です。

フィルタリングされた検索は有意義な差別化要因です

マルチテナント、タイムウィンドウ、またはパーミッションを意識した取得の場合、アプリケーションはまず SQL、BM25、ACL サービス、または別のシステムから許可された ID セットを生成し、次に turbovec にそれらの候補のみをランク付けするように依頼できます。フィルタリングは、SIMD パス内で 32 ベクトル ブロック粒度で行われます。空のブロックはスキップでき、許可されていないスロットはヒープ挿入前に拒否されるため、選択フィルターにより高密度スコアリング作業の多くを回避できます。

これは、グローバル トップ K を取得して未承認の結果を破棄するよりも優れています。返される有効なドキュメントが少なすぎて、ランキング情報が漏洩する可能性があります。ホワイトリストを正しく構築し、それを認証されたテナントにバインドし、空のセット、小さなセット、巨大なセット、および急速に変化するセットをテストすることは、依然として呼び出し元の責任です。最終的なドキュメントの取得における唯一の認証チェックとしてメタデータ フィルタリングを使用しないでください。

公開されているベンチマークの見方

比較のベースラインは FAISS です インデックスPQ/IndexPQFastScanすべての FAISS インデックス タイプではありません。フラット完全一致検索、HNSW、IVF-PQ、GPU インデックス、および管理されたデータベースは、リコール、レイテンシー、メモリ、操作曲線上のさまざまな点を解決します。まずリポジトリのベンチマークを再現し、次にデータと許容目標を一度に 1 つの要素に置き換えます。

便利な RAG 評価プロトコル

1. 埋め込みを凍結します。 実稼働用に計画されている正確なモデル、正規化、寸法、および距離の規則を使用します。
2. グラウンドトゥルースを作成します。 信頼できるフラット実装で正確な上位 k 近傍を計算し、タスクの関連性の判断を個別に維持します。
3. 両方のビット幅をテストします。 2 ビットと 4 ビットを相互に比較するだけでなく、float32 または完全一致検索を使用して比較します。
4. クエリを階層化します。 一般的なケース、まれなケース、多言語のケース、短いケース、長いケース、重複したケース、ドメイン外のケースが含まれます。
5. 運動摂取。 代表的なバッチで初期化し、後でディストリビューションを追加し、ID を削除し、永続化し、リロードし、決定的な動作を検証します。
6. ベンチマークフィルター。 フィルターなしと許可リストを 0%、0.1%、1%、10%、50%、100% カバレッジ (敵対的ブロック レイアウトを含む) で測定します。
7. 負荷テスト。 p50/p95/p99 のレイテンシ、スループット、CPU 使用率、常駐メモリ、および実際の同時実行時のテール動作を記録します。
8. 答えを評価します。 検索再現率、リランカーの品質、引用の正しさ、最終回答の成功を測定します。より高速な近似近傍は、アプリケーションの結果が存続する場合にのみ価値があります。

意思決定指標

フレームワークの統合

このリポジトリには、使い慣れたインターフェイスを維持しながら、メモリ内参照ストアを置き換える LangChain、LlamaIndex、Haystack、および Agno 用のアダプターが文書化されています。これにより概念実証を迅速に行うことができますが、「ドロップイン」とはパブリック ソフトウェア サーフェスを指し、同一のスコアリング、フィルタリング、削除、永続化、スレッド化、または障害セマンティクスではありません。デプロイする前に、各フレームワークの取得テストを実行し、互換性のあるバージョンを固定します。

代替案

制限と生産上のリスク

• 近似圧縮により、特にビット幅が激しい場合や次元が低い場合に、最近傍順序が変更される可能性があります。
• CPU 固有のカーネルは、ARM、AVX2、および AVX-512 ハードウェア間でベンチマーク結果を転送すべきではないことを意味します。
• 最初の追加キャリブレーション、埋め込みモデルおよびコーパス ドリフトの変更には、明示的な移行テストが必要です。
• ローカル展開では、ベクターを管理下に置きますが、暗号化、アクセス制御、安全なバックアップは自動的に追加されません。
• サービス境界と回復戦略が意図的に設計されていない限り、プロセス中のクラッシュはホスト アプリケーションに影響を与えます。
• プロジェクトは進化しています。リリースを固定し、変更ログ/セキュリティ ガイダンスを検査し、永続化インデックスの互換性を検証します。

よくある質問

turbovec はベクトル データベースですか?

いいえ、ベクトルインデックスライブラリです。アプリケーションは、必要に応じてドキュメント ストレージ、ネットワーキング、承認、レプリケーション、監視、ライフサイクル操作を提供する必要があります。

オフラインのトレーニング手順は必要ですか?

従来のコードブック トレーニングを回避し、オンライン追加をサポートします。 TQ+ は最初の追加時に座標ごとの値を調整するため、初期化バッチには依然として注意が必要です。

2 ビットまたは 4 ビットを選択する必要がありますか?

メモリがバインディング制約であり、測定されたタスクの再現率が許容範囲内である場合は、2 ビットを使用します。 4 ビットでは、通常、座標コードのストレージの約 2 倍でより高い忠実度が得られます。両方をベンチマークします。

フィルター検索はテナントのセキュリティを強化しますか?

ランキングをホワイトリストに効率的に制限できます。アプリケーションは、ソース コンテンツを返す前に、正しいリストを作成し、承認を再チェックする必要があります。

FAISS という速度の主張は普遍的なものですか?

いいえ。公開された結果には、指定されたハードウェア、データセット、ディメンション、ビット幅、FAISS PQ/FastScan 構成が含まれています。 x86 2 ビットの結果には、FAISS の方が高速な場合が含まれます。

エアギャップは可能ですか?

インデックスはローカルで実行され、管理されたサービスは必要ありません。完全なエアギャップ RAG スタックには、ローカルの埋め込み、ドキュメント、パッケージ/モデルの来歴、および制御された更新も必要です。

一次情報源

• turbovec 公式リポジトリとベンチマークのドキュメント
• turbovec API リファレンス
• 再現可能なベンチマーク スクリプトと結果
• TurboQuant 研究論文
• RaBitQ 論文が長さの修正のために引用されました
• FAISS FastScan テクニカル リファレンス
• turbovec Python パッケージ
• turbovec Rust クレート

最終レビュー日は 2026 年 7 月 25 日です。特に明記されていない限り、パフォーマンス ステートメントの範囲はリポジトリの公開設定に限定されます。導入前に、コーパス、埋め込みモデル、ハードウェア、フィルター配布上で再現します。