api-vectorstore — 向量数据库契约

包名: @aalis/api-vectorstore
源码: packages/api-vectorstore/src/index.ts
实现: @aalis/plugin-vectorstore-flat, @aalis/plugin-vectorstore-lancedb

概述

最小化的向量数据库服务契约：存向量、查最近邻、按 metadata 过滤删除。常被 plugin-memory-vector 消费做语义历史检索。描述符 vectorstore 不给 bind，业务层就是 VectorStoreService 形状的活句柄（caps.vectorstore.use）。

关键类型

interface VectorSearchResult {
  score: number;
  metadata: Record<string, unknown>;
}

interface VectorStoreService {
  add(vector: number[], metadata: Record<string, unknown>): Promise<void>;
  search(queryVector: number[], topK: number): Promise<VectorSearchResult[]>;
  size(): Promise<number>;
  clear(): Promise<void>;
  deleteByFilter?(filter: Record<string, unknown>): Promise<number>;
  save(): Promise<void>;
}

典型用法

import { embedding } from '@aalis/api-embedding';
import { vectorstore } from '@aalis/api-vectorstore';
import { definePlugin } from '@aalis/core';

export default definePlugin({
  name: '@acme/plugin-example-vectorstore',
  uses: { embedding, vectorstore },
  apply({ embedding, vectorstore }) {
    if (!embedding.present || !vectorstore.present) return;
    const embedSvc = embedding.use;
    const vs = vectorstore.use;
    void (async () => {
      const vec = await embedSvc.embed('查询内容');
      const hits = await vs.search(vec, 5);
      for (const { score, metadata } of hits) {
        void score;
        void metadata;
      }
    })();
  },
});

维度一致性

向量维度由配套的 embedding 服务决定。vectorstore 实现不强校验维度——调用方应保证 embedding.use.embed() 与历史写入向量来自同一模型。

持久化

• flat —— 进程内 + 启动时全量加载 JSON / 关停时 save() 落盘
• lancedb —— LanceDB 列存，每次 add 即可见

实现者

• @aalis/plugin-vectorstore-flat — 简单 in-memory + 文件，适合小规模
• @aalis/plugin-vectorstore-lancedb — 适合大规模 / 多元数据过滤

相关

• 消费方：plugin-memory-vector
• 配套 embedding：api-embedding