Vectra 实战：纯 JS 本地向量搜索引擎

ZengLiangYi
0 阅读5分钟

本文面向：想在 Node.js 项目中实现本地语义搜索的开发者。
预计阅读时间：12 分钟
最终效果：掌握 vectra 的索引创建、向量插入、查询、删除、事务模式的完整用法，理解 ChatCrystal 的候选集升级和双写策略。

想在 Node.js 项目里加语义搜索，但不想装 Python、不想跑 Docker、不想申请云服务 API Key？vectra 就是为这个场景设计的——一个纯 JavaScript 实现的本地向量搜索引擎，零原生依赖，数据全部存在本地文件里。

这篇文章从零开始，带你用 vectra 完成向量索引的创建、插入、查询、删除全流程，所有代码来自 ChatCrystal 的生产级实现。

vectra 是什么

vectra 是 Steve Bilig 开发的轻量级向量数据库，核心特点：

  • 纯 JS。没有任何 C++ 原生模块，npm install 即可，不需要编译
  • 文件存储。索引数据存在本地文件系统，不依赖 SQLite 或外部服务
  • TypeScript 原生。类型定义完整，IDE 补全友好
  • HNSW 算法。基于 Hierarchical Navigable Small World 算法做近似最近邻搜索，查询速度快

vectra 不是为大规模生产环境设计的（百万级以上向量应该用 Qdrant 或 Pinecone），但它非常适合本地工具、CLI 应用、Electron 桌面软件这类场景。ChatCrystal 用它存储所有笔记的 embedding 向量，支撑语义搜索功能。

为什么选 vectra

选型时考虑过几个方案：

方案问题
chroma需要 Python 运行时，Node.js 项目集成成本高
hnswlib-node有 C++ 原生依赖，跨平台编译容易出问题
自己实现HNSW 算法复杂度高，不适合项目初期
vectra纯 JS、零配置、文件存储、API 简洁

vectra 的优势在于零摩擦：npm install vectra 装完就能用，不需要配置数据库连接、不需要启动额外进程、不需要处理原生模块编译失败的问题。对于 Electron 桌面应用这种需要跨平台分发的场景，这一点尤其重要。

安装和初始化

npm install vectra

创建索引实例：

import { LocalIndex } from 'vectra';
import { resolve } from 'node:path';

const INDEX_PATH = resolve('./data', 'vectra-index');
const index = new LocalIndex(INDEX_PATH);

LocalIndex 构造函数只接收一个路径参数，不创建任何文件。需要显式调用 createIndex() 初始化：

if (!(await index.isIndexCreated())) {
  await index.createIndex();
}

isIndexCreated() 检查路径下是否已有索引文件。这个模式适合应用启动时调用——首次运行创建索引，后续运行直接复用。

ChatCrystal 用单例模式管理索引实例，避免重复创建：

// server/src/services/vector-index.ts
const INDEX_PATH = resolve(appConfig.dataDir, 'vectra-index');
let _index: LocalIndex | null = null;

export async function getIndex(): Promise<LocalIndex> {
  if (_index) return _index;
  _index = new LocalIndex(INDEX_PATH);
  if (!(await _index.isIndexCreated())) {
    await _index.createIndex();
  }
  return _index;
}

插入向量

向 vectra 插入数据需要两样东西：向量（浮点数组）和元数据（任意 JSON 对象）。

先拿到一个向量。实际项目中会调用 Embedding 模型，这里用随机向量演示：

// 模拟一个 768 维的 embedding 向量
const vector = Array.from({ length: 768 }, () => Math.random() * 2 - 1);

const item = await index.insertItem({
  vector,
  metadata: {
    noteId: 42,
    chunkIndex: 0,
    title: 'SQLite WAL 模式并发写入问题',
    projectName: 'my-project',
  },
});

console.log(item.id); // vectra 自动生成的唯一 ID

insertItem 返回的对象包含 id 字段，这是 vectra 分配的内部标识符。后续删除、查询都会用到它。ChatCrystal 把这个 id 存到 SQLite 的 embeddings 表中，建立 vectra 向量和业务数据之间的关联。

在 ChatCrystal 的实际代码中，一条笔记会被切分成多个 chunk，每个 chunk 独立生成向量并插入：

