zvec 딥다이브
— 서버 없이 앱 안에 박아 쓰는 '초고속 인프로세스 벡터 DB'

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

zvec = "벡터 검색계의 SQLite — 서버를 띄울 필요 없이, 라이브러리로 앱에 박아 쓰는 초고속 벡터 데이터베이스." 보통 벡터 DB(Milvus·Qdrant·Weaviate)는 별도 서버 프로세스를 띄우고, 도커로 올리고, 네트워크로 붙어 쓴다. zvec은 그 발상을 뒤집어 서버도 도커도 설정도 없이 pip install zvec 한 줄로 깔고, import zvec 해서 내 코드 안에서 곧바로 호출한다. 데이터는 로컬 디스크 폴더 하나에 저장되고, 검색 연산은 내 프로세스의 CPU에서 그대로 돈다.

한 가지 짚을 것 — zvec은 알리바바 그룹 내부에서 이미 실전(production)에 쓰이며 검증된(battle-tested) 엔진을 오픈소스로 푼 것이다. Python뿐 아니라 Node.js·Go·Rust·Dart/Flutter SDK까지 제공하고, 리눅스·macOS·Windows를 모두 지원한다. 즉 "가볍지만 장난감은 아닌" 프로덕션급 임베디드 벡터 엔진이라는 점이 핵심이다.

2왜 주목받는가

TrendShift 일간 4위 — 별 1만 개를 향해 달리는 이유.

2024~2026년은 "모든 앱이 AI 검색을 품는" 시대다. 챗봇은 RAG로 문서를 찾고, 추천은 임베딩으로 비슷한 걸 고르고, 에이전트는 '기억(memory)'을 벡터로 저장한다. 그런데 이걸 하려고 매번 Milvus 서버를 띄우고 도커를 관리하는 건 과하다. zvec은 "서버 없이, 라이브러리로, 그러나 프로덕션급 속도로"라는 빈자리를 정확히 노린다. 이유를 다섯으로 정리한다.

① 설정 0 — pip install 하고 바로 검색

가장 큰 매력. 도커·서버·스키마 마이그레이션·네트워크 인증이 전부 없다. pip install zvec → import zvec → create_and_open() → insert() → query(). 5줄이면 끝난다. 데이터는 로컬 폴더 하나(./zvec_example)에 담기고, 그 폴더를 통째로 복사하면 그게 곧 백업이다.

② C++ 코어 — "수십억 벡터를 밀리초에"

마케팅 구호가 아니라 설계가 받쳐 준다. 코어의 79%가 C++이고, x86의 AVX2/AVX-512 SIMD 명령어, RaBitQ 양자화, mmap 기반 저장까지 동원해 거리 계산을 극한으로 최적화했다. Python은 얇은 바인딩일 뿐, 실제 무거운 연산은 전부 네이티브 코드가 처리한다.

③ 인덱스 백화점 — FLAT부터 DiskANN까지

경쟁작이 한두 개 인덱스만 주는 데 비해, zvec은 FLAT(완전탐색)·HNSW·HNSW+RaBitQ·IVF·DiskANN·Vamana를 모두 제공한다. 데이터가 작으면 메모리 인덱스(HNSW), 메모리에 다 안 들어가면 디스크에 인덱스를 두는 DiskANN으로 — 규모에 맞춰 갈아 끼운다. 메모리 한 줌으로 수억 벡터를 다루는 길이 열려 있다.

④ 벡터만? 아니다 — FTS·하이브리드·필터까지

v0.5.0에서 전문 검색(Full-Text Search)이 네이티브로 들어왔다. 외부 검색엔진(Elasticsearch) 없이 문자열 필드에 키워드 검색을 건다. 게다가 한 번의 MultiQuery로 밀집 벡터 + 희소 벡터 + 스칼라 필터 + 키워드를 동시에 섞는 하이브리드 검색이 가능하다. "의미는 비슷하면서, 가격은 1만 원 이하, '방수' 단어 포함"을 한 방에 처리한다.

⑤ 영속성과 동시성 — 진짜 'DB'답다

임베디드라고 데이터가 휘발되지 않는다. WAL(Write-Ahead Logging) 덕에 프로세스가 죽거나 정전이 나도 데이터를 잃지 않는다. 또 여러 프로세스가 같은 컬렉션을 동시에 읽을 수 있다(쓰기는 한 프로세스 전용). 캐시가 아니라 '내구성 있는 DB'로 설계됐다.

3기술 스택 전체 지도

