把散落各处的笔记、片段与灵感,沉淀成一个可检索、可浏览、可成长的本地知识库。
知识不该被锁在互相割裂的文档和笔记应用里,更不该为了「存几条笔记」就引入一整套数据库与大模型服务。 Vellum 把知识管理收敛到最小可行内核:用一份本地 JSON 文件持久化笔记,用经典 BM25 算法做中英混合全文检索,再附带一个零依赖的 Web 控制台,让知识真正「存得下、找得到、看得爽」。
无需联网、无需安装第三方库、无需配置数据库——一台装着 Python 的笔记本即可运行。
- 纯本地 · 零依赖 — 仅依赖 Python 标准库,不连网、不装包、不依赖外部服务。
- BM25 中英混合检索 — 中文按 bigram 切分、英文小写归一,标题额外加权,结果稳定可解释。
- 分层而完整的工程结构 — 笔记模型 / 索引层 / 检索层 / CLI / Web UI 各司其职,代码易读易改。
- 零依赖 Web 控制台 — 基于标准库
http.server自托管前端,支持实时搜索与即时添加。 - 工程化就绪 — 内置单元测试与 GitHub Actions CI,开箱即跑、可测、可扩展。
# 可编辑安装(推荐)
pip install -e .
# 或直接以模块方式运行,连安装都不需要
python -m vellum --help要求 Python 3.8+,无任何第三方依赖。
# 添加一条笔记(标题 / 内容 / 标签)
vellum add "如何系统学习 Python" -c "从变量、函数到面向对象" -t python 学习
# 列出全部笔记
vellum list
# 用 BM25 检索
vellum search "python 函数"
# 启动 Web 控制台(浏览器打开 http://127.0.0.1:8000)
vellum serve --port 8000数据默认写入 ~/.vellum/store.json,可用环境变量 VELLUM_PATH 自定义存储路径。
$ vellum search "python"
[0.82] 如何系统学习 Python tags: python 学习
匹配片段:…从变量、函数到面向对象…
搜索结果是真实的 BM25 打分,不是模糊匹配:1.1805 / 1.099 / 1.0803 三个分数分别对应标题命中、标题+正文命中、纯正文命中的加权结果。
vellum serve --port 8000 启动后浏览器打开即可用。前端是三个静态文件(index.html / app.js / style.css),由标准库 http.server 直接托管——没有构建步骤,改完刷新就生效。
Vellum 分为四层,请求自上而下流动,存储与索引在最底层被复用:
graph TD
UI["CLI / Web 控制台<br/>cli.py · server.py · web/"] --> S[检索入口 search.py]
UI --> M[笔记读写 models.py]
S --> IDX["BM25 索引 index.py<br/>中文 bigram · 英文归一 · 标题加权"]
M --> IDX
IDX --> ST["JSON 持久化<br/>~/.vellum/store.json"]
- 存储层 —
Note以 dataclass 描述,序列化为 JSON 落盘;读写带原子保护,进程退出不丢数据。 - 索引层 — 经典 BM25 实现,针对中文做 bigram 切分、英文做小写 + 词正则,排序可解释。
- 检索 / 服务层 — 检索入口负责打分与摘要高亮;
http.server零框架托管前端与 REST API。
启动 vellum serve 后可用:
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/notes |
列出全部笔记 |
| POST | /api/notes |
新增笔记(Body:{title, content, tags}) |
| GET | /api/search?q=关键词 |
BM25 检索并返回高亮摘要 |
- 存储后端可插拔(默认 JSON,可选 SQLite 支撑更大规模)
- Markdown 渲染与代码高亮(前端
marked.js+highlight.js) - 语义检索模式(本地嵌入模型
sentence-transformers与 BM25 混合排序) - 多空间 / 多知识库隔离
欢迎提 Issue 与 PR。本地开发:
python -m unittest discover -s tests # 运行测试MIT — 自由使用、修改与分发。
