知识库
这是什么 / 何时用
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 接入增强结果。
前置
- 项目已配置可用的 LLM Gateway embedding 模型(可选 rerank / VLM):创建 KB 时按模型名精确匹配,Gateway 无此模型或 Provider 未激活则创建失败。
- API Key scopes:
knowledgebases.read(读/检索)、knowledgebases.write(写/摄取);浏览器用用户 Session,不持项目 API Key。 documentParser取值text/vlm/mineru(默认vlm;vlm必须配可用visionModel;旧值auto会被拒绝;MinerU 不可用时不要自动换解析器)。
使用骨架
create({ name, embeddingModel, ... })创建 KB——创建后 embeddingModel 不可改;探测失败即创建失败(换模型名或先激活 Provider)。2.9.0 起可选 **embeddingDimension(1–65535:对所选模型探测校验,与模型输出维度不符则创建失败)与tracingEnabled**(摄取追踪开关,记录解析 / 分块中间产物供解析评估使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据)。- 摄取文档:
createDocument+createIngestion({ documentId, ... })(或批量createDocumentsBatch);ingestion 状态机queued → running → ready | failed | cancelled,轮询getIngestion。parser 配置(parserId+parserConfig)决定切片方式,常用参数见下节。 - (可选)图片理解:在
imageUnderstanding配置enabled/model/providerRef/prompt/ 上限参数——这是解析后的独立步骤,为有信息量的图片生成描述并加入检索文本,但不修改原始 chunk 的 content/span/locator。 - 检索:
createSearch(单库)与createMultiSearch(多库),传query、searchMode(默认hybrid;**参数名是searchMode,不要用mode**)、limit、similarityThreshold、vectorWeight、rerank/rerankModel。2.9.0 起可传 **answer: true启用答案合成**:用知识库 indexingDefaults 的 chat 模型对合并证据做接地合成(最多 12 行证据、答案 ≤1024 tokens),结果带answer(状态 / 文本 / 模型 / 延迟)。 - 溯源:结果 chunk 带
content、source(原文 URI)与locator(章节/文本偏移);读原文getDocumentSource支持 Range/206,只需knowledgebases.read。 - 全量重建:
createReindex(返回 202,有界批量重摄取入口;不改变 embeddingModel)。 - (可选)增强索引:
updateIndexCapability配置并启用 GraphRAG / RAPTOR / Wiki →createIndexOperation异步构建 → 轮询 operation 终态;Wiki 页面 / 版本 / 提案 / 冲突与图谱浏览见 wiki.md。
关键参数与返回
parserId:general(默认)/title/smart/regex/faq/sheet(2.7.0 新增,Excel 专用,详见文档与摄取)。常用parserConfig:chunkTokenNum默认 512(摄取时必须 ≥1);overlapPercent默认 10(0–99,执行上限 90);titleLevel默认 2(1–6);minChunkTokens默认 128(不得大于chunkTokenNum);regexPattern默认[.!?]+\s*(PCRE)。imageUnderstanding:prompt≤4000 字符;maxImagesPerDocument默认 20(1–20);maxDescriptionChars默认 800(1–800);maxConcurrency默认 4(1–8)。- 检索:
limit默认 10(1–100);similarityThreshold0–1;vectorWeight常见 0.7(默认取 KB 的 retrievalDefaults);rerank=true时先扩大召回再经 Gateway rerank,rerankModel未指定时自动选择(显式指定的模型失败=硬报错;自动选择失败降级并返回reranked: false)。 - Document 级
parserConfig非空时整体替换 KB 默认(非逐字段合并);ingestion 的overrides.parserConfig再做浅合并。
错误与边界
- ingestion 返回 409:同文档已有进行中任务(单文档单任务并发控制),或 overrides 试图修改 embedding——等任务结束或取消,不要在 overrides 里改 embedding。
- 改 KB 的 parser 配置不会静默重写历史 chunk;只有新摄取或显式重摄取才会用新解析/图片描述。
- 检索空结果常见原因:文档未 ready、阈值过高、generation 未激活。
- 列表
total不完全套用queries[]过滤,不要当精确命中数用。 - 删除 KB 会异步拆除其绑定的向量库;不要手工删除 KB 占用的底层资源。
SDK 类别差异
- Server SDK(server-sdk/nodejs.md):全集——KB/Document/Chunk/Ingestion/DataSource/搜索(单库 + 多库)/语雀;2.7.0 起 Node / Python / Go / Java 还覆盖 Knowledge Index 与 Wiki 管理面(见 wiki.md)。
- 客户端 SDK(client-sdk/web.md):仅语雀 OAuth 会话相关方法(授权、列出文档、创建语雀文档、删除凭据);完整 RAG 流程放服务端,Wiki / GraphRAG / 索引治理也不进浏览器。
- Console SDK(console-sdk/nodejs.md):JS Console SDK(2.6.0)不含 Knowledge Bases 服务;Java Console SDK 有
KnowledgeBases服务(2.7.0 起 Java / Python / Go 的 console 包与 Server 面同构,含 Wiki / 索引治理)。 - Python Server SDK 15.4.0 补齐 Knowledge Bases surface(安装产物核验见 integration.md)。
各语言调用示例
创建知识库示例在本页;摄取与数据源见文档与摄取,检索与溯源见检索与溯源。每个卡片可切换语言(全页同步)。
创建知识库
建库为同步调用,配套 VectorsDB / Storage 资源在 provision 中异步就绪。Web(用户 Session)面无 KB 管理能力(仅语雀 OAuth 相关方法),故本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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 探测一次维度,之后不可改
});KnowledgeBases kb = new KnowledgeBases(client); // client 初始化见 server-sdk/java.md
var base = kb.create(ID.unique(), "产品手册", "text-embedding-v3",
null, null, null, null, null, null); // description / embeddingProviderRef / parserId / parserConfig / retrievalDefaults / ingestRoutes
// 创建时对 Gateway 探测一次维度,之后 embeddingModel 不可改from agentbase.id import ID
from agentbase.services.knowledge_bases import KnowledgeBases # 15.4.0 起补齐 KB 调用面
kb = KnowledgeBases(client)
base = kb.create(knowledge_base_id=ID.unique(), name='产品手册',
embedding_model='text-embedding-v3') # 创建时对 Gateway 探测一次维度,之后不可改kb := agentbase.NewKnowledgeBases(cl) // facade 构造器;cl 为已装载 API Key 的 Client
base, err := kb.Create(id.Unique(), "产品手册", "text-embedding-v3") // 创建时对 Gateway 探测一次维度,之后不可改
// 其余可选参数经 With* 选项:WithCreateDescription / WithCreateParserId / WithCreateParserConfig(interface{} 装载)等curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"knowledgeBaseId":"kb_product_docs","name":"产品文档库","embeddingModel":"text-embedding-v3"}'
# 201 返回 embeddingDimension 与自动开通的 vectorsdbDatabaseId / vectorsdbCollectionId / bucketId
# provision 异步:这些字段可能短暂为 null,稍后 GET /knowledgebases/{kbId} 确认示例指引
- JavaScript(Node 摄取与检索):examples/javascript.md
- Java(Server / Console SDK 调用写法):examples/java.md
事实源
skills/ob-agentbase/references/knowledge-bases.mdskills/ob-agentbase/references/release-2.6.0.md(富文档 RAG、Python 15.4.0)skills/ob-agentbase/references/release-2.7.0.md(Knowledge Index / Wiki / Excel sheet 为 2.7.0 能力增量)- appbase v2.9.0(tag v2.9.0,peeled
ebae9540…) - agentbase-sdks v2.9.0 specs(
packages/sdks/server-nodejs/src/services/knowledge-bases.ts方法面:create +embeddingDimension/tracingEnabled,search +answer)