CMakeLists.txt · pyproject.toml · .gitmodules · 소스 트리에서 직접 확인한 실제 구성.

zvec의 정체는 "C++ 코어 + 다국어 얇은 바인딩"이다. GitHub 언어 통계가 이를 명확히 보여준다 — C++ 79.3% · Python 7.9% · SWIG 7.7% · C 3.6%. 즉 엔진의 실체는 C++이고, Python·Node·Go 등은 그 위에 씌운 껍데기다. 빌드는 CMake로 묶고, 18개나 되는 서드파티 라이브러리를 git submodule로 끌어온다.

ⓐ 코어 엔진 (C++17)

ⓑ 인덱스 알고리즘 (src/core/algorithm)

ⓒ 저장 · 영속성 (src/db/index/storage)

ⓓ 질의 엔진 & FTS (src/db/sqlengine)

ⓔ 바인딩 — 한 코어, 여러 언어

4아키텍처 심화 분석

벡터 하나가 들어가 검색 결과로 나오기까지 — 인프로세스 엔진의 속살.

zvec의 핵심 아이디어는 한 문장이다 — "풀 기능 벡터 DB를, 서버가 아니라 라이브러리 한 덩어리로 패키징한다." 외부에서 보면 Collection 객체 하나에 insert()/query()만 호출하면 되지만, 그 아래에는 스키마·세그먼트·인덱스·저장·질의 엔진이 층층이 쌓여 있다. 먼저 숲(전체 그림)을 보고, 그다음 검색 한 줄기를 따라가 보자.

먼저 전체 그림 한 장

흐름 한 줄기 따라가기 — collection.query(VectorQuery(...), topk=10)

실제 코드 호출 하나가 내부에서 어떤 순서로 도는지, 핵심 5%(해피패스)만 따라간다.

① 바인딩 경유 — Python에서 C++로. collection.query(...)는 순수 Python 래퍼를 거쳐 네이티브 _zvec 모듈로 내려간다. 이때 네트워크 직렬화·소켓 왕복이 전혀 없다 — 같은 프로세스 메모리를 그대로 넘긴다. 이게 인프로세스의 속도 비밀이다.

② 필터 파싱 (있다면). "price < 10000 AND tag = 'waterproof'" 같은 스칼라 필터가 붙어 있으면, ANTLR SQL 엔진이 이를 파싱해 실행 계획으로 바꾼다. 역색인(invert index)으로 조건에 맞는 후보 ID를 먼저 좁힌다.

③ 세그먼트별 벡터 검색. 데이터는 여러 세그먼트로 나뉘어 있다. 각 세그먼트의 벡터 인덱스(예: HNSW 그래프)를 타고 질의 벡터와 가까운 Top-k 후보를 모은다. 거리 계산은 SIMD로 가속된다.

# C++ 코어가 내부에서 하는 일 (개념 요약)
filter_ids = sql_engine.eval(filter_expr)        # 필터로 후보 좁히기
for seg in segments:                              # 세그먼트마다
    cand = seg.vector_index.search(q, topk, filter_ids)  # HNSW/IVF 탐색
    heap.merge(cand)                              # 부분결과 합치기
results = reranker.fuse(heap)                     # (하이브리드면) 융합·재정렬
return results.topk(10)                           # 최종 Top-10

④ 결과 병합 & 재정렬. 세그먼트별 부분 결과를 하나의 힙(heap)으로 합친다. 하이브리드 검색(벡터+FTS)이라면 reranker가 서로 다른 점수 체계를 RRF 같은 방식으로 융합해 최종 순위를 매긴다.

⑤ 결과 반환 — 다시 Python으로. 최종 Top-k가 {'id', 'score', ...} 리스트로 바인딩을 거쳐 돌아온다. 점수 순으로 정렬돼 있고, 필요하면 원본 벡터·메타데이터까지 함께 실어 준다.

핵심 설계 패턴 ① — 인프로세스 + 단일 라이터(single-writer)

가장 중요한 결정. zvec은 서버를 두지 않는다. 대신 데이터 폴더를 파일 락으로 보호해, 한 프로세스만 쓰고(write) 여러 프로세스가 동시에 읽도록(read) 한다. src/db/collection.cc가 file_lock.h·shared_mutex를 쓰는 게 그 증거다. SQLite의 동시성 모델과 같은 철학 — 단순함과 속도를 위해 분산 쓰기를 포기한 트레이드오프다.

핵심 설계 패턴 ② — 세그먼트 + 다중 인덱스 분리

