Fast, SQL powered, in-process vector search for any language with an SQLite driver

Vectorlite – SQLite 내부의 빠른 벡터 검색

기능 소개

Vectorlite는 런타임에 로드 가능한 SQLite 확장으로, 고차원 벡터에 대한 근사 최근접 이웃(ANN) 검색을 위한 새로운 가상 테이블 유형을 추가합니다. 이를 통해 벡터를 SQLite 데이터베이스에 직접 저장하고 일반 SQL 문으로 빠른 유사도 쿼리를 실행할 수 있습니다.

주요 장점

SQL 우선 워크플로우 – 별도의 벡터 데이터베이스가 필요하지 않습니다. 관계형 데이터와 벡터 임베딩을 하나의 파일에 함께 보관할 수 있습니다.
속도 – HNSW 알고리즘(hnswlib 사용)과 SIMD 가속 거리 계산을 사용하여, 무차별 대입 방식의 SQLite 확장보다 3~100배 빠른 쿼리 성능을 제공합니다.
다중 언어 지원 – 컴파일된 vectorlite.so/.dll/.dylib는 SQLite 확장을 로드할 수 있는 모든 언어(Python, Node.js, Rust, Go 등)에서 작동합니다.
이식성 – Linux x64, Windows x64 및 macOS Apple Silicon용 사전 빌드된 바이너리를 제공하며, Python wheel(vectorlite-py) 및 npm 패키지로도 이용 가능합니다.

사용 방법 (SQL 예시)

.load path/to/vectorlite.so               -- 확장 로드
SELECT vectorlite_info();                -- 버전 정보

-- 3차원 float32 벡터를 저장하는 테이블 생성
CREATE VIRTUAL TABLE my_vec USING vectorlite(
    embedding float32[3], hnsw(max_elements=100)
);

INSERT INTO my_vec(rowid, embedding) VALUES (0, vector_from_json('[1,2,3]'));
INSERT INTO my_vec(rowid, embedding) VALUES (1, vector_from_json('[2,3,4]'));
INSERT INTO my_vec(rowid, embedding) VALUES (2, vector_from_json('[7,7,7]'));

-- [3,4,5]의 2개 최근접 이웃 찾기
SELECT rowid, distance
FROM my_vec
WHERE knn_search(embedding, knn_param(vector_from_json('[3,4,5]'), 2));

이 확장은 다음과 같은 도우미 함수를 제공합니다:

vector_from_json() / vector_to_json() – JSON 배열과 SQLite가 저장하는 이진 형식 간의 변환.
vector_distance() – 정확한 L2, 코사인 또는 내적 거리를 계산.
knn_param() 및 knn_search() – ANN 쿼리 빌드 및 실행.
vectorlite_info() – 빌드 세부 정보 및 런타임에 선택된 SIMD 타겟 표시.

주요 기능

기능	세부 정보
ANN 엔진	HNSW (hierarchical navigable small world) via hnswlib; `ef_construction`, `M` 등 튜닝 가능
거리 측정	L2 (제곱), 코사인, 내적 (IP)
SIMD 가속	Google의 Highway 라이브러리 사용; 고차원 벡터에서 hnswlib 자체 거리 코드보다 1.5~3배 빠름
데이터 타입	`float32`, `float16`, `bfloat16` – 반정밀도 테이블은 삽입/쿼리 시 양자화됨
메타데이터 필터	Row-id 조건은 인덱스로 푸시다운됨 (SQLite ≥ 3.38)
영속성	인덱스는 메모리에 상주; 명시적인 `INSERT … (operation, path) VALUES ('save', '/path')` 및 `('load', …)` 명령으로 직렬화/역직렬화
크로스 플랫폼	Linux x64, Windows x64, macOS Apple Silicon용 바이너리; Python wheel, Node.js용 npm 패키지
베타 상태	API가 변경될 수 있음; 주요 변경 사항으로 `CREATE VIRTUAL TABLE`의 자동 인덱스 파일 인수가 제거됨

제한 사항

인덱스는 메모리 전용입니다. 연결을 닫기 전에 명시적으로 저장해야 합니다.
베타 버전이므로 향후 릴리스에서 주요 변경 사항이 발생할 수 있습니다.
Intel 기반 macOS는 지원하지 않으며, Apple Silicon만 지원합니다.
근사 결과 – 재현율은 HNSW 매개변수에 따라 다르며, 정확도를 높이기 위해 튜닝할 수 있습니다.

위의 모든 정보는 저장소의 README에서 직접 가져왔습니다.

1yefuwang1/vectorlite