turbovec：RAGインデックスのメモリを8分の1に

RAGでは文書を埋め込みに変えて保存します。float32²で持つと768次元1000万件が31GBです。モデルを載せる前にメモリが埋まります。

turbovecはこのベクトルを次元あたり2ビットか4ビットで圧縮して保持し、圧縮したまま検索します。同じ1000万件が4GBになります。

サーバーを別に立てないライブラリです。プロセス内で動き1ファイルに保存されるため、既存のパイプライン³に組み込めます。

float32は次元あたり4バイト、4ビットは0.5、2ビットは0.25なので計算上は8倍と16倍です。READMEは実測で7.8倍と15.5倍と書いています。

10万件・1536次元でfloat32が586MB、4ビットが75MB、2ビットが38MBです。この比率で見積もればメモリ不足を避けられます。

pipで導入し、NumPy配列をそのまま渡します。入れたベクトルはすぐ検索でき、学習の段階はありません。

入力は2次元float32である必要があります。他の型は黙って変換せずエラーになるため、変換ミスを早く見つけられます。

返るスコアは内積です。コサイン類似度を使うなら入れる前に正規化します。

import numpy as np
from turbovec import TurboQuantIndex

vectors = np.load("embeddings.npy").astype(np.float32)  # (n, 1536)
index = TurboQuantIndex(dim=1536, bit_width=4)
index.add(vectors)

scores, slots = index.search(vectors[:1], k=5)
index.sync("index.tv")

4ビット検索はFAISSより3.8〜5.1倍速いです。ARMで4.0倍、x86で4.9倍と両方で上回ります。

recall@1は4ビットが0.959と0.981、FAISSが0.966と0.971です。1536次元と3072次元の結果です。

2ビットは0.901と0.931に下がります。次元が低いとさらに落ち、GloVe 200次元は0.572です。幅を決めるときはこの値を見ます。

10万件の埋め込み、k=64、1000クエリ、5回の中央値をGCP c4a-standard-8(ARM)とc3-standard-8(x86)で測定した値です。

学習段階が無いため、入れたベクトルは即座に検索できます。文書を集め続けるパイプラインでも再インデックスは不要です。

削除はマイクロ秒単位です。FAISSは削除のたびにコードを整理するため0.19〜1.03秒かかります。

保存は変わった部分だけを書きます。インデックスが大きくてもミリ秒で終わり、途中で切れても最後の保存地点までは残ります。

許可したid一覧を渡すとその中だけを探します。権限や時間条件をインデックスの外で決めて検索に渡す形です。

idで管理するならIdMapIndexを使います。スロット番号ではなく自分で決めた番号で出し入れするため、他システムのキーと合わせやすいです。

from turbovec import IdMapIndex

index = IdMapIndex(dim=1536, bit_width=4)
index.add_with_ids(vectors, ids)

allowed = np.array([1001, 1003, 1042], dtype=np.uint64)
scores, ids = index.search(query, k=10, allowlist=allowed)

LangChain、LlamaIndex、Haystack、Agno向けのストアがあり、各フレームワークのメモリ内ストアと同じインターフェースなので差し替えるように入ります。

埋め込みモデルをローカルで動かせばインデックスまで全てオフラインで動きます。turbovec自体はプロセスの外に出ません。

グラフインデックスが必要な用途には勧めません。全ベクトルを走査するため件数に比例して費用が増えます。10万件では8コアで0.13〜0.25msで、数億件の背後で厳しい遅延が要る場所にはHNSWやIVFが適します。

正確なfloat結果が必要な場合も不向きです。量子化⁴は損失があり、4ビットで上位1件が正解と96〜98%一致します。自分のデータの一部でリコールを確認すると安全です。

サーバーでもありません。ネットワークAPI⁵や複製、マルチテナントは無く、それらを持つスタックに組み込む部品です。

次元は8の倍数で16,384以下である必要があります。ビット幅は2と4のみです。