vecdb-demo 0.1.0__tar.gz

vecdb_demo-0.1.0/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv python *)",
+      "Bash(uv pip *)"
+    ]
+  }
+}

vecdb_demo-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

vecdb_demo-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

vecdb_demo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vecdb-demo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vecdb_demo-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: vecdb-demo
+Version: 0.1.0
+Summary: Chroma / FAISS / LanceDB 를 같은 인터페이스로 비교하는 수업용 벡터 DB 데모
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chroma,embeddings,faiss,lancedb,tutorial,vector-database
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: faiss-cpu>=1.14.2
+Requires-Dist: lancedb>=0.30.2
+Requires-Dist: sentence-transformers>=5.5.1
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 벡터 DB 실습: Chroma / FAISS / LanceDB
+
+세 가지 벡터 데이터베이스에서 **insert / update / delete / search** (CRUD + 검색)를
+같은 인터페이스로 구현하고 테스트해보는 수업용 예제.
+
+## 구성
+
+| 파일 | 내용 |
+|------|------|
+| `sample_data.py` | 공통 샘플 문서와 검색 질의 |
+| `embedding.py` | 공통 임베딩 함수 (다국어 모델) |
+| `chroma_store.py` | Chroma — 텍스트만 넣으면 자동 임베딩 |
+| `faiss_store.py` | FAISS — 벡터를 직접 만들어 인덱스에 추가 |
+| `lancedb_store.py` | LanceDB — 벡터+원문을 한 테이블에 저장 |
+| `test_stores.py` | 세 store 의 CRUD+검색을 한 번에 검증하는 pytest |
+| `test_chroma_features.py` | Chroma 특징: 자동 임베딩, 메타데이터/본문 필터 |
+| `test_faiss_features.py` | FAISS 특징: L2/IP 척도, 인덱스 저장·로드, 배치 검색 |
+| `test_lancedb_features.py` | LanceDB 특징: 필터+벡터검색 결합, 디스크 영속성 |
+
+`test_*_features.py` 파일은 **각 DB의 고유 기능**을 보여준다. pytest로 검증할 수도,
+`python test_chroma_features.py` 처럼 직접 실행해 동작을 눈으로 볼 수도 있다.
+
+### 비교 예제 (한 시나리오, 세 구현)
+
+| 파일 | 내용 |
+|------|------|
+| `compare.py` | 세 DB를 같은 데이터·같은 시나리오로 돌려 특징을 나란히 비교 |
+| `test_compare.py` | 구현은 달라도 결과가 동일한지 교차 검증 |
+
+`compare.py` 는 세 DB를 **동일한 인터페이스**(`insert`/`search`/`search_in_category`)로
+감싼 어댑터로 묶어, "카테고리 필터 + 검색"이라는 같은 시나리오를 처리한다.
+같은 결과가 나오지만 필터 구현 방식이 다른 것이 핵심:
+
+- **Chroma**: `where` 메타데이터 필터 (네이티브)
+- **LanceDB**: SQL `where` prefilter (네이티브)
+- **FAISS**: 메타데이터가 없어 파이썬에서 직접 후필터링
+
+```bash
+python compare.py            # 특징 비교표 + A/B 시나리오 결과 출력
+pytest test_compare.py -v
+```
+
+세 store 는 모두 동일한 메서드를 제공한다:
+
+| 메서드 | 설명 |
+|--------|------|
+| `insert(ids, texts)` | 문서 여러 개 추가 |
+| `update(id, text)` | 문서 내용 교체 (임베딩도 재계산) |
+| `delete(id)` | 문서 삭제 |
+| `get(id)` | ID로 원문 조회 |
+| `count()` | 저장된 문서 수 |
+| `search(query, k)` | 유사 상위 k개를 `(id, 문서, 점수)`로 반환 |
+
+## 설치
+
+```bash
+uv pip install -r requirements.txt    # 또는 pip install -r requirements.txt
+```
+
+> Python 3.12 이상 필요 (`chromadb` 의존성인 `onnxruntime` 이 3.11+ wheel만 제공).
+
+## 실행 (각 DB의 CRUD 흐름 시연)
+
+```bash
+python chroma_store.py    # insert → search → update → delete 순서로 출력
+python faiss_store.py
+python lancedb_store.py
+```
+
+## 테스트
+
+```bash
+pytest test_stores.py -v
+```
+
+같은 CRUD 테스트(9개)를 세 백엔드에 모두 돌려 **27개 케이스**를 검증한다.
+검색은 `"유사도 검색을 해주는 저장소는?"` 질의에
+"벡터 데이터베이스는 임베딩을 저장하고 유사도로 검색한다." 문서를
+1순위로 찾으면 정상이다.
+
+## 핵심 차이 (수업 포인트)
+
+| | 임베딩 | 원문 저장 | update/delete | 저장 위치 |
+|---|---|---|---|---|
+| **Chroma** | 텍스트 넣으면 자동 | O (자체 보관) | id 지정 | 메모리/디스크 |
+| **FAISS** | 직접 생성해 주입 | X (dict로 직접 관리) | `IndexIDMap`로 id 삭제, update는 삭제+재삽입 | 메모리 |
+| **LanceDB** | 직접 생성해 주입 | O (테이블 컬럼) | SQL 같은 `where` 조건 | 디스크 |
+
+- **Chroma**: 가장 간단. 기본 임베딩은 영어용이라 여기선 다국어 모델을 지정했다.
+- **FAISS**: 순수 벡터 인덱스라 원문/ID 매핑을 직접 관리. 대규모·고속 검색에 강함.
+- **LanceDB**: 벡터와 메타데이터를 한 테이블에 저장, `where` 필터링 가능.