// server/src/services/embedding.ts
const item = await index.insertItem({
  vector: chunk.vector,
  metadata: {
    noteId: id,
    chunkIndex: chunk.chunkIndex,
    conversationId,
    title,
    projectName,
  } as NoteChunkMeta,
});

// 保存 vectra ID 到 SQLite，建立关联
newItems.push({
  chunkIndex: chunk.chunkIndex,
  chunkText: chunk.chunkText,
  vectraId: item.id,
});

metadata 里的字段完全自定义。vectra 不关心你放什么进去，它只负责存储和返回。但 metadata 在查询时可以用来做过滤，所以合理设计 metadata 结构很重要。

查询向量

查询是 vectra 最核心的功能。给一个查询向量，它返回余弦相似度最高的 top-K 结果：

const queryVector = Array.from({ length: 768 }, () => Math.random() * 2 - 1);
const results = await index.queryItems(queryVector, '查询文本', 10);

for (const result of results) {
  console.log(`笔记: ${result.item.metadata.title}`);
  console.log(`相似度: ${result.score}`);
  console.log(`chunk: ${result.item.metadata.chunkIndex}`);
}

queryItems 的三个参数：

  1. queryVector — 查询向量（浮点数组）
  2. queryText — 查询文本（vectra 内部用于辅助，传空字符串也行）
  3. topK — 返回结果数量

返回的每个 result 包含 item（含 metadata）和 score（相似度分数，0-1 之间，越大越相似）。

ChatCrystal 在实际搜索中加入了候选集升级机制——因为一个笔记可能有多个 chunk，直接取 top-10 可能返回的 10 个 chunk 全来自同一条笔记。所以先取小批量，不够就翻倍：

let candidateK = requestedTopK;
let directResults: DirectSearchHit[] = [];

while (candidateK > 0) {
  const results = await index.queryItems<NoteChunkMeta>(embedding, query, candidateK);
  directResults = await materializeDirectSearchHits(db, results);

  if (directResults.length >= requestedTopK || results.length < candidateK) break;

  // 翻倍候选集，但不超过索引总条数
  const nextCandidateK = candidateLimit === undefined
    ? candidateK * 2
    : Math.min(candidateK * 2, candidateLimit);
  if (nextCandidateK <= candidateK) break;
  candidateK = nextCandidateK;
}

materializeDirectSearchHits 从 SQLite 读取 chunk 原文，按 noteId 去重保留最高分。这样即使 vectra 返回了同一笔记的 5 个 chunk，最终结果里也只出现一条。

按 metadata 过滤

vectra 支持按 metadata 字段过滤查询结果。比如只搜索某个项目的笔记：

// 获取指定笔记的所有 chunk
const items = await index.listItemsByMetadata({ noteId: 42 });

listItemsByMetadata 接收一个 metadata 对象，返回所有字段完全匹配的条目。ChatCrystal 用它来做两件事：

删除前查找：先找到某条笔记在 vectra 中的所有 chunk ID，然后逐个删除：

// server/src/services/vector-index.ts
export async function committedVectraIdsForNote(index: LocalIndex, noteId: number): Promise<string[]> {
  const items = await index.listItemsByMetadata({ noteId });
  return items.map((item) => item.id);
}

存在性检查：确认 vectra 中的向量是否和 SQLite 记录一致：

export async function currentVectraIdsCommitted(index: LocalIndex, vectraIds: string[]): Promise<boolean> {
  if (vectraIds.length === 0) return false;

  for (const vectraId of vectraIds) {
    if (!(await index.getItem(vectraId))) {
      return false;
    }
  }
  return true;
}

getItem(vectraId) 按 ID 获取单个条目，如果不存在返回 undefined。

需要注意的是，vectra 的 listItemsByMetadata 是精确匹配，不支持范围查询或模糊匹配。如果你需要复杂的过滤逻辑，应该在 vectra 查询之后用业务代码二次过滤。

删除向量

删除单个向量：

await index.deleteItem(vectraId);

ChatCrystal 在更新笔记的 embedding 时，会先删除旧向量再插入新向量：

// 找到旧向量
const oldVectraIds = await committedVectraIdsForNote(index, noteId);

