rryam/VecturaKit

VecturaKit – Swift 앱을 위한 디바이스 내 벡터 데이터베이스

무엇인가요 – VecturaKit은 iOS, macOS, watchOS, tvOS, visionOS 앱이 텍스트 문서를 디바이스 내부에 로컬로 벡터 임베딩 형태로 저장할 수 있게 해주는 Swift 라이브러리입니다. 일반적인 벡터 데이터베이스 기능(추가, 업데이트, 삭제, 검색)에 더해 하이브리드 BM25 + 벡터 검색을 제공하며, 모든 데이터가 사용자 하드웨어 내부에 머무르도록 완전히 디바이스 내부에서 작동하도록 설계되었습니다.

주요 기능

• 플러그인 가능한 임베딩 엔진 – VecturaEmbedder를 준수하는 임베딩 엔진을 어떤 것도 연결할 수 있습니다. 이 패키지에는 다음이 포함되어 있습니다:
  • NLContextualEmbedder – Apple의 NaturalLanguage 프레임워크 사용 (외부 종속성 없음).
  • OpenAICompatibleEmbedder – /v1/embeddings API와 호환되는 어떤 서비스든 사용 가능 (예: OpenAI, Ollama, LM Studio).
  • SwiftEmbedder (별도의 VecturaEmbeddingsKit를 통해) – swift-embeddings 모델(예: Model2Vec, BERT, RoBERTa 등)을 실행.
  • MLXEmbedder (별도의 VecturaMLXKit를 통해) – Apple MLX에서 GPU 가속 임베딩.
• 하이브리드 검색 – 벡터 간 코사인 유사도와 BM25 텍스트 점수를 결합하며, 두 요소 간 가중치는 사용자 정의 가능.
• 사용자 정의 스토리지 및 검색 – VecturaStorage를 준수하여 SQLite, Core Data, 클라우드 등 사용자 정의 스토리지 백엔드를 제공할 수 있으며, VecturaSearchEngine를 준수하여 검색 알고리즘을 교체할 수 있습니다.
• 메모리 전략 – 자동, 전체 메모리, 또는 필요 시 문서를 로드하는 인덱스 모드를 지원하여 수백 개에서 수백만 개의 레코드까지 사용 가능.
• CLI 도구 – vectura-cli (NaturalLanguage)와 vectura-oai-cli (OpenAI 호환)는 명령줄에서 실험할 수 있게 해줍니다.

일반적인 사용 흐름

1. 설정 – VecturaConfig 구성 (이름, 선택적 사용자 정의 디렉터리, 검색 옵션, 메모리 전략).
2. 임베딩 엔진 생성 – 예: let embedder = try await NLContextualEmbedder(language: .english).
3. 데이터베이스 인스턴스화 – let db = try await VecturaKit(config: config, embedder: embedder).
4. 문서 추가 – await db.addDocuments(texts: [...]) (배치 처리는 병렬화됨).
5. 검색 – await db.search(query: "some query", numResults: 5)는 VecturaSearchResult 배열을 반환하며, id, 텍스트, 유사도 점수, 타임스탬프 포함.
6. 문서 관리 – id 기반 업데이트, 삭제, 조회, 또는 전체 데이터베이스 리셋.

왜 중요한가요

• 개인정보 우선 – 모든 임베딩과 인덱싱이 로컬에서 이루어지므로, 사용자 데이터를 클라우드로 전송하지 않고도 의미 기반 검색이 가능.
• Swift 네이티브 – OpenAI 호환 임베딩 엔진을 선택하지 않는 한, Python 또는 외부 서비스로의 브리징이 필요 없음.
• 확장성 – 플러그인 아키텍처 덕분에, 새로운 임베딩 모델이나 사용자 정의 랭킹 로직을 앱의 다른 부분을 변경하지 않고 교체 가능.

시작하기 Swift Package Manager로 패키지 추가:

.dependencies: [
    .package(url: "https://github.com/rryam/VecturaKit.git", from: "6.3.0"),
]

그 후 VecturaKit (옵션으로 VecturaNLKit 또는 VecturaOAIKit)를 가져와 README에 나와 있는 빠른 시작 코드를 따라주세요.

문서 및 커뮤니티

• 상세 가이드는 Docs/ 폴더에 있음 (인덱스 스토리지, 성능 벤치마크).
• 임베딩용 별도 패키지 (VecturaEmbeddingsKit)와 MLX 가속용 (VecturaMLXKit).
• 오픈소스 라이선스(MIT)와 기여 가이드라인이 제공됩니다.

---

결론 – VecturaKit은 디바이스 내 AI/ML 작업을 위한 진정한 프로덕션 준비된 Swift 벡터 데이터베이스로, 유연한 임베딩 백엔드, 하이브리드 검색, 사용자 정의 스토리지 또는 랭킹을 위한 확장성을 제공합니다.