VectorSearch：有边界的精确余弦检索
给定同一个向量空间，先过滤文档，再按余弦相似度排序。
构造 VectorSearchSpace 必须提供 identity 和 dimensions（1—16384）。upsert({document,vector}) 复制文档并归一化向量；拒绝维数不符、非有限数和零向量。search({vector,limit,filter,minScore?,groupBy?}) 返回 SearchHit[]。filter/groupBy 同步，limit 为 1—1000，minScore 若给出须在 [-1,1]。
配置 groupBy 时每组只取最高分，等分时以 id 选择；最终按分数降序和 id 排序。remove/clear 只改变当前内存索引。它不生成 embedding、不查数据库，也不混合不同模型/维数的向量；空间版本、授权、索引规模和持久化由 App 决定。
由简到繁的同业务示例
先在同一空间检索说明片段
入门 · Node.js
二维向量用于展示合同；不代表真实文本 embedding 或检索质量。
ts
import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch<{ id: string; text: string }>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));js
import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));相同 search 增加权限、阈值和文档分组
配置 · Node.js
ts
import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
type Chunk = { id: string; documentId: string; audience: string; text: string };
const index = new VectorSearch<Chunk>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));js
import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));