// 插入新向量后，删除旧的
for (const vectraId of oldVectraIds) {
  await index.deleteItem(vectraId);
}

如果要清空整个索引重建，可以直接删除索引目录：

import { existsSync, rmSync } from 'node:fs';

export function clearEmbeddingIndex(): void {
  _index = null;  // 清空内存缓存
  if (existsSync(INDEX_PATH)) {
    rmSync(INDEX_PATH, { recursive: true, force: true });
  }
  // 下次 getIndex() 调用会自动重建空索引
}

事务模式：beginUpdate / endUpdate

这是 vectra 最重要的设计模式。单个 insertItem 或 deleteItem 调用会立即写入磁盘，但如果你要批量操作，每次都写盘会很慢。vectra 提供了事务式的批量写入：

await index.beginUpdate();

// 批量插入/删除，不会立即写盘
await index.insertItem({ vector: v1, metadata: { ... } });
await index.insertItem({ vector: v2, metadata: { ... } });
await index.deleteItem(oldId);

await index.endUpdate(); // 这时候才一次性写入磁盘

如果中途出错，可以用 cancelUpdate() 回滚：

let updateOpen = false;
try {
  await index.beginUpdate();
  updateOpen = true;
  // ... 写入操作 ...
  await index.endUpdate();
  updateOpen = false;
} catch (error) {
  if (updateOpen) {
    try {
      index.cancelUpdate(); // 丢弃未提交的变更
    } catch {
      // 忽略取消失败，优先抛出原始错误
    }
  }
  throw error;
}

ChatCrystal 在所有批量写入的地方都用了这个模式。updateOpen 标志位确保 cancelUpdate 只在事务确实开启的情况下才调用，避免二次异常。

实际代码（删除某笔记的所有向量）：

// server/src/services/vector-index.ts
export async function deleteVectraItemsForNote(index: LocalIndex, noteId: number): Promise<number> {
  const vectraIds = await committedVectraIdsForNote(index, noteId);
  if (vectraIds.length === 0) return 0;

  let updateOpen = false;
  try {
    await index.beginUpdate();
    updateOpen = true;

    for (const vectraId of vectraIds) {
      await index.deleteItem(vectraId);
    }

    await index.endUpdate();
    updateOpen = false;
    return vectraIds.length;
  } catch (error) {
    if (updateOpen) {
      try {
        index.cancelUpdate();
      } catch {
        // Ignore cancel failures
      }
    }
    throw error;
  }
}

索引统计

获取索引中的向量总数：

const stats = await index.getIndexStats();
console.log(`索引中有 ${stats.items} 个向量`);

ChatCrystal 用这个数字来决定查询时的候选集大小——如果索引里只有 5 个向量，就没必要请求 top-100。

文件存储结构

vectra 的索引存储在你指定的目录下。ChatCrystal 的路径是 {dataDir}/vectra-index/：

~/.chatcrystal/data/vectra-index/
├── items/          # 向量数据文件
├── index.json      # 索引元信息
└── ...

因为是纯文件存储，备份只需要复制整个目录，迁移也只需要把目录搬到新位置。不需要 pg_dump、不需要 mysqldump，cp -r 搞定。

这个特性对 Electron 桌面应用特别友好：用户卸载重装后，只要数据目录还在，索引就还在。

vectra vs chroma vs hnswlib

维度vectrachromahnswlib-node
语言纯 JS/TSPythonC++ binding
原生依赖无有有
安装难度npm installpip install + server需要编译环境
运行方式进程内嵌入独立服务进程内嵌入
存储方式文件系统SQLite / 文件文件
适合场景Node.js 本地工具Python 应用、服务端需要极致性能
元数据过滤精确匹配丰富过滤表达式无内置支持
最大规模万级十万级百万级

vectra 的定位很清晰：Node.js 生态里的轻量级本地向量存储。如果你的项目是 Python 技术栈，chroma 更合适。如果你需要处理百万级向量，应该上 Qdrant 或 Pinecone。但如果你是 Node.js 开发者，想要一个零配置的本地语义搜索能力，vectra 是目前最好的选择。

下一步

项目地址：github.com/ZengLiangYi…

avatar
文章
阅读
粉丝