跳转到内容

知识库

@aidy-dev/knowledge 是 aidy 的知识索引。它把 Markdown 文档按集合(collection)存储,按标题切块,用 BM25 检索(提供嵌入函数时再加上向量检索)。它运行在 @aidy-dev/sql 的任意 SqlDriver 上:Postgres、SQLite 或 Cloudflare D1。接入 aidy 后,它就是一个名为 knowledge 的搜索源。

终端窗口
npm install @aidy-dev/knowledge @aidy-dev/sql
import { createKnowledge } from '@aidy-dev/knowledge';
import { postgresDriver } from '@aidy-dev/sql/postgres';
const knowledge = createKnowledge({ driver: postgresDriver(process.env.DATABASE_URL!) });
await knowledge.migrate(); // creates aidy_knowledge_* tables
驱动 导入 说明
Postgres postgresDriver(url) from @aidy-dev/sql/postgres 需要 postgres 包(v4)。用 ts_rank 排序。
SQLite sqliteDriver(path) from @aidy-dev/sql/sqlite 使用 Node 内置的 node:sqlite。FTS5 + BM25。
D1 d1Driver(env.DB) from @aidy-dev/sql/d1 Cloudflare Workers。FTS5 + BM25。

索引可以与 aidy 的存储共用一个数据库,它的表有独立的前缀。

ingest(collection, documents) 新增或替换文档,返回 { updated, unchanged }。

import { glob, readFile } from 'node:fs/promises';
const documents = [];
for await (const file of glob('docs/**/*.md')) {
const markdown = await readFile(file, 'utf8');
const slug = file.replace(/^docs\//, '').replace(/\.md$/, '');
documents.push({
id: slug,
title: markdown.match(/^# (.+)$/m)?.[1] ?? slug,
url: `/help/${slug}`,
markdown,
});
}
const { updated, unchanged } = await knowledge.ingest('docs', documents);
  • 文档的结构是 { id, title, url, markdown, updatedAt? }。url 是产品内路径或绝对 http(s) URL。
  • 内容哈希未变的文档会被跳过。有变化的文档会替换其分块,而文本没变的分块保留原有嵌入,所以每次部署全量重新导入的开销很小。
  • remove(collection, ids) 删除文档及其分块。源中已删除的文档要同步删除。

可以在 CI 构建文档之后执行导入,也可以放在应用的后台任务中。

没有嵌入时词法检索照常可用。提供嵌入函数后,向量得分会与词法排名融合:

import OpenAI from 'openai';
const openai = new OpenAI();
const knowledge = createKnowledge({
driver,
embed: async (texts) =>
(await openai.embeddings.create({ model: 'text-embedding-3-small', input: texts })).data.map((d) => d.embedding),
dimensions: 1536,
});

embed 返回的每个向量都会按 dimensions 检查维度。任何服务商都可以,包括 DashScope 这类 OpenAI 兼容端点。

source() 把索引变成一个 SearchSource。collections 按用户决定其可搜索的集合:

const aidy = createAidy({
// ...
sources: [
knowledge.source({
collections: (identity) => ['docs', `manuals/${identity.tenant}`],
}),
],
});

这个函数接收调用者的身份,因此租户私有的手册只对本租户可见。搜索源名称默认为 knowledge,可以通过 name 修改。

之后,凡是有搜索的地方都会出现知识库结果:⌘K 面板、智能体的 search 工具、MCP 的 search 工具和 aidy search。它们与产品自身的搜索操作通过倒数排名融合(RRF)合并。详见搜索。

使用 aidy-server 时,不需要写代码,设置 AIDY_KNOWLEDGE_DIR 和 AIDY_KNOWLEDGE_BASE_URL 即可。服务启动时把该目录下所有 .md 和 .mdx 文件导入 docs 集合(与 aidy 使用同一个数据库),并对所有用户开放搜索。文档的 URL 是基础 URL 加上去掉扩展名的路径(index 对应其所在目录),标题取 frontmatter 中的 title,没有时取第一个标题。

智能体基于搜索结果回答时,运行会发出 aidy.citation 事件,内容为 {messageId, citations: [{n, hit}]}:每个被引用的结果都放在消息中写作 [n] 的编号 n 下。@aidy-dev/react 把它们渲染为消息下方的来源列表;自建界面可以从 useThread(...).state.citations 按消息 id 读取。结果的 url 指向分块所在的小节:文档 URL 加上该标题的锚点。

要固定锚点,可以在标题上显式写 id,它会从标题文字中去掉:

## Rotate keys {#rotate}

没写时,锚点是标题的 GitHub 风格 slug。

  • 分块。 Markdown 按 h1–h3 标题切分。超过约 800 token 的小节(每个 CJK 字符计 1 个,其他字符每 4 个计 1 个)先按段落、再按句子切开。分块标题为 文档标题 › 标题路径。
  • 词法。 SQLite 和 D1 使用 FTS5(unicode61),按 bm25() 排序。Postgres 使用 simple 配置的 tsvector,按 ts_rank 排序。连续的 CJK 文本以重叠二元组(bigram)建索引,中文查询无需分词器也能命中。查询词之间是 OR 关系。
  • 向量。 在 JavaScript 中对词法前 200 条结果以及所搜集合中最新的 20,000 个分块计算余弦相似度,再与词法排名融合(k = 60)。
  • 摘要 最多 300 个字符,取匹配最密集的位置,匹配词用 «…» 包裹,供人阅读。
  • 正文。 每条结果还以 content 携带分块正文,最多 4000 个字符。只有模型通过 search 工具和 MCP 读取它;搜索面板和引用显示的是摘要。

也可以直接查询索引:

const hits = await knowledge.search('rotate certificates', { collections: ['docs'], limit: 5 });
  • 向量检索每次查询读取所搜集合的全部嵌入,上限 20,000 个分块;超出部分中较旧的分块只能被词法检索命中。1,536 维时,达到上限的单次查询要读取几百 MB。请让带嵌入的集合远低于这个上限,或每次少搜几个集合。不使用 pgvector。
  • 在 D1 上,只有单条语句是原子的。导入中途失败的文档可能没有分块,重新导入即可修复。
  • Postgres 用 ts_rank 排序,接近 BM25 但并不相同。
  • search 最多返回 50 条结果。