VectorSearch

KIT · class · 运行时值

Exact cosine search for a bounded embedded corpus. Identity and metadata are App-owned.

Vectors arrive as plain arrays and are stored normalized in Float32Array form, so query time only needs a dot product per candidate.

导入

TypeScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';

JavaScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/kits、@jangts/agent-core/kits/vector-search。

定义

class VectorSearch<Document>

泛型参数

类型参数	约束	默认类型
Document	{ id: string }	—

构造函数

new VectorSearch<Document extends { id: string; }>(space: VectorSearchSpace): VectorSearch<Document>

参数	类型	传递	说明
space	VectorSearchSpace	必需	—

space 的字段

字段	类型	必需	说明
identity	string	必需	只读。Non-blank space name, for example model@revision; reported back by VectorSearch.
dimensions	number	必需	只读。Expected vector length, 1..16384.

返回： VectorSearch<Document>。

实例属性

字段	类型	必需	说明
space	VectorSearchSpace	必需	只读。The declared space; compare it before mixing vectors from another source.

成员目录

成员	用途
upsert	Insert or replace one document and its embedding.
remove	Remove one document; returns whether it was present.
clear	Drop the whole corpus while keeping the declared space.
search	Score every candidate and return the best hits.

成员详情

upsert

实例方法。

Insert or replace one document and its embedding.

upsert({ document, vector }: { document: Document; vector: readonly number[]; }): void

Insert or replace one document and its embedding.

参数	类型	传递	说明
__0	{ document: Document; vector: readonly number[]; }	必需	—

__0 的字段

字段	类型	必需	说明
document	Document	必需	见类型定义及调用场景。
vector	readonly number[]	必需	见类型定义及调用场景。

返回： void。

remove

实例方法。

Remove one document; returns whether it was present.

remove(id: string): boolean

Remove one document; returns whether it was present.

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

clear

实例方法。

Drop the whole corpus while keeping the declared space.

clear(): void

Drop the whole corpus while keeping the declared space.

无调用参数。

返回： void。

search

实例方法。

Score every candidate and return the best hits.

search(options: VectorSearchQuery<Document> & { vector: readonly number[]; }): VectorSearchHit<Document>[]

Score every candidate and return the best hits.

参数	类型	传递	说明
options	VectorSearchQuery<Document> & { vector: readonly number[]; }	必需	—

options 的字段

字段	类型	必需	说明
limit	number	必需	只读。Maximum hits returned, 1..1000.
filter	(document: Readonly<Document>) => boolean	必需	只读。Synchronous predicate over a document snapshot; false excludes the candidate.
minScore	number | undefined	可省略	只读。Minimum cosine score in [-1, 1]; defaults to -1, which keeps every candidate.
groupBy	((document: Readonly<Document>) => string) | undefined	可省略	只读。Optional group key; only the best hit per group is kept, defaulting to the document id.
vector	readonly number[]	必需	见类型定义及调用场景。

返回： VectorSearchHit<Document>[]。

使用示例

• VectorSearch：有边界的精确余弦检索：给定同一个向量空间，先过滤文档，再按余弦相似度排序。

先在同一空间检索说明片段

入门 · Node.js

二维向量用于展示合同；不代表真实文本 embedding 或检索质量。

TypeScript

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 }));

JavaScript

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

TypeScript

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 }));

JavaScript

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 }));

相关策略源码

• 向量校验、归一化、过滤与分组排序

相关定义

• VectorSearchHit
• VectorSearchQuery
• VectorSearchSpace