VectorDB

VectorDB 是一个简单、轻量级、完全本地化的端到端解决方案，用于基于嵌入的文本检索。

得益于其低延迟和较小的内存占用，VectorDB 被用于支持 Kagi Search 内部的 AI 功能。

请查看一个 示例 Colab 笔记本，其中它被用来根据用户声明的兴趣过滤 Kagi Small Web 的 RSS 订阅内容。

安装

要安装 VectorDB，请使用 pip：

pip install vectordb2

使用方法

以下是一个快速示例，将数据加载到内存中并执行检索。所有数据，包括嵌入和向量搜索，都将在本地处理，对用户完全透明，同时提供尽可能高的性能。

from vectordb import Memory

# Memory 是您想要存储或搜索的所有内容的容器。
memory = Memory()

memory.save(
    ["苹果是绿色的", "橙子是橙色的"],  # 保存您的文本内容。对于长文本，我们会自动进行分块处理
    [{"url": "https://apples.com"}, {"url": "https://oranges.com"}],  # 可选：为内容关联任意元数据
)

# 搜索前 n 个相关结果，自动使用嵌入技术
query = "绿色"
results = memory.search(query, top_n=1)

print(results)

此操作将返回带有附加元数据和向量距离的文本块（其中 0 表示完全匹配，数值越大表示距离越远）。

[
  {
    "chunk": "苹果是绿色的",
    "metadata": {"url": "https://apples.com"},
    "distance": 0.87
  }
]

选项

Memory(memory_file=None, chunking_strategy={"mode":"sliding_window"}, embeddings="normal")

• memory_file: 可选。 内存文件的路径。如果提供，内存将持久化到磁盘，并从此文件加载或保存。

• chunking_strategy: 可选。 包含分块模式的字典。

  选项：
  {'mode':'sliding_window', 'window_size': 240, 'overlap': 8} (默认)
  {'mode':'paragraph'}

• embeddings: 可选。

  选项：
  fast - 使用 Universal Sentence Encoder 4
  normal - 使用 "BAAI/bge-small-en-v1.5" (默认)
  best - 使用 "BAAI/bge-base-en-v1.5"
  multilingual - 使用 Universal Sentence Encoder Multilingual Large 3

  您也可以指定自定义的 HuggingFace 模型名称，例如 TaylorAI/bge-micro-v2。更多信息请参阅 预训练模型 和 MTEB。

Memory.save(texts, metadata, memory_file=None)

将内容保存到内存中。元数据会自动优化以减少资源占用。

• texts: 必填。 要保存的文本或文本列表。
• metdata: 可选。 与文本关联的元数据或元数据列表。
• memory_file: 可选。 用于持久化内存文件的路径。默认情况下

Memory.search(query, top_n=5, unique=False, batch_results="flatten")

在内存中进行搜索。

• query: 必填。 查询文本或查询列表（有关如何处理列表查询的结果，请参阅下方的 batch_results 选项）。
• top_n: 可选。 返回最相似文本块的数量（默认：5）。
• unique: 可选。 仅返回来自不同原始文本的文本块（来自同一文本的重复块将被忽略）。请注意，这可能会导致返回的文本块数量少于请求的数量（默认：False）。
• batch_results: 可选。 当输入为查询列表时，输出算法可以是“flatten”或“diverse”。Flatten 会返回所有查询中最接近的邻居，这意味着所有结果可能都来自单个查询。而“diverse”则会尝试分散结果，使每个查询的最近邻都能被均匀地加入（先按所有查询的最近邻排序，再按次近邻排序，依此类推）。（默认：“flatten”）

Memory.clear()

清空内存。

Memory.dump()

打印内存中的内容。

示例

from vectordb import Memory

memory = Memory(
    chunking_strategy={"mode": "sliding_window", "window_size": 128, "overlap": 16}, embeddings='TaylorAI/bge-micro-v2'
)

