semvec/pypi-packages huggingface dataset:
mykb 0.2.0
Local CLI search engine for personal knowledge bases with hybrid BM25 + vector search
License: MIT
Requires Python: >=3.12
Keywords: search, knowledge-base, vector-search, meilisearch, embedding, cli

# mykb

本地知识库搜索引擎 CLI，支持 BM25 全文搜索 + 向量语义搜索的混合检索。

## 特性

- **Hybrid Search**: BM25 全文 + 向量语义混合搜索
- **本地 Embedding**: 使用 `embeddinggemma-300m` 本地生成 embedding，无需 API
- **多数据源**: 目前支持 Obsidian vault，可扩展 Twitter、Telegram 等
- **增量索引**: 基于内容 hash，只索引变化的文档
- **可插拔后端**: 支持 Meilisearch 和 SeekDB

## 安装

```bash
# 基础安装（Meilisearch 后端）
pip install mykb

# 带 SeekDB 支持
pip install mykb[seekdb]
```

### 依赖

- **Meilisearch 后端**: 需要运行 [Meilisearch](https://www.meilisearch.com/) 服务
- **SeekDB 后端**: 嵌入式模式无需外部服务（macOS 15+ / Linux）

## 快速开始

```bash
# 1. 配置 Meilisearch
mykb config set meilisearch.url http://localhost:7700

# 2. 添加 collection（Obsidian vault）
mykb collection add my-notes --path ~/Documents/Obsidian --source obsidian

# 3. 索引（含 embedding）
mykb index my-notes --embed

# 4. 搜索
mykb search "机器学习"          # BM25 全文
mykb vsearch "AI 技术趋势"      # 向量语义
mykb query "深度学习入门" --ratio 0.5  # 混合搜索
```

## 配置

配置文件: `~/.mykb/config.toml`

```toml
[backend]
type = "meilisearch"  # 或 "seekdb"

[backend.meilisearch]
url = "http://localhost:7700"
api_key = ""

[backend.seekdb]
path = "~/.mykb/seekdb.db"  # 嵌入式模式
fulltext_analyzer = "ik"     # ik | space | ngram

[embedding]
model = "google/embeddinggemma-300m"
chunk_size = 800
chunk_overlap = 0.15

[collections.my-notes]
source = "obsidian"
path = "/path/to/vault"
mask = "**/*.md"
exclude = [".obsidian/**", ".trash/**"]
```

## 命令

| 命令 | 说明 |
|------|------|
| `mykb collection add/ls/rm` | 管理 collection |
| `mykb index [--embed] [--full]` | 索引文档 |
| `mykb embed [--full]` | 补充 embedding |
| `mykb search <query>` | BM25 全文搜索 |
| `mykb vsearch <query>` | 向量语义搜索 |
| `mykb query <query> [--ratio]` | 混合搜索 |
| `mykb status` | 查看状态 |

## 后端对比

| 特性 | Meilisearch | SeekDB |
|------|-------------|--------|
| 部署 | 独立服务 | 嵌入式 / 服务 |
| BM25 速度 | ⚡ 快 (~2ms) | 慢 (~30ms) |
| Vector 速度 | 快 (~3ms) | ⚡ 更快 (~1ms) |
| Hybrid 速度 | ⚡ 快 (~4ms) | 慢 (~33ms) |
| 资源占用 | 低 | 高 |

**建议**: 
- 通用场景用 **Meilisearch**
- 纯向量搜索场景可考虑 **SeekDB**

## 开发

```bash
# 安装开发依赖
uv sync --all-extras

# 运行测试
uv run pytest

# Benchmark
uv run python scripts/benchmark_seekdb.py --backend meilisearch -n 1000
```

## License

MIT