AgentbaseDocs
文档目录

知识库

这是什么 / 何时用

Knowledge Bases 提供托管 RAG 管线:上传/导入文档 → 解析与切片 → Embedding → 入向量库 → 检索(vector / fulltext / hybrid,可选 rerank)。2.6.0 的富文档 RAG 支持 PDF(文本层 / 逐页 VLM / MinerU)、Office 文档(DOC/DOCX/PPT/PPTX 直接提取或转 PDF 后解析)、表格(CSV/TSV/XLS/XLSX 结构化提取)、图片资产与可选图片理解;Python Server SDK 15.4.0 补齐了 Knowledge Bases 的完整 surface。

资源模型:KB(创建时必填 embeddingModel,服务端对 LLM Gateway 做一次 embedding 探测自动得到维度,并自动创建配套的向量库与 Storage 资源)→ Document → generation(每次成功摄取产生一代,检索只返回活跃代)→ ingestion(异步任务)→ chunk(切片,检索的基本单元);数据源(datasource,当前为语雀)可同步文档进同一管线。

2.7.0 起在基础 RAG 之上新增增强索引:GraphRAG(实体图谱)、RAPTOR(摘要树)与 LLM Wiki(canonical Wiki 页面、版本、提案与冲突治理),以及配套的索引能力配置与异步构建操作——管理面与各语言调用见 Wiki 与 GraphRAG(索引治理);检索侧经 useKnowledgeGraph / useWiki / allowDegraded 接入增强结果。

2.10.0(对齐 release-2.10.2 基线)新增项目级词库(Lexicon)与知识库绑定:通过 /v1/lexicons 管理同义词(synonym)、关联扩展词(expansion)与停止词(stop)词条,并经 /v1/knowledgebases/{knowledgeBaseId}/lexicons 绑定到知识库。绑定启用后,单库与跨库检索会在进入向量/全文召回前基于 native-v1 分词策略自动完成同义词归一化与扩展词增补(无需重建文档向量);若在知识索引配置中开启 lexiconEnabled,GraphRAG 图谱构建还会复用所绑定的词库对抽取出的实体与关系端点做确定性标准名归一化。

前置

使用骨架

关键参数与返回

常见问题:知识库检索可以用 mode 吗?

不能。KnowledgeBases.createSearch 和 createMultiSearch 的检索模式字段名是 searchMode;mode 不能替代这个 SDK/API 请求字段。问“为什么要使用 searchMode”时,原因就是接口契约定义的参数名为 searchMode。

错误与边界

SDK 类别差异

各语言调用示例

创建知识库示例在本页;摄取与数据源见文档与摄取,检索与溯源见检索与溯源。每个卡片可切换语言(全页同步)。

创建知识库

建库为同步调用,配套 VectorsDB / Storage 资源在 provision 中异步就绪。Web(用户 Session)面无 KB 管理能力(仅语雀 OAuth 相关方法),故本卡不设 Web 页签。

import { KnowledgeBases, ID } from 'agentbase-node-sdk';

const kb = new KnowledgeBases(client);

const base = await kb.create({
    knowledgeBaseId: ID.unique(),        // 自定义或 ID.unique()
    name: '产品手册',
    embeddingModel: 'text-embedding-v3'  // 创建时对 Gateway 探测一次维度,之后不可改
});

词库(Lexicon)管理与知识库绑定

通过 /v1/lexicons 创建项目级词库、写入同义词/扩展词/停止词词条并预览 native-v1 查询改写结果,再通过 PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons 将词库绑定到知识库(如 kb_enterprise_support)。已发布 2.10.0 Server SDK 统一使用底层 client.call 或标准 REST 调用,本地 Console SDK 提供 Lexicons 服务封装。

import { Client } from 'agentbase-node-sdk';

// 已初始化的 Server Client(需具备 lexicons.read / lexicons.write 与 knowledgebases.write scope)
const endpoint = process.env.APPBASE_ENDPOINT!; // 例如 https://appbuild-sit.oceanbase.com/v1

// 1. 创建企业同义词词典
const lexicon = await client.call('post', new URL(`${endpoint}/lexicons`), {
    'content-type': 'application/json',
}, {
    lexiconId: 'lex_enterprise_synonyms',
    name: '企业核心产品同义词词典',
    description: '统一 OB / OceanBase / Agentbase 等标准术语',
    tokenizerProfile: 'native-v1',
});

// 2. 新增同义词词条(terms 首项为标准词,其余为同义词)
await client.call('post', new URL(`${endpoint}/lexicons/${lexicon.$id}/entries`), {
    'content-type': 'application/json',
}, {
    entryType: 'synonym',
    terms: ['OceanBase', 'OB', '分布式数据库OB'],
});

// 3. 预览查询改写效果
const preview = await client.call('post', new URL(`${endpoint}/lexicons/${lexicon.$id}/preview`), {
    'content-type': 'application/json',
}, {
    query: 'OB 向量索引怎么排障?',
});

// 4. 将词库绑定到知识库 kb_enterprise_support 并启用检索改写
const bindings = await client.call('put', new URL(`${endpoint}/knowledgebases/kb_enterprise_support/lexicons`), {
    'content-type': 'application/json',
}, {
    enabled: true,
    bindings: [
        { lexiconId: 'lex_enterprise_synonyms', priority: 1 },
        { lexiconId: 'lex_support_stopwords', priority: 2 },
    ],
});

示例指引

事实源