texts = [
    """
机器学习是一种数据分析方法，能够自动构建分析模型。

它是人工智能的一个分支，其核心思想是让系统能够从数据中学习、识别模式，并在尽量减少人类干预的情况下做出决策。

机器学习算法会基于包含期望输出示例的数据集进行训练。例如，用于图像分类的机器学习算法可能会在包含猫和狗图像的数据集上进行训练。一旦算法训练完成，它就可以用来对新数据进行预测。比如，该图像分类算法可以用来判断一张新图片中是猫还是狗。

机器学习算法可以应用于解决各种各样的问题。常见的应用场景包括：

分类：将数据划分为不同的类别。例如，机器学习算法可以用来将电子邮件分类为垃圾邮件或非垃圾邮件。

回归：预测连续值。例如，机器学习算法可以用来预测房屋的价格。

聚类：找出相似的数据点群组。例如，机器学习算法可以用来发现具有相似购买习惯的客户群体。

异常检测：识别与整体数据不同的异常点。例如，机器学习算法可以用来检测欺诈性的信用卡交易。

机器学习是一种功能强大的工具，能够解决多种多样的问题。随着可用数据量的持续增长，机器学习在未来很可能会变得更加重要。
""",
    """
人工智能（AI）是指通过编程使机器模拟人类智能，从而像人类一样思考并模仿人类行为。

该术语也可以指任何表现出与人类思维相关特征的机器，例如学习和解决问题的能力。

人工智能研究在开发解决广泛问题的有效技术方面取得了巨大成功，从游戏博弈到医学诊断等各个领域。

然而，要真正达到人类的智能水平，人工智能还有很长的路要走。其中一个主要挑战在于，人类智能极其复杂且尚未完全被理解。

尽管面临诸多挑战，人工智能仍是一个快速发展的领域，有望彻底改变我们生活的许多方面。人工智能的一些潜在好处包括：

提高生产力：人工智能可以自动化目前由人类执行的任务，从而让我们有更多时间从事更具创造性和成就感的工作。

改善决策能力：人工智能可以根据比人类通常能够获取的更广泛的数据做出更明智的决策。

增强创造力：人工智能可以生成新的想法和解决方案，超越人类自身的想象范围。

当然，人工智能也伴随着一些潜在风险，例如：

工作岗位流失：随着人工智能能力的提升，部分人类工作岗位可能会被取代。

武器化：人工智能可能被用于研发比现有武器更强大、更具破坏性的新型武器。

失去控制：如果人工智能变得过于强大，我们可能会失去对其的控制，进而带来灾难性的后果。

因此，在继续发展这项技术的过程中，我们需要仔细权衡人工智能的潜在收益与风险。通过周密的规划和监督，人工智能确实有可能让世界变得更美好；但若处理不当，也可能引发严重问题。
""",
]

metadata_list = [
    {
        "title": "机器学习简介",
        "url": "https://example.com/introduction-to-machine-learning",
    },
    {
        "title": "人工智能简介",
        "url": "https://example.com/introduction-to-artificial-intelligence",
    },
]

memory.save(texts, metadata_list)

query = "人工智能与机器学习之间有什么关系？"
results = memory.search(query, top_n=3, unique=True)
print(results)

# 因设置了unique参数为True，将返回两条结果

输出：

[
  {
    "chunk": "人工智能（AI）是指通过编程使机器模拟人类智能，从而像人类一样思考并模仿人类行为。该术语也可以指任何表现出与人类思维相关特征的机器，例如学习和解决问题的能力。人工智能研究在开发解决广泛问题的有效技术方面取得了巨大成功，从游戏博弈到医学诊断等各个领域。然而，要真正达到人类的智能水平，人工智能还有很长的路要走。其中一个主要挑战在于，人类智能极其复杂且尚未完全被理解。尽管面临诸多挑战，人工智能仍是一个快速发展的领域，有望彻底改变我们生活的许多方面。人工智能的一些潜在好处包括：增加",
    "metadata": {
      "title": "人工智能简介",
      "url": "https://example.com/introduction-to-artificial-intelligence"
    },
    "distance": 0.87
  },
  {
    "chunk": "机器学习是一种数据分析方法，能够自动构建分析模型。它是人工智能的一个分支，其核心思想是让系统能够从数据中学习、识别模式并以最小的人为干预做出决策。机器学习算法会基于包含期望输出示例的数据集进行训练。例如，用于图像分类的机器学习算法可能会在包含猫和狗图像的数据集上进行训练。一旦算法训练完成，它就可以用来对新数据进行预测。例如，该图像分类算法可以用来判断一张新图片中是猫还是狗。机器学习算法可以用于",
    "metadata": {
      "title": "机器学习简介",
      "url": "https://example.com/introduction-to-machine-learning"
    },
    "distance": 0.83
  }
]