vecdb_demo-0.1.0/README.md

@@ -0,0 +1,91 @@
+# 벡터 DB 실습: Chroma / FAISS / LanceDB
+
+세 가지 벡터 데이터베이스에서 **insert / update / delete / search** (CRUD + 검색)를
+같은 인터페이스로 구현하고 테스트해보는 수업용 예제.
+
+## 구성
+
+| 파일 | 내용 |
+|------|------|
+| `sample_data.py` | 공통 샘플 문서와 검색 질의 |
+| `embedding.py` | 공통 임베딩 함수 (다국어 모델) |
+| `chroma_store.py` | Chroma — 텍스트만 넣으면 자동 임베딩 |
+| `faiss_store.py` | FAISS — 벡터를 직접 만들어 인덱스에 추가 |
+| `lancedb_store.py` | LanceDB — 벡터+원문을 한 테이블에 저장 |
+| `test_stores.py` | 세 store 의 CRUD+검색을 한 번에 검증하는 pytest |
+| `test_chroma_features.py` | Chroma 특징: 자동 임베딩, 메타데이터/본문 필터 |
+| `test_faiss_features.py` | FAISS 특징: L2/IP 척도, 인덱스 저장·로드, 배치 검색 |
+| `test_lancedb_features.py` | LanceDB 특징: 필터+벡터검색 결합, 디스크 영속성 |
+
+`test_*_features.py` 파일은 **각 DB의 고유 기능**을 보여준다. pytest로 검증할 수도,
+`python test_chroma_features.py` 처럼 직접 실행해 동작을 눈으로 볼 수도 있다.
+
+### 비교 예제 (한 시나리오, 세 구현)
+
+| 파일 | 내용 |
+|------|------|
+| `compare.py` | 세 DB를 같은 데이터·같은 시나리오로 돌려 특징을 나란히 비교 |
+| `test_compare.py` | 구현은 달라도 결과가 동일한지 교차 검증 |
+
+`compare.py` 는 세 DB를 **동일한 인터페이스**(`insert`/`search`/`search_in_category`)로
+감싼 어댑터로 묶어, "카테고리 필터 + 검색"이라는 같은 시나리오를 처리한다.
+같은 결과가 나오지만 필터 구현 방식이 다른 것이 핵심:
+
+- **Chroma**: `where` 메타데이터 필터 (네이티브)
+- **LanceDB**: SQL `where` prefilter (네이티브)
+- **FAISS**: 메타데이터가 없어 파이썬에서 직접 후필터링
+
+```bash
+python compare.py            # 특징 비교표 + A/B 시나리오 결과 출력
+pytest test_compare.py -v
+```
+
+세 store 는 모두 동일한 메서드를 제공한다:
+
+| 메서드 | 설명 |
+|--------|------|
+| `insert(ids, texts)` | 문서 여러 개 추가 |
+| `update(id, text)` | 문서 내용 교체 (임베딩도 재계산) |
+| `delete(id)` | 문서 삭제 |
+| `get(id)` | ID로 원문 조회 |
+| `count()` | 저장된 문서 수 |
+| `search(query, k)` | 유사 상위 k개를 `(id, 문서, 점수)`로 반환 |
+
+## 설치
+
+```bash
+uv pip install -r requirements.txt    # 또는 pip install -r requirements.txt
+```
+
+> Python 3.12 이상 필요 (`chromadb` 의존성인 `onnxruntime` 이 3.11+ wheel만 제공).
+
+## 실행 (각 DB의 CRUD 흐름 시연)
+
+```bash
+python chroma_store.py    # insert → search → update → delete 순서로 출력
+python faiss_store.py
+python lancedb_store.py
+```
+
+## 테스트
+
+```bash
+pytest test_stores.py -v
+```
+
+같은 CRUD 테스트(9개)를 세 백엔드에 모두 돌려 **27개 케이스**를 검증한다.
+검색은 `"유사도 검색을 해주는 저장소는?"` 질의에
+"벡터 데이터베이스는 임베딩을 저장하고 유사도로 검색한다." 문서를
+1순위로 찾으면 정상이다.
+
+## 핵심 차이 (수업 포인트)
+
+| | 임베딩 | 원문 저장 | update/delete | 저장 위치 |
+|---|---|---|---|---|
+| **Chroma** | 텍스트 넣으면 자동 | O (자체 보관) | id 지정 | 메모리/디스크 |
+| **FAISS** | 직접 생성해 주입 | X (dict로 직접 관리) | `IndexIDMap`로 id 삭제, update는 삭제+재삽입 | 메모리 |
+| **LanceDB** | 직접 생성해 주입 | O (테이블 컬럼) | SQL 같은 `where` 조건 | 디스크 |
+
+- **Chroma**: 가장 간단. 기본 임베딩은 영어용이라 여기선 다국어 모델을 지정했다.
+- **FAISS**: 순수 벡터 인덱스라 원문/ID 매핑을 직접 관리. 대규모·고속 검색에 강함.
+- **LanceDB**: 벡터와 메타데이터를 한 테이블에 저장, `where` 필터링 가능.

