TurboVec 완벽 가이드: FAISS보다 빠른 오픈소스 벡터 검색 라이브러리

pip install turbovec

# LangChain 통합
pip install turbovec[langchain]

# LlamaIndex 통합
pip install turbovec[llama-index]

# Haystack 통합
pip install turbovec[haystack]

# Agno 통합
pip install turbovec[agno]

[dependencies]
turbovec = "0.1"

import numpy as np
from turbovec import TurboQuantIndex

# 인덱스 생성: 차원 1536(OpenAI 임베딩 기본 차원), 4비트 양자화
index = TurboQuantIndex(dim=1536, bit_width=4)

# 샘플 벡터 생성(실제 사용 시 임베딩 벡터로 대체)
vectors = np.random.rand(10000, 1536).astype(np.float32)

# 인덱스에 벡터 추가
index.add(vectors)

# 더 많은 벡터를 계속 추가할 수 있으며, 인덱스 재구축이 필요 없습니다
more_vectors = np.random.rand(5000, 1536).astype(np.float32)
index.add(more_vectors)

print(f"인덱스에 총 {len(index)}개의 벡터가 있습니다")

# 쿼리 벡터 생성
query = np.random.rand(1536).astype(np.float32)

# 가장 유사한 10개 벡터 검색
scores, indices = index.search(query, k=10)

print("유사도 점수:", scores)
print("벡터 인덱스:", indices)

# 인덱스를 디스크에 저장
index.write("my_index.tq")

# 디스크에서 인덱스 로드
loaded_index = TurboQuantIndex.load("my_index.tq")

# 로드 확인
scores, indices = loaded_index.search(query, k=10)

import numpy as np
from turbovec import IdMapIndex

# 외부 ID를 지원하는 인덱스 생성
index = IdMapIndex(dim=1536, bit_width=4)

# 3개의 벡터가 있고, 해당 외부 ID가 1001, 1002, 1003이라고 가정
vectors = np.random.rand(3, 1536).astype(np.float32)
external_ids = np.array([1001, 1002, 1003], dtype=np.uint64)

# 벡터와 해당 외부 ID 추가
index.add_with_ids(vectors, external_ids)

# 검색 시 내부 인덱스가 아닌 외부 ID를 반환
query = np.random.rand(1536).astype(np.float32)
scores, ids = index.search(query, k=10)

print("반환된 외부 ID:", ids)  # [1001, 1003, 1002, ...]

# ID가 1002인 벡터 삭제
index.remove(1002)

# 다시 검색하면 1002가 결과에 나타나지 않음
scores, ids = index.search(query, k=10)
print("삭제 후 ID:", ids)  # 더 이상 1002 포함되지 않음

# 저장
index.write("my_index.tvim")

# 로드
loaded_index = IdMapIndex.load("my_index.tvim")

import numpy as np
from turbovec import IdMapIndex

# 인덱스 생성
idx = IdMapIndex(dim=1536, bit_width=4)

# 10,000개의 벡터가 있고, 각 벡터가 문서 ID에 대응한다고 가정
vectors = np.random.rand(10000, 1536).astype(np.float32)
doc_ids = np.arange(1, 10001, dtype=np.uint64)
idx.add_with_ids(vectors, doc_ids)

# 데이터베이스 쿼리 시뮬레이션: 테넌트 A의 문서 ID 목록 가져오기
# 실제 시나리오에서는 PostgreSQL / MySQL에서 쿼리한 결과입니다
tenant_a_docs = np.array([1, 5, 10, 15, 20, 25, 30, 35, 40, 45], dtype=np.uint64)

# 테넌트 A의 문서 범위 내에서 검색
query = np.random.rand(1536).astype(np.float32)
scores, ids = idx.search(query, k=5, allowlist=tenant_a_docs)

print("테넌트 A의 가장 관련성 높은 문서:", ids)
# 출력에는 tenant_a_docs의 ID만 포함됩니다

from langchain_community.vectorstores import TurboVec
from langchain_openai import OpenAIEmbeddings

# 임베딩 초기화
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

# TurboVec 벡터 스토어 생성
vector_store = TurboVec.from_documents(
    documents=documents,  # Document 리스트
    embedding=embeddings,
    bit_width=4  # 4비트 양자화
)

# 유사성 검색
results = vector_store.similarity_search("질문", k=5)

# 영구 저장
vector_store.save_local("turbovec_index")

# 로드
loaded_store = TurboVec.load_local("turbovec_index", embeddings)

from llama_index.vector_stores.turbovec import TurboVecVectorStore
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 문서 로드
documents = SimpleDirectoryReader("./data").load_data()

# TurboVec 벡터 스토어 생성
vector_store = TurboVecVectorStore(dim=1536, bit_width=4)

# 인덱스 생성
index = VectorStoreIndex.from_documents(
    documents,
    vector_store=vector_store
)

# 쿼리 엔진
query_engine = index.as_query_engine()
response = query_engine.query("질문")
print(response)

from haystack_integrations.document_stores.turbovec import TurboVecDocumentStore
from haystack.components.embedders import SentenceTransformersDocumentEmbedder
from haystack import Pipeline

