向量数据库， 一个文件就够。

import recern_vector as rv

db = rv.Database.open_or_create("docs.rvec")
docs = db.create_collection("docs", dim=384, metric="cosine")
docs.upsert_many(ids, embeddings, metadatas)

hits = docs.search(query, k=5, filter={"lang": "en"})
docs.explain(query, k=5)  # strategy, visited nodes, time

$ recern-vector query docs.rvec docs --like doc-42 -k 3 \
    --filter '{"lang": "en", "year": {"$gte": 2020}}' \
    --explain

  #  id          distance  metadata
  1  doc-42      -0.00000  {"lang":"en","year":2024}
  2  doc-18861    0.63155  {"lang":"en","year":2022}
  3  doc-10899    0.63834  {"lang":"en","year":2024}

  strategy      hnsw
  ef            64
  selectivity   ~19.9% of records match the filter
  visited       7,244 nodes
  distances     7,330 computed
  time          529 µs

Python 绑定直接接收 NumPy float32 数组，无需逐元素转换。批量插入使用全部核心构建索引。

• HNSW 与精确搜索

  图索引支持按集合配置 m、ef_construction 和 ef_search；需要基准真值时可使用精确扫描。

• 余弦、L2 与点积

  每个集合使用固定维度和距离度量。使用余弦度量的向量在存储时会归一化。

• 元数据过滤

  支持相等、$in、范围及嵌套的 $and、$or、$not。成本规划器采样评估过滤选择率，选择精确搜索或 HNSW，并调整搜索工作量。

• 并行原子插入

  批量插入使用全部核心构建索引。只要有一个向量无效，就不会写入任何数据。

• Upsert、删除与压实

  按 ID 替换或删除记录，再通过压实重建集合，移除已删除的记录。

• 内省 API

  stats()、explain() 和 estimate_recall() 是 API 的组成部分，无需独立工具。

• Python 绑定

  面向 CPython 3.11 及以上版本的 PyO3 wheel，附带类型提示。

• 命令行工具

  init、create-collection、insert、query、inspect、recall、checkpoint 和 compact。

• 稳定的格式 2

  提供版本化文件、校验和与基准样本兼容性测试，同时仍可读取现有的格式 1 快照。

• WAL 与检查点

  save() 将变更页提交到 WAL；checkpoint() 写出独立完整的快照。恢复时会忽略末尾因中断而不完整的记录。

• 可选 int8

  按集合使用 int8 编码，每个向量有独立的缩放系数。可用自己的数据测量召回率，选择存储与精度之间的平衡。

• 原生 Node.js 绑定

  提供 Node-API 8、TypeScript 类型定义，以及在工作线程运行的 searchAsync。GitHub 发布版本中包含 Linux x64、macOS arm64 和 Windows x64 构建。

1. 已支持

   0.2.0

   • 稳定文件格式与兼容性测试
   • WAL 与增量磁盘写入
   • 可选 int8 向量存储
   • AND / OR / NOT 元数据过滤
2. 下一步

   后续改进

   • 降低保存时完整镜像的编码开销
   • 自动检查点
   • npm 平台包与加载器
3. v0 暂无计划

   不在范围内

   • 服务器模式
   • 分片与复制
   • GPU 加速
   • 云服务

数据库仍需完整装入内存。WAL 减少磁盘写入，但 save() 仍会编码并比较完整镜像。检查点需显式执行；并发写入会串行化，状态过期的写入方必须重新打开数据库。