vecdb_demo-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vecdb-demo"
+version = "0.1.0"
+description = "Chroma / FAISS / LanceDB 를 같은 인터페이스로 비교하는 수업용 벡터 DB 데모"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = ["vector-database", "chroma", "faiss", "lancedb", "embeddings", "tutorial"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+    "Intended Audience :: Education",
+]
+dependencies = [
+    "chromadb>=1.5.9",
+    "faiss-cpu>=1.14.2",
+    "lancedb>=0.30.2",
+    "sentence-transformers>=5.5.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=9.0.3"]
+
+[project.scripts]
+vecdb-compare = "vecdb_demo.compare:main"
+vecdb-chroma = "vecdb_demo.chroma_store:main"
+vecdb-faiss = "vecdb_demo.faiss_store:main"
+vecdb-lancedb = "vecdb_demo.lancedb_store:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vecdb_demo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vecdb_demo-0.1.0/requirements.txt

@@ -0,0 +1,10 @@
+# 공통 임베딩 모델
+sentence-transformers
+
+# 벡터 DB
+chromadb
+faiss-cpu
+lancedb
+
+# 테스트
+pytest

vecdb_demo-0.1.0/src/vecdb_demo/__init__.py

@@ -0,0 +1,8 @@
+"""vecdb-demo: Chroma / FAISS / LanceDB 를 같은 인터페이스로 비교하는 수업용 패키지."""
+
+from vecdb_demo.chroma_store import ChromaStore
+from vecdb_demo.faiss_store import FaissStore
+from vecdb_demo.lancedb_store import LanceStore
+
+__version__ = "0.1.0"
+__all__ = ["ChromaStore", "FaissStore", "LanceStore"]

