turbovec 딥다이브
— FAISS보다 빠른 Rust 벡터 인덱스, 학습 없이 16배 압축

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

turbovec은 벡터 인덱스 (vector index, 임베딩 벡터를 저장하고 유사한 것을 빠르게 찾아주는 자료구조)입니다. RAG (Retrieval-Augmented Generation, 검색 증강 생성) 시스템에서 "질문과 가장 비슷한 문서 조각 10개를 찾아와"라는 요청을 처리하는 핵심 부품이죠. 코어는 Rust로 작성됐고, pip install turbovec 한 줄이면 Python에서 바로 씁니다.

특징은 세 가지입니다. ① 학습 제로 — 코드북 훈련, 데이터 보정, 재빌드가 전혀 없습니다. ② FAISS보다 빠름 — 손으로 짠 SIMD 커널이 ARM에서 FAISS FastScan을 10~19% 앞섭니다. ③ 완전 로컬 — 관리형 서비스 없이 내 머신/VPC 안에서만 돕니다. 오픈소스 임베딩 모델과 짝지으면 완전 폐쇄망 RAG 스택이 됩니다.

2왜 주목받는가

트렌딩 이유 · 경쟁 대비 장점.

벡터 DB 시장은 Pinecone 같은 관리형 서비스와 FAISS 같은 로컬 라이브러리로 나뉩니다. 로컬 진영의 표준인 FAISS의 PQ (Product Quantization, 곱 양자화 — 벡터를 조각내 각 조각을 코드북으로 압축)는 강력하지만 한 가지 전제가 있습니다: 먼저 데이터로 코드북을 학습해야 한다는 것. turbovec이 트렌딩 1위에 오른 이유는 이 전제를 깬 구글의 TurboQuant 논문(2025년 4월 공개, ICLR 2026 채택)을 가장 빠르게, 실전 품질로 구현한 레포이기 때문입니다.

또 하나의 매력은 정직한 벤치마크입니다. README가 "우리가 GloVe 저차원에선 FAISS에 3~6점 진다"는 약점까지 그래프와 JSON 원본으로 공개하고, 비교 기준을 논문보다 더 강한 FAISS 기본값으로 잡았다고 명시합니다. 벤치마크 부풀리기가 흔한 분야에서 신뢰를 산 부분입니다.

3기술 스택 전체 지도

Rust 코어 · Python 바인딩 · 벤치마크 인프라.

레포는 Cargo 워크스페이스 (workspace, 여러 Rust 크레이트를 한 저장소에서 함께 빌드하는 구조)로 구성됩니다. 핵심 계산은 전부 turbovec 크레이트(Rust)에 있고, turbovec-python이 그걸 Python으로 노출합니다.

4아키텍처 심화 분석

벡터 하나가 들어가서 검색 결과로 나오기까지.

먼저 전체 그림입니다. 파이프라인은 크게 인코딩(add)과 검색(search) 두 갈래이고, 둘 다 같은 "회전된 공간"에서 만납니다.

이제 벡터 하나의 여정을 따라가 봅시다. 1536차원 OpenAI 임베딩 하나(6,144바이트)가 index.add()로 들어오면:

① 정규화. 벡터의 길이(norm)를 떼어내 float 하나로 따로 저장합니다. 남은 것은 구면 위의 "방향"뿐입니다. ② 회전. 모든 벡터에 같은 무작위 직교 행렬을 곱합니다(rotation.rs — ChaCha8 난수를 시드 42로 고정하고 faer로 QR 분해). 이 회전이 마법의 핵심인데, 회전 후엔 어떤 입력이든 각 좌표가 Beta((d-1)/2, (d-1)/2) 분포를 따릅니다. ③ TQ+ 보정. 실제 데이터는 이론 분포에서 살짝 어긋나므로, 좌표마다 shift/scale 두 파라미터를 5%/95% 분위수로 맞춥니다(encode.rs — 1,000개 미만이면 통계가 불안정해 보정을 건너뜀). ④ 양자화. 분포를 아니까 최적 구간도 미리 계산됩니다 — codebook.rs의 Lloyd-Max 알고리즘이 4비트면 16개, 2비트면 4개의 구간 경계와 대푯값을 "수학에서" 뽑아냅니다. ⑤ 패킹. 좌표 하나가 0~15의 작은 정수가 됐으니 pack.rs가 바이트에 꽉꽉 눌러 담습니다. 결과: 6,144바이트 → 4비트 기준 768바이트.

검색은 반대 방향의 잔머리입니다. 데이터베이스 쪽을 복원(decompress)하는 게 아니라 쿼리를 한 번만 같은 공간으로 회전시키고, 코드북 대푯값과의 곱을 미리 표로 만들어(LUT (Look-Up Table, 룩업테이블 — 계산 결과를 미리 적어둔 표)) 압축된 코드에서 바로 점수를 읽습니다. 이 안쪽 루프가 search.rs(1,821줄, 레포에서 가장 큰 파일)의 SIMD 커널입니다 — 32개 벡터를 한 블록으로 묶어 NEON/AVX-512 레지스터에서 니블(4비트) 단위로 테이블을 찾습니다.

이 레포의 "정상적인 모양새" 하나를 짚자면: 모든 주석이 '왜'를 설명합니다. 예컨대 입력 검증 코드엔 "NaN이 들어오면 어떤 경로로 인덱스가 조용히 오염되는지"가, 상수 하나엔 "왜 하필 1000개인지" 실험 근거가 달려 있습니다. 주석 읽는 것만으로 수치 컴퓨팅의 함정 목록을 배울 수 있는 코드베이스입니다.

5디렉토리 구조 해부

어떤 폴더가 무슨 일을 하나.

6학습 포인트 (기술별)

이 레포에서 배울 만한 것 + 어디를 보면 되는지.

인-커널 필터링도 눈여겨볼 만합니다. 검색 후 결과를 걸러내는(post-filter) 게 아니라 커널 안에서 허용 목록 밖 벡터를 힙에 아예 안 넣기 때문에, 필터를 걸어도 항상 k개가 꽉 채워져 나옵니다:

# SQL/BM25 1차 검색이 추린 후보 id 안에서만 벡터 검색 (하이브리드 검색)
allowed = np.array([1003, 1010, 1042], dtype=np.uint64)
scores, ids = idx.search(queries, k=10, allowlist=allowed)

7시스템 요구사항

돌리려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

난이도별로 손에 익히는 단계.

import numpy as np
from turbovec import TurboQuantIndex

vecs = np.random.randn(10000, 384).astype(np.float32)
index = TurboQuantIndex(dim=384, bit_width=4)
index.add(vecs)
scores, idx = index.search(vecs[:5], k=10)
print(idx[0])  # 첫 쿼리는 자기 자신(0번)이 1등으로 나와야 정상

9관련 기술 심화 학습 로드맵

한 주씩 따라가는 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: RyanCodrai/turbovec
• PyPI: pypi.org/project/turbovec · crates.io: crates.io/crates/turbovec
• TurboQuant 논문 (ICLR 2026): arxiv.org/abs/2504.19874
• API 레퍼런스: docs/api.md
• FAISS FastScan 해설 (커널이 참고한 기법): FAISS 위키