# 문서 스토어 생성
document_store = TurboVecDocumentStore(dim=768, bit_width=4)

# 임베더
embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2")

# 파이프라인 구축
pipeline = Pipeline()
pipeline.add_component("embedder", embedder)
# ... 다른 컴포넌트 계속 추가

use turbovec::TurboQuantIndex;
use ndarray::Array2;

fn main() {
    // 인덱스 생성: 1536차원, 4비트 양자화
    let mut index = TurboQuantIndex::new(1536, 4);

    // 벡터 데이터 준비(여기서는 랜덤 숫자 예시)
    let vectors = Array2::<f32>::random((10000, 1536), &mut rand::thread_rng());

    // 벡터 추가
    index.add(&vectors);

    // 쿼리 벡터 준비
    let query = Array1::<f32>::random(1536, &mut rand::thread_rng());

    // 가장 유사한 10개 벡터 검색
    let results = index.search(&query, 10);

    println!("Top 10 결과: {:?}", results);

    // 영구 저장
    index.write("index.tv").unwrap();

    // 로드
    let loaded = TurboQuantIndex::load("index.tv").unwrap();
}

use turbovec::IdMapIndex;

fn main() {
    let mut index = IdMapIndex::new(1536, 4);

    let vectors = Array2::<f32>::random((100, 1536), &mut rand::thread_rng());
    let ids = vec![1001u64, 1002, 1003, /* ... */];

    index.add_with_ids(&vectors, &ids);

    let query = Array1::<f32>::random(1536, &mut rand::thread_rng());
    let (scores, returned_ids) = index.search(&query, 10);

    println!("반환된 외부 ID: {:?}", returned_ids);

    // 삭제
    index.remove(1002);

    // 영구 저장
    index.write("index.tvim").unwrap();
    let loaded = IdMapIndex::load("index.tvim").unwrap();
}

pip install turbovec sentence-transformers langchain-community langchain-openai

import numpy as np
from turbovec import IdMapIndex
from sentence_transformers import SentenceTransformer
from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1. 임베딩 모델 로드(로컬 실행, API 키 불필요)
print("임베딩 모델 로드 중...")
model = SentenceTransformer('all-MiniLM-L6-v2')  # 384차원
dim = 384

# 2. 문서 로드 및 분할
print("문서 로드 중...")
loader = TextLoader('./data/my_documents.txt', encoding='utf-8')
documents = loader.load()

splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50
)
chunks = splitter.split_documents(documents)

print(f"{len(chunks)}개의 텍스트 청크로 분할됨")

# 3. 벡터 생성 및 인덱스 구축
print("벡터 생성 및 인덱스 구축 중...")
index = IdMapIndex(dim=dim, bit_width=4)

texts = [chunk.page_content for chunk in chunks]
metadata_list = [chunk.metadata for chunk in chunks]

# 배치로 벡터 생성
embeddings = model.encode(texts, show_progress_bar=True)

# 벡터와 메타데이터 추가(인덱스를 외부 ID로 사용)
external_ids = np.arange(len(texts), dtype=np.uint64)
index.add_with_ids(embeddings.astype(np.float32), external_ids)

# 인덱스 저장
index.write("rag_index.tvim")
print("인덱스 저장 완료")

# 4. 검색 함수
def search(query: str, k: int = 5):
    """가장 관련성 높은 텍스트 청크 검색"""
    # 인덱스 로드
    idx = IdMapIndex.load("rag_index.tvim")

    # 쿼리 벡터 생성
    query_embedding = model.encode([query])[0].astype(np.float32)

    # 검색
    scores, ids = idx.search(query_embedding, k=k)

    # 결과 반환
    results = []
    for score, doc_id in zip(scores, ids):
        doc_id = int(doc_id)
        results.append({
            'text': texts[doc_id],
            'score': float(score),
            'metadata': metadata_list[doc_id]
        })

    return results

# 5. 검색 테스트
if __name__ == "__main__":
    query = "TurboVec란 무엇인가?"
    results = search(query, k=3)

    print("\n=== 검색 결과 ===")
    for i, result in enumerate(results, 1):
        print(f"\n[{i}] 유사도: {result['score']:.4f}")
        print(f"내용: {result['text'][:200]}...")

def search_with_filter(query: str, category: str, k: int = 5):
    """카테고리 필터링이 있는 검색"""
    idx = IdMapIndex.load("rag_index.tvim")

    # 지정된 카테고리에 속하는 문서 ID 찾기
    allowed_ids = np.array([
        i for i, meta in enumerate(metadata_list)
        if meta.get('category') == category
    ], dtype=np.uint64)

    if len(allowed_ids) == 0:
        return []

    # 쿼리 벡터 생성
    query_embedding = model.encode([query])[0].astype(np.float32)

    # 필터링된 검색
    scores, ids = idx.search(query_embedding, k=k, allowlist=allowed_ids)

    results = []
    for score, doc_id in zip(scores, ids):
        doc_id = int(doc_id)
        results.append({
            'text': texts[doc_id],
            'score': float(score),
            'metadata': metadata_list[doc_id]
        })

    return results

# "기술" 카테고리 문서만 검색
results = search_with_filter("설치 방법은?", category="기술", k=3)