turbo-graph — turbovec에 그래프 메모리/필터 캐시를 얹은 constrained RAG 인덱스

turbo-graph — turbovec에 그래프 메모리/필터 캐시를 얹은 constrained RAG 인덱스

2026년 6월, RAG 파이프라인의 *제약 결합* 이슈를 인덱스 레이어로 끌어내린 새 OSS가 등장했다. turbo-graph는 TurboQuant 라인리지의 turbovec 코어 위에 graph memory, tag/source/time 인덱스, SlotMask 캐시, graph-aware rerank, explain telemetry를 한 번에 얹은 *constrained RAG* 인덱스다. 긱뉴스 Show GN(30400)을 통해 제작자 mansuiki가 Alpha 단계로 공개했고, 이미 Star 13 / Fork 8을 모았다.

turbo-graph가 해결하는 문제

대부분의 운영형 RAG 쿼리는 단순 top-k가 아니다. *tenant ACL* ∩ *tag* ∩ *source* ∩ *time window* ∩ *graph neighbors* ∩ *BM25 candidates*를 매번 Python/SQL/app layer에서 만든 뒤 vector search로 넘기고, 결과를 graph/BM25로 다시 rerank한다. 그리고 "왜 이 결과가 나왔는가"를 explain하는 코드까지 — 같은 모양이 반복된다.

turbo-graph는 이 *조립 작업*을 인덱스로 옮긴다. 즉, kernel filtering은 그대로 두고, app layer의 graph 확장, 메타데이터 인덱스, 후보 리스트 교집합, view 캐시 재사용, rerank, explain을 한 곳에 묶는다.

turbovec과의 차이

turbovec은 flat top-k나 cheap allowlist에는 이미 충분하다. SIMD 커널 안에서 빈 32-vector 블록을 건너뛰고, (nq, min(k, n_allowed)) 형태로 결과를 돌려주기 때문에 tight filter에서도 recall을 위한 padding이 필요 없다. 이 부분은 turbo-graph에 그대로 상속됐다.

반면 graph neighborhood 확장, tag/source/time view, rerank, explain telemetry는 turbovec이 *사용자 책임*으로 남겨둔 영역이다. turbo-graph는 그 영역을 GraphMemoryIndex라는 Python 운영 API로 감싸고, IdMapIndex는 turbovec과 호환되는 core로 유지한다. 즉, hot filtered route만 turbo-graph로 옮기면 된다.

5단계 도입 패턴

1. 코어 import 교체: from turbovec import IdMapIndex를 from turbo_graph import IdMapIndex로 바꾼다. API는 호환된다.

2. 메타데이터 등록: add_records()에 id, title, tags, source, timestamp_ms를 함께 넘긴다.

3. 그래프 링크: link_bidirectional(a, b, 0.8)처럼 가중치로 양방향 엣지를 정의한다.

4. prepare(): 인덱스 빌드를 한 번 끝낸다. 이후 search에서 view 컴파일이 캐시된다.

5. 제약 검색: search(query, k=10, seeds=[...], required_tags=[...], allowed_sources=[...], candidate_ids=[...])로 한 번에 호출한다. BM25/SQL/ACL 후보는 candidate_ids로 주입한다.

2026년 6월 현재 성능과 한계

벤치마크는 100K 벡터, 1K 쿼리, k=64, seed 42 기준이다. ARM에서는 16개 구성 모두 TurboQuant가 FAISS IndexPQFastScan보다 빠르다(최대 +19.4%). x86 2-bit MT만 FAISS AVX-512 VBMI 대비 -8.4%로 알려진 갭이 있다. 인덱스 RAM은 10M × 1536d 2-bit 기준 약 4 GB로, float32 벡터(약 31 GB) 대비 압축이 크다.

한계는 명확하다. brute-force O(n) 스캔이며 HNSW/IVF는 아니다. 2~4 bit 근사만 지원한다. TQ+는 첫 add에서 최소 1,000개 벡터가 필요하다. 운영 환경에서는 버전 핀 고정이 권장된다.

마이그레이션 기준

다음을 3개 이상 만족하면 turbo-graph로 옮길 만하다. (1) 대부분의 쿼리가 tenant/source/tag/time 제약을 동반한다. (2) vector search 전에 graph neighborhood를 확장한다. (3) 같은 filter 술어가 burst로 반복된다. (4) BM25/SQL 점수와 vector, graph 점수를 수동으로 합친다. (5) trace, cache hit, selectivity 같은 production explainability가 필요하다. *allowlist=* 자체는 충분하지만 그 allowlist를 만드는 데 병목이 있다면 turbo-graph의 승리 구간이다.

전망과 요약

constrained RAG의 핵심은 *view 컴파일을 한 번 하고 재사용*하는 데 있다. turbo-graph는 그 재사용을 Python이 아니라 인덱스 안에서 처리한다. 멀티테넌트 검색, 사내 knowledge graph 기반 Q&A, BM25와 vector를 함께 쓰는 production RAG에서 가장 먼저 효과를 볼 수 있다. 2026년 6월 현재 Alpha이므로 production 직결보다는 *어떤 API가 실제로 필요한지*를 함께 실험해 볼 시점이다.