데이터를 세그먼트로 쪼개 관리한다(LSM 트리와 유사). 새 데이터는 새 세그먼트로 쌓이고, 검색은 여러 세그먼트를 병렬로 훑어 합친다. 또 벡터 인덱스 / 역색인(필터·FTS) / 포워드 스토어(원본)를 명확히 분리해, 같은 데이터에 의미 검색·키워드 검색·필터를 각각 최적 자료구조로 건다. 이 분리가 하이브리드 검색을 가능케 한다.

핵심 설계 패턴 ③ — 플러그형 인덱스 (IndexFactory)

인덱스 알고리즘을 IndexParams로 추상화하고 IndexFactory::CreateAndInitIndex()로 찍어낸다(examples/c++ 참고). 덕분에 같은 데이터에 FLAT→HNSW→DiskANN을 코드 거의 그대로 갈아 끼운다. DiskANN은 별도 플러그인(.so)으로 분리돼, 처음 쓸 때 동적 로드(load_diskann_plugin)되고 libaio가 없으면 친절히 에러를 낸다.

5디렉토리 구조 해부

저장소를 열었을 때 어디부터 봐야 하는가 — 3층 구조(코어 / DB / 바인딩).

처음 저장소를 열면 디렉토리가 많아 막막하다. 핵심만 잡으면 된다 — src/core/는 '인덱스 알고리즘', src/db/는 '데이터베이스 기능', src/binding/·python/은 '언어 껍데기'다. 공부는 examples/ → src/db/collection.cc → src/core/algorithm/ 순서가 좋다.

6학습 포인트 (기술별)

이 레포에서 실제로 무엇을 배울 수 있는가 — 기술별 + 실습 아이디어.

7하드웨어/시스템 요구사항

내 컴퓨터로 돌릴 수 있나? — 인프로세스라 의외로 가볍다.

좋은 소식 — zvec은 GPU가 전혀 필요 없다. 벡터 '검색' 엔진이지 '학습' 엔진이 아니므로, CPU만으로 돈다(임베딩을 만드는 단계는 별개). 별도 서버·도커도 없어, 노트북 한 대면 시작한다. 실제 요구사항은 데이터 규모와 고른 인덱스에 좌우된다.

메모리는 '어떤 인덱스를 고르느냐'가 전부다. 대략의 그림:

실행 전 알아둘 것 — zvec은 cgroup의 CPU·메모리 한도를 자동 감지해 기본값을 잡는다(컨테이너 친화적). zvec.init(memory_limit_mb=..., query_threads=...)로 직접 조절도 가능하다. FTS를 쓰면 jieba 사전(data/jieba_dict)이 휠에 동봉돼 별도 설치가 필요 없다.

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

난이도별로 — 손으로 돌려봐야 진짜 내 것이 된다.

먼저 '복사만 하면 OK'인 기본 호출부터. 아래가 zvec 사용의 전부다 — 서버도 도커도 없다.

import zvec

# ① 스키마 정의: 'embedding'이라는 4차원 FP32 벡터 필드
schema = zvec.CollectionSchema(
    name="example",
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4),
)
# ② 컬렉션 생성 + 열기(로컬 폴더 하나가 곧 DB)
collection = zvec.create_and_open(path="./zvec_example", schema=schema)
# ③ 문서(벡터) 삽입
collection.insert([
    zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}),
    zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}),
])
# ④ 유사도 검색 — 질의 벡터와 가까운 Top-k
results = collection.query(zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]), topk=10)
print(results)   # [{'id': 'doc_2', 'score': ...}, ...]  점수순 정렬

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

zvec을 발판으로 벡터 검색+임베디드 DB를 제대로 — 6주 계획.

10핵심 키워드 사전

문서·코드에 자주 나오는 용어 — 한 줄 정의.

11참고 링크

원문으로 더 깊이 — 공식 소스 위주.

• GitHub 저장소: github.com/alibaba/zvec
• 공식 홈/문서: zvec.org · Quickstart · Docs
• 벤치마크: zvec.org/docs/db/benchmarks
• 벡터 인덱스 종류 개념: vector-index 문서
• 코드 분석 위키: DeepWiki (alibaba/zvec)
• PyPI: pypi.org/project/zvec · npm: @zvec/zvec
• 공식 SDK: Go · Rust · Zvec Studio(시각 도구)
• v0.5.0 릴리스 노트: github.com/alibaba/zvec/releases
• TrendShift 페이지: trendshift.io/repositories/20830