vectordb
本地向量数据库，通过文本分块+Embedding+向量检索为AI应用提供本地记忆能力
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
本地向量数据库，通过文本分块+Embedding+向量检索为AI应用提供本地记忆能力
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象这样一个场景：你向一个 AI 助手提问：「我上周收藏的那篇关于检索增强生成的技术文章讲了什么？」AI 沉默了三秒，然后茫然地回答「我不知道」。这不是 AI 不够聪明，而是它根本没有记忆——每次对话都是一次从零开始。向量数据库（Vector Database）正是解决这个问题的关键基础设施，而 VectorDB 则是其中最轻量、最接地气的选择之一。
VectorDB 由 Vladimir Prelovac（Kagi Search 团队）开发并维护，源代码托管于 kagisearch/vectordb。Prelovac 是互联网搜索领域的老兵，曾主导过多个搜索相关项目，而 VectorDB 的诞生直接来源于生产级需求：为 Kagi Search 的 AI 功能提供本地化、低延迟的文本检索能力。
从项目的设计决策可以看出明显的工程化取向：代码量精简（整个项目仅 22 个文件），依赖栈轻量（可运行在纯 CPU 环境），数据完全存储在本地文件（pickle 格式）。这与其他追求功能丰富而引入大量外部依赖的向量库（如 Milvus、Pinecone 客户端）形成了鲜明对比——VectorDB 的核心理念是**「最小化引入，最大化实用」**。
VectorDB 的工作流程可以归纳为四个核心步骤，理解这四步即掌握了向量检索的本质：
第一步：文本分块（Chunking）
将长文本切分为语义完整的小块（chunk）。VectorDB 支持两种策略：
\n\n 分割，保持段落语义完整，适合结构化文档第二步：向量化（Embedding）
每个文本块通过预训练语言模型转换为高维向量。VectorDB 支持四种 embedding 模型：
| 模型 | 特点 | 适用场景 |
|---|---|---|
fast | Universal Sentence Encoder v4，最快 | 实时响应优先 |
normal（默认） | BAAI/bge-small-en-v1.5 | 平衡速度与质量 |
best | BAAI/bge-base-en-v1.5 | 质量优先 |
multilingual | USE Multilingual Large v3 | 多语言文档 |
底层封装了 sentence_transformers（HuggingFace）和 tensorflow_hub 两种模型生态，开发者也可以传入任意 HuggingFace 模型名称（如 TaylorAI/bge-micro-v2），灵活性很高。
第三步：存储与索引（Storage + Vector Search）
向量数据通过 FAISS（Facebook AI Similarity Search）构建索引并存储。VectorDB 会根据数据规模自动选择策略：
元数据（标题、URL、来源等）以 pickle 格式持久化到磁盘，支持断电恢复。
第四步：相似性检索（Search）
用户输入查询文本 → 转换为向量 → 在索引中查找最近邻。返回结果包含文本块、关联元数据和向量距离（distance：0 为完全匹配，数值越大差异越大）。支持 unique 参数去重，以及 batch_results 参数控制多查询结果聚合方式（flatten 或 diverse）。
图1：VectorDB 检索引擎性能对比（来自项目 README）
从图中可以看出，VectorDB 在不同数据规模下均能保持稳定的检索速度，MRPT 模式在大规模数据场景下展现出明显的速度优势。
项目代码结构极为精简，5 个核心模块各司其职：
| 模块 | 职责 | 核心类 |
|---|---|---|
vectordb/__init__.py | 对外导出 | 暴露 Memory 类 |
vectordb/chunking.py | 文本分块 | Chunker |
vectordb/embedding.py | 向量生成 | Embedder（支持多种模型） |
vectordb/vector_search.py | 相似性检索 | VectorSearch（MRPT/FAISS） |
vectordb/storage.py | 持久化 | Storage（pickle） |
vectordb/memory.py 是整个系统的编排层，负责协调以上四个模块的协作，对外提供统一的 save()、search()、clear()、dump() 接口。这种分层设计使得每个模块都可以独立测试和替换——例如想换用不同的 embedding 模型，只需修改 Embedder 类而不影响其他部分。
代码质量方面，项目启用了 Pylint 并配置了严格的检查规则（too-many-locals、too-many-instance-attributes 等），虽然注释中大量使用 # pylint: disable 规避了部分警告，但整体风格保持了可读性。代码附带了 GitHub Actions CI（pylint 流水线），自动化程度合格。
VectorDB 的 API 设计极为简洁，真正做到了「零学习成本」：
from vectordb import Memory
memory = Memory() # 默认配置：滑动窗口分块 + BAAI/bge-small-en-v1.5 向量化
memory.save(["苹果是绿色的", "橙子是橙色的"], [{"url": "..."}, {"url": "..."}])
results = memory.search("绿色水果", top_n=1)
print(results) # [{'chunk': '苹果是绿色的', 'metadata': {...}, 'distance': 0.87}]
这与使用 Pinecone、Weaviate 等云向量数据库的复杂度形成了强烈对比——无需注册账号、无需配置服务端、无需管理 API Key，所有数据在本地处理。对于隐私敏感型应用（医疗记录、内部文档）和边缘部署场景（个人设备、嵌入式系统），这种「零云依赖」的特性尤为重要。
坦诚地说，VectorDB 并非万能解药。它的主要局限体现在：
1. 单机存储瓶颈：pickle 持久化方案在数据量超过内存容量时性能会急剧下降，不适合构建大规模向量数据库。对于百万级向量检索需求，应当选择专门的向量数据库（Milvus、Qdrant 等）。
2. 不支持向量更新与删除：当前的 save() 方法是追加模式，不支持对已有向量进行更新或删除。如果需要修改内容，只能重建整个内存文件。
3. 检索算法有限：仅支持 L2 距离（欧氏距离）排序，不支持余弦相似度（cosine similarity）。对于某些 embedding 模型，余弦相似度可能是更好的度量标准。
4. 无分布式支持：不支持主从复制、分片等分布式特性，不能横向扩展。
VectorDB 的出现反映了一个趋势：在向量检索领域，轻量化与实用性正在赢得越来越多开发者的青睐。随着 LLM 应用井喷，大量开发者需要的是「能在自己的服务器上跑起来、不依赖第三方服务的向量检索工具」，而不是功能强大但运维复杂的企业级数据库。
类似定位的项目（如 ChromaDB、FAISS 封装层）近年来增长迅猛，VectorDB 凭借其极致精简的设计和 Kagi Search 的生产级背书，在轻量向量库赛道中占据了一席之地。项目在 GitHub 拥有 791 颗星，MIT 协议开源，如果你需要快速为本地 AI 应用添加记忆功能，VectorDB 是一个值得一试的选择。