vecdb_demo-0.1.0/src/vecdb_demo/chroma_store.py

@@ -0,0 +1,84 @@
+"""Chroma 로 CRUD + 검색 해보기.
+
+Chroma 는 텍스트를 넣으면 내부적으로 임베딩까지 해준다.
+다만 기본 임베딩 모델은 영어용이라, 다른 예제(embedding.py)와 동일한
+다국어 모델을 임베딩 함수로 지정해 한국어 검색 품질을 맞춘다.
+
+ID 는 문자열만 허용하므로, 공통 인터페이스(정수 ID)를 내부에서 str 로 변환한다.
+
+실행: python chroma_store.py   (insert→search→update→delete 흐름 시연)
+"""
+
+import chromadb
+from chromadb.utils import embedding_functions
+
+# 다른 예제와 동일한 다국어 임베딩 모델
+_EMBED_FN = embedding_functions.SentenceTransformerEmbeddingFunction(
+    model_name="paraphrase-multilingual-MiniLM-L12-v2"
+)
+
+
+class ChromaStore:
+    def __init__(self, name="demo"):
+        # 메모리 클라이언트. 디스크 저장은 chromadb.PersistentClient(path=...)
+        self.client = chromadb.Client()
+        # 매번 깨끗한 상태로 시작 (이미 있으면 지우고 새로 생성)
+        try:
+            self.client.delete_collection(name)
+        except Exception:
+            pass
+        self.collection = self.client.create_collection(
+            name=name, embedding_function=_EMBED_FN
+        )
+
+    def insert(self, ids, texts):
+        """여러 문서를 한 번에 추가. (id는 정수 리스트)"""
+        self.collection.add(ids=[str(i) for i in ids], documents=texts)
+
+    def update(self, id, text):
+        """기존 문서의 내용을 교체 (임베딩도 자동 재계산)."""
+        self.collection.update(ids=[str(id)], documents=[text])
+
+    def delete(self, id):
+        """문서 삭제."""
+        self.collection.delete(ids=[str(id)])
+
+    def get(self, id):
+        """ID로 원문 조회. 없으면 None."""
+        res = self.collection.get(ids=[str(id)])
+        docs = res["documents"]
+        return docs[0] if docs else None
+
+    def count(self):
+        """저장된 문서 수."""
+        return self.collection.count()
+
+    def search(self, query, k=2):
+        """질의와 유사한 상위 k개를 (id, 문서, 거리)로 반환. 거리는 작을수록 가깝다."""
+        res = self.collection.query(query_texts=[query], n_results=k)
+        ids = [int(i) for i in res["ids"][0]]
+        docs = res["documents"][0]
+        dists = res["distances"][0]
+        return list(zip(ids, docs, dists))
+
+
+def main():
+    from vecdb_demo.sample_data import DOCUMENTS, QUERY
+
+    store = ChromaStore()
+    store.insert(ids=list(range(len(DOCUMENTS))), texts=DOCUMENTS)
+    print(f"insert 후 문서 수: {store.count()}")
+
+    print(f"\n[검색] {QUERY}")
+    for rank, (id_, doc, dist) in enumerate(store.search(QUERY), start=1):
+        print(f"  {rank}. (id={id_}, 거리={dist:.4f}) {doc}")
+
+    store.update(0, "사과는 비타민이 풍부한 빨간 과일이다.")
+    print(f"\n[update id=0] -> {store.get(0)}")
+
+    store.delete(1)
+    print(f"[delete id=1] 이후 문서 수: {store.count()}, id=1 조회: {store.get(1)}")
+
+
+if __name__ == "__main__":
+    main()

