概要
- turbovec は、Google Researchの TurboQuantアルゴリズム をベースにした、Pythonバインディング付きのRust製ベクトルインデックス。
- 圧倒的な圧縮率 と 高速な検索性能 で、FAISSを上回る実績。
- オンライン追加・削除・インクリメンタル保存 など、運用に便利な機能を多数搭載。
- 検索時フィルタリング や 外部ID管理、多様なフレームワーク統合に対応。
- プライバシー重視 や 低レイテンシ用途 のRAG構築に最適。
turbovecの特徴と概要
- 10Mドキュメントコーパス をfloat32で格納すると 31GB 必要だが、turbovecなら 4GB で収まり、FAISSよりも高速検索可能。
- TurboQuantアルゴリズム は、データ非依存型の量子化手法。最適に近い歪みで、 トレーニング不要。
- オンラインインジェスト対応。追加したベクトルは即時インデックス化、 再トレーニングやパラメータ調整不要。
- 高速SIMD検索。ARM（NEON SDOT/SMMLA）、x86（AVX-512 VNNI, vpermb, AVX2）に最適化された手書きカーネル。
- FAISS IndexPQFastScan と比較して、4-bitで平均3.4倍、2-bitで23%高速化（両アーキテクチャで実証）。
- インクリメンタル保存。sync(path)で差分のみ保存、fsync1回、クラッシュセーフ設計。
- 検索時フィルタ。idの許可リストやビットマスクを渡せば、その範囲のみからk件返却、 過剰取得やリコール低下なし。
- ローカル完結。データはマシンやVPC外に出ない。オープンソース埋め込みモデルと組み合わせて エアギャップRAG 構築可能。
Pythonでの基本利用例
- pip install turbovec でインストール。
- TurboQuantIndexの作成とベクトル追加：
from turbovec import TurboQuantIndexindex = TurboQuantIndex(dim=1536, bit_width=4)index.add(vectors)index.add(more_vectors)
- 検索例：
scores, indices = index.search(query, k=10)
- 保存・ロード・インクリメンタル保存：
index.write("my_index.tv")loaded = TurboQuantIndex.load("my_index.tv")index.sync("my_index.tv")
- ベクトル・クエリはfloat32型2次元配列（(n, dim)）。他の型は明示的に変換が必要。
安定した外部ID運用（IdMapIndex）
- 外部IDでの追加・削除 が可能なIdMapIndex利用方法：
from turbovec import IdMapIndexindex = IdMapIndex(dim=1536, bit_width=4)index.add_with_ids(vectors, np.array([1001, 1002, 1003], dtype=np.uint64))scores, ids = index.search(query, k=10)index.remove(1002)# O(1)で削除index.write("my_index.tvim")loaded = IdMapIndex.load("my_index.tvim")index.sync("my_index.tvim")
ハイブリッド検索（フィルタ付き検索）
- 他システム（SQL, BM25等）で候補IDを絞り、turbovecで再ランキング。
- 検索時にallowlistを渡すことで、 SIMDカーネル内部で効率的にフィルタ処理。
- 許可リストが小さい場合、 SIMDコストの大部分を回避。
- 出力はmin(k, n_allowed)件を厳密に返却。
フレームワーク統合
- LangChain ：langchain_core.vectorstores.InMemoryVectorStoreを置換
- LlamaIndex ：llama_index.core.vector_stores.SimpleVectorStoreを置換
- Haystack ：haystack.document_stores.in_memory.InMemoryDocumentStoreを置換
- Agno ：agno.vectordb.lancedb.LanceDbを置換
- Rust でもcargo add turbovecで利用可能
TurboQuant vs FAISS 詳細比較
- TurboQuant（TQ+）はFAISS PQより高リコール （R@1）を複数条件で実現。
- d=1536やd=3072の高次元埋め込みでは、TQ+がFAISSを上回る。
- GloVe（低次元）では4-bitでTQ+が優位、2-bitではFAISSがやや優勢だがTQ+校正で逆転。
- FAISS IndexPQ（LUT256, nbits=8, float32 LUT） を強力なベースラインとして比較。
ベンチマーク結果と性能
- 検索速度 ：100Kベクトル、1Kクエリ、k=64、5回中央値
- ARM：4-bitで3.5倍、2-bitで26%高速（SDOT/SMMLAカーネル）
- x86：4-bitで3.4倍、2-bitで20%高速（AVX-512 VNNIカーネル）
- 挿入・削除レイテンシ ：
- 1ベクトルaddで6.3–19.7μs（FAISSの7.6–13.9倍高速）
- 100ベクトルバッチで4.6–16.3μs/ベクトル
- 削除は0.44–1.37μs/回、FAISSは0.19–1.02秒（100K時、桁違いの高速化）
- 保存・ロード ：
- TurboQuantは単一.tvファイルへfsync+アトミックリネーム
- 再開・最初のクエリまでのラウンドトリップも高速
TurboQuantの仕組み
- 各ベクトルは高次元球面上の方向ベクトルとして扱う。
- 正規化 ：ノルムを除去し、方向のみを単位球面上に配置。
- ランダム回転 ：全ベクトルを同じランダム直交行列で回転。各座標が既知の分布（Beta分布）になる。
- 座標ごとの校正（TQ+） ：有限次元では分布が理想からズレるため、各座標に2スカラー（シフト・スケール）を適用し、分布を補正。
- Lloyd-Max符号本 で目標分布に量子化。
利用シーンとメリット
- プライバシー重視、 メモリ効率、 低レイテンシ が求められるRAG用途に最適。
- エアギャップ構成 や 独自埋め込みモデル との組み合わせで、完全ローカル運用が可能。
- 大規模コーパス でも低メモリ・高速・高精度を維持。
より詳細なAPIやドキュメントは docs/api.md を参照。