嵌入模型性能分析

我们使用标准化基准持续评估嵌入模型（分数越高越好）。平均延迟是在本地 CPU 上测量的（数值越低越好）。基准数据来自 MTEB。

模型	延迟	基准测试 1	基准测试 2	基准测试 3	基准测试 4
all-mpnet-base-v2	6.12 s	80.28	65.07	43.69	83.04
all-MiniLM-L6-v2	1.14 s	78.9	63.05	42.35	82.37
BAAI/bge-large-en-v1.5	20.8 s	83.11	75.97	46.08	87.12
BAAI/bge-base-en-v1.5	6.48 s	82.4	75.53	45.77	86.55
BAAI/bge-small-en-v1.5	1.85 s	81.59	74.14	43.82	84.92
TaylorAI/bge-micro-v2	0.671 s	78.65	68.04	39.18	82.81
TaylorAI/gte-tiny	1.25 s	80.46	70.35	42.09	82.83
thenlper/gte-base	6.28 s	82.3	73.01	46.2	84.57
thenlper/gte-small	2.14 s	82.07	72.31	44.89	83.54
universal-sentence-encoder-large/5	0.769 s	74.05	67.9	37.82	79.53
universal-sentence-encoder-multilingual-large/3	1.02 s	75.35	65.78	35.06	79.62
universal-sentence-encoder-multilingual/3	0.162 s	75.39	63.42	34.82	75.43
universal-sentence-encoder/4	0.019 s	72.04	64.45	35.71	76.23

CPU 上的相对嵌入延迟

GPU 上的相对嵌入延迟

向量检索性能分析

向量数据库同样针对检索速度进行了优化。对于小规模数据集（少于 4000 个分块），我们会自动使用 Faiss；而对于大规模数据集，则使用 mrpt，以确保在各种应用场景下都能达到最佳性能。

许可证

MIT 许可证。

VectorDB 快速上手指南

VectorDB 是一个简单、轻量级且完全本地化的端到端解决方案，专为基于嵌入（Embeddings）的文本检索设计。它具有低延迟和小内存占用的特点，所有数据处理（包括向量化和搜索）均在本地完成，无需依赖外部服务。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux。
• Python 版本：建议 Python 3.8 及以上版本。
• 前置依赖：无需额外安装系统级依赖，库会自动处理模型下载和运行时环境。
• 网络要求：首次运行时需联网下载预训练嵌入模型（后续可离线使用）。若网络受限，可配置国内镜像或手动下载模型。

安装步骤

使用 pip 直接安装：

pip install vectordb2

提示：国内用户若下载缓慢，可尝试使用清华或阿里镜像源加速：

pip install vectordb2 -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简示例，展示如何初始化内存、保存文本数据并执行语义搜索。

from vectordb import Memory

# 初始化内存对象（所有数据存储在内存中）
memory = Memory()

# 保存文本内容及可选元数据
# 长文本会自动分块处理
memory.save(
    ["apples are green", "oranges are orange"],
    [{"url": "https://apples.com"}, {"url": "https://oranges.com"}],
)

# 执行语义搜索
query = "green"
results = memory.search(query, top_n=1)

print(results)

输出示例：

[
  {
    "chunk": "apples are green",
    "metadata": {"url": "https://apples.com"},
    "distance": 0.87
  }
]

参数说明简述

• Memory() 支持自定义分块策略和嵌入模型，例如：

  memory = Memory(
      chunking_strategy={"mode": "sliding_window", "window_size": 128, "overlap": 16},
      embeddings='TaylorAI/bge-micro-v2'
  )
  

• save(texts, metadata)：texts 为必填，metadata 可选。
• search(query, top_n=5)：返回最相关的文本片段及距离值（越小越匹配）。

该工具适合快速构建本地知识库、文档检索或个性化内容过滤等应用场景。