vecdb_demo-0.1.0/src/vecdb_demo/compare.py

@@ -0,0 +1,165 @@
+"""세 벡터 DB를 '같은 데이터·같은 시나리오'로 돌려 특징을 비교한다.
+
+시나리오: 문서 6개(+카테고리)를 넣고
+  (A) 그냥 검색,
+  (B) 특정 카테고리 안에서만 검색
+을 세 DB에 똑같이 수행한다. 결과는 같지만 '구현 방식'이 다르다는 점이 핵심:
+
+  - Chroma : where 메타데이터 필터 (네이티브)
+  - LanceDB: SQL where prefilter (네이티브)
+  - FAISS  : 메타데이터가 없어 파이썬에서 직접 후필터링
+
+세 어댑터는 동일한 인터페이스(insert / search / search_in_category)를 갖는다.
+
+데모 실행: python compare.py
+테스트:    pytest test_compare.py -v
+"""
+
+import chromadb
+import faiss
+import lancedb
+import numpy as np
+from chromadb.utils import embedding_functions
+
+from vecdb_demo.embedding import embed, DIM
+from vecdb_demo.sample_data import DOCUMENTS, CATEGORIES
+
+# (id, 텍스트, 카테고리) 형태의 공통 데이터
+DATA = list(zip(range(len(DOCUMENTS)), DOCUMENTS, CATEGORIES))
+
+_CHROMA_EMBED_FN = embedding_functions.SentenceTransformerEmbeddingFunction(
+    model_name="paraphrase-multilingual-MiniLM-L12-v2"
+)
+
+
+class ChromaAdapter:
+    name = "Chroma"
+    # 특징 요약 (auto_embed, metadata_filter, persistence, metric)
+    traits = ("자동", "네이티브 where", "메모리/디스크", "거리(작을수록 가까움)")
+
+    def __init__(self):
+        client = chromadb.Client()
+        try:
+            client.delete_collection("cmp")
+        except Exception:
+            pass
+        self.col = client.create_collection("cmp", embedding_function=_CHROMA_EMBED_FN)
+
+    def insert(self, data):
+        self.col.add(
+            ids=[str(i) for i, _, _ in data],
+            documents=[t for _, t, _ in data],
+            metadatas=[{"category": c} for _, _, c in data],
+        )
+
+    def search(self, query, k=2):
+        r = self.col.query(query_texts=[query], n_results=k)
+        return list(zip([int(i) for i in r["ids"][0]], r["documents"][0]))
+
+    def search_in_category(self, query, category, k=2):
+        # 네이티브 메타데이터 필터
+        r = self.col.query(query_texts=[query], n_results=k, where={"category": category})
+        return list(zip([int(i) for i in r["ids"][0]], r["documents"][0]))
+
+
+class FaissAdapter:
+    name = "FAISS"
+    traits = ("직접 주입", "수동(파이썬 후필터)", "메모리(+파일)", "유사도/거리 선택")
+
+    def __init__(self):
+        self.index = faiss.IndexIDMap(faiss.IndexFlatIP(DIM))
+        self.meta = {}  # id -> (text, category)
+
+    def insert(self, data):
+        ids = [i for i, _, _ in data]
+        self.index.add_with_ids(embed([t for _, t, _ in data]), np.array(ids, dtype="int64"))
+        for i, t, c in data:
+            self.meta[i] = (t, c)
+
+    def _search_ids(self, query, k):
+        _, ids = self.index.search(embed([query]), k)
+        return [int(i) for i in ids[0] if i != -1]
+
+    def search(self, query, k=2):
+        return [(i, self.meta[i][0]) for i in self._search_ids(query, k)]
+
+    def search_in_category(self, query, category, k=2):
+        # FAISS엔 메타데이터가 없다 → 넉넉히 검색한 뒤 파이썬에서 카테고리로 거른다.
+        candidates = self._search_ids(query, self.index.ntotal)
+        hits = [i for i in candidates if self.meta[i][1] == category]
+        return [(i, self.meta[i][0]) for i in hits[:k]]
+
+
+class LanceAdapter:
+    name = "LanceDB"
+    traits = ("직접 주입", "네이티브 SQL where", "디스크", "거리(작을수록 가까움)")
+
+    def __init__(self, db_path="./lance_compare"):
+        db = lancedb.connect(db_path)
+        if "cmp" in db.table_names():
+            db.drop_table("cmp")
+        self._db = db
+
+    def insert(self, data):
+        vectors = embed([t for _, t, _ in data])
+        rows = [
+            {"id": i, "text": t, "category": c, "vector": v}
+            for (i, t, c), v in zip(data, vectors)
+        ]
+        self.table = self._db.create_table("cmp", data=rows)
+
+    def search(self, query, k=2):
+        rows = self.table.search(embed([query])[0]).limit(k).to_list()
+        return [(r["id"], r["text"]) for r in rows]
+
+    def search_in_category(self, query, category, k=2):
+        # 네이티브 SQL prefilter
+        rows = (
+            self.table.search(embed([query])[0])
+            .where(f"category = '{category}'", prefilter=True)
+            .limit(k)
+            .to_list()
+        )
+        return [(r["id"], r["text"]) for r in rows]
+
+
+def build_all():
+    """세 어댑터에 동일한 데이터를 넣어 반환."""
+    adapters = [ChromaAdapter(), FaissAdapter(), LanceAdapter()]
+    for a in adapters:
+        a.insert(DATA)
+    return adapters
+
+
+def main():
+    adapters = build_all()
+    query = "유사도 검색을 해주는 저장소는?"
+    category = "동물"
+
+    print("=" * 70)
+    print("특징 비교표")
+    print("=" * 70)
+    header = ("DB", "임베딩", "메타필터", "저장", "거리척도")
+    print(f"{header[0]:<9}{header[1]:<7}{header[2]:<16}{header[3]:<13}{header[4]}")
+    for a in adapters:
+        e, f, p, m = a.traits
+        print(f"{a.name:<9}{e:<7}{f:<16}{p:<13}{m}")
+
+    print("\n" + "=" * 70)
+    print(f"(A) 같은 질의로 검색: '{query}'")
+    print("=" * 70)
+    for a in adapters:
+        top = a.search(query, k=1)[0]
+        print(f"  {a.name:<9} -> (id={top[0]}) {top[1]}")
+
+    print("\n" + "=" * 70)
+    print(f"(B) '{category}' 카테고리 안에서만 검색: '귀여운 동물'")
+    print("=" * 70)
+    for a in adapters:
+        hits = a.search_in_category("귀여운 동물", category, k=2)
+        joined = ", ".join(t for _, t in hits)
+        print(f"  {a.name:<9} -> {joined}")
+
+
+if __name__ == "__main__":
+    main()

vecdb_demo-0.1.0/src/vecdb_demo/embedding.py

@@ -0,0 +1,22 @@
+"""공통 임베딩 함수.
+
+sentence-transformers 의 다국어 모델을 사용해 텍스트를 벡터로 변환한다.
+FAISS / LanceDB 처럼 벡터를 직접 넣어야 하는 DB에서 재사용한다.
+(Chroma 는 자체 임베딩 기능이 있어 텍스트만 넣어도 된다.)
+"""
+
+from sentence_transformers import SentenceTransformer
+
+# 한국어를 포함한 다국어를 지원하는 가벼운 모델
+_MODEL_NAME = "paraphrase-multilingual-MiniLM-L12-v2"
+
+# 모델 로딩은 비싸므로 모듈 전역에서 한 번만 한다.
+_model = SentenceTransformer(_MODEL_NAME)
+
+# 이 모델이 출력하는 벡터 차원 (FAISS 인덱스 생성 시 필요)
+DIM = _model.get_sentence_embedding_dimension()
+
+
+def embed(texts):
+    """텍스트 리스트를 float32 numpy 배열(N x DIM)로 변환."""
+    return _model.encode(texts, normalize_embeddings=True).astype("float32")