turbovec: RAG 인덱스가 먹는 램을 8분의 1로

RAG를 만들면 문서를 임베딩으로 바꿔 저장해요. 이 벡터를 float32²로 들고 있으면 768차원 1,000만 개가 31GB예요. 모델을 올리기도 전에 램이 먼저 차요.

turbovec은 이 벡터를 차원당 2비트나 4비트로 압축해 들고, 압축된 상태로 검색해요. 같은 1,000만 개가 4GB로 줄어요.

서버를 따로 띄우지 않는 라이브러리예요. 프로세스 안에서 돌고 파일 하나로 저장돼서, 기존 파이프라인³에 끼워 넣는 방식이에요.

float32는 차원당 4바이트, 4비트는 0.5바이트, 2비트는 0.25바이트예요. 이론값으로는 8배와 16배가 되는데, README는 실제 측정값으로 7.8배와 15.5배를 적어요.

100K 벡터 1536차원 기준으로 float32가 586MB, 4비트가 75MB, 2비트가 38MB예요. 인덱스 크기를 이 비율로 미리 잡아 두면 램 부족을 피할 수 있어요.

pip으로 설치하고 넘파이 배열을 그대로 넣어요. 넣은 벡터는 바로 검색되고, 따로 학습시키는 단계가 없어요.

입력은 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예요. 압축 폭을 정할 때 이 값을 봐야 해요.

100K 임베딩, k=64, 1,000개 질의, 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 자체는 프로세스 밖으로 나가지 않아요.

그래프 인덱스가 필요한 작업에는 권장하지 않아요. turbovec은 모든 벡터를 훑어서 코퍼스가 커지면 비용이 선형으로 늘어요. 100K에서 8코어 기준 0.13~0.25ms이고, 수억 개 뒤에서 엄격한 지연을 요구하는 자리에는 HNSW나 IVF가 맞아요.

정확한 float 결과가 필요해도 안 돼요. 양자화⁴는 손실이 있어서 4비트에서 상위 1개가 정답과 96~98% 일치해요. 자기 데이터 일부로 리콜을 확인하는 편이 안전해요.

서버가 필요해도 안 돼요. 네트워크 API⁵나 복제, 멀티테넌시는 없고, 그런 기능이 있는 스택에 끼워 넣는 부품이에요.

차원은 8의 배수여야 하고 16,384를 넘으면 안 돼요. 비트 폭은 2와 4만 지원해요.