EmbedDB: 단일 파일로 구현된 초경량 벡터 데이터베이스

단일 파일에 담긴 작은 의미 검색 DB. 설정 불필요. 즉시 프로토타이핑 가능.

EmbedDB는 의미 검색 및 RAG(Retrieval-Augmented Generation) 애플리케이션의 신속한 프로토타이핑을 위해 설계된 초경량 벡터 데이터베이스입니다. 전체 구현은 최소한의 의존성만 가진 단일 Python 파일에 포함되어 있습니다.

⚡ 2분 만에 통합: pip install부터 2분 이내 작동하는 코드까지
📄 단일 파일: 전체 구현이 읽기 쉬운 하나의 Python 파일(<500줄)
🔍 간단한 API: 배우기 쉬운 직관적인 명령어 7개만 사용
🛠️ 설정 불필요 (Zero Config): 계정, API 키 또는 복잡한 설정 필요 없음
💾 JSON 영속성: 사람이 읽을 수 있는 형식의 간단한 파일 기반 저장소
🧩 확장 가능: 특정 요구 사항에 맞게 수정하거나 확장하기 쉬움
🤖 선택적 임베딩: 내장된 텍스트 임베딩 지원 (필요할 때)

기본 설치 (벡터 스토리지만):

pip install embeddb

내장 임베딩 지원과 함께:

pip install embeddb[embeddings]

이것으로 충분합니다. 컴파일이나 복잡한 의존성이 필요 없습니다.

EmbedDB는 단순성을 위해 설계되었습니다. 전체 API는 단 7개의 직관적인 명령어로 구성되어 있습니다:

db = EmbedDB(dimension=384) # 데이터베이스 생성
db.add(id, vector, metadata) # 벡터 추가 (또는 텍스트 입력을 위해 add_text 사용)
db.search(vector, top_k=5) # 유사한 벡터 찾기 (또는 텍스트 질의를 위해 search_text 사용)
...

이것으로 충분합니다. 복잡한 설정도 없고, 가파른 학습 곡선도 없습니다. 설치하고 구축을 시작하기만 하면 됩니다.

참고: 벡터 임베딩이 제공되지 않을 때 (add_text 또는 search_text 사용 시), EmbedDB는 내부적으로 all-MiniLM-L6-v2 임베딩 모델을 사용합니다.

EmbedDB는 순수 성능보다 사용 편의성에 중점을 두었지만, 프로토타이핑 및 소규모에서 중규모 애플리케이션에는 여전히 놀라울 정도로 효율적입니다.

실제 벤치마크는 EmbedDB의 효율적인 확장 특성을 보여줍니다:

벡터 추가 (Adding Vectors): 데이터베이스 크기에 관계없이 일관된 성능을 보입니다 (~0.017ms/벡터)
검색 성능 (Search Performance): 벡터 100개일 때 1ms에서 벡터 10,000개일 때 ~110ms로 선형적으로 증가합니다
메모리 효율성 (Memory Efficiency): 데이터베이스 크기에 따라 메모리가 선형적으로 증가합니다 (벡터 1,000개 시 2MB, 벡터 10,000개 시 130MB)

<1,000 vectors: 최소한의 메모리 사용량으로 매우 빠릅니다
1,000-10,000 vectors: 대부분의 프로토타이핑 요구 사항에 대해 우수한 성능을 보입니다
10,000-100,000 vectors: 중규모 애플리케이션에 적합합니다
>100,000 vectors: 운영 환경에서는 FAISS와 같은 보다 전문화된 솔루션을 고려하십시오

from embeddb import EmbedDB
# 벡터 데이터베이스 생성
db = EmbedDB(dimension=384) # 임베딩 차원 설정
...

from embeddb import EmbedDB
# 내장 임베딩 지원 기능으로 데이터베이스 생성
db = EmbedDB()
...

30줄 미만으로 완성된 Retrieval-Augmented Generation (RAG) 구현 예시입니다:

from embeddb import EmbedDB
# 내장 임베딩 지원 기능으로 EmbedDB 초기화
db = EmbedDB() # 내부적으로 all-MiniLM-L6-v2 사용
...

핵심 벡터 데이터베이스 함수:

# 데이터베이스 생성
db = EmbedDB(dimension=None) # 차원은 선택 사항이며, 첫 번째 추가 시 설정됨
# 벡터 추가
...

텍스트 임베딩 함수 (embeddb[embeddings] 사용 시):

# 텍스트에 대한 임베딩 생성
vector = db.embed_text(text)
# 텍스트를 직접 추가 (임베딩 자동 생성)
...

✅ 다음과 같은 경우에 완벽합니다:

• 의미 검색 애플리케이션의 신속한 프로토타이핑
• 벡터 데이터베이스 학습 및 교육 목적
• 소규모에서 중규모 RAG 구현
• 확장성보다 단순성이 더 중요한 프로젝트
• 빠른 데모 및 개념 증명(PoC)

❌ 다음과 같은 용도로는 설계되지 않았습니다:

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다.

• 수백만 개의 벡터를 사용하는 프로덕션 시스템
• 고처리량(High-throughput) 애플리케이션
• 고급 필터링 및 하이브리드 검색
• 접근 제어가 필요한 다중 사용자 환경

EmbedDB는 코사인 유사도(cosine similarity)를 사용하여 인메모리 스토리지(in-memory storage) 기반의 벡터 검색을 수행합니다. 최적의 유사도 계산을 위해 벡터는 삽입 시 자동으로 정규화됩니다(normalized). 영속성(Persistence)은 간단한 JSON 직렬화(JSON serialization)를 통해 처리됩니다.

선택적인 텍스트 임베딩 기능은 sentence-transformers의 all-MiniLM-L6-v2 모델을 사용하며, 이는 대부분의 프로토타이핑 요구 사항에 대해 크기, 속도 및 품질 간의 탁월한 균형을 제공합니다.

이 데이터베이스는 학습 곡선(learning curve)이 거의 없습니다. Python에서 함수를 호출하는 방법을 안다면 EmbedDB를 사용하는 방법을 아는 것입니다.

기여를 환영합니다! 이 프로젝트의 목표는 개발자에게 유용하면서도 극도로 단순하게 유지되는 것입니다. 기능을 추가하기 전에, 그것이 프로젝트의 미니멀리스트 철학에 부합하는지 고려해 주십시오.

MIT 라이선스

아이디어를 며칠이 아닌 몇 분 만에 프로토타입으로 만들고 싶은 개발자를 위해 제작되었습니다.