检索与溯源
这是什么 / 何时用
检索与溯源模块覆盖知识库的数据面查询闭环:单库检索(createSearch)、跨库联合检索(createMultiSearch,一次查询横跨 1–10 个知识库并经 RRF 融合与全局重排返回 TopK)、接地答案合成(answer: true)、增强索引协同召回(GraphRAG 图谱上下文与 LLM Wiki 页面联合检索),以及命中切片(chunk)的受保护原文下载(getDocumentSource,支持 HTTP Range 分段读取 206 Partial Content)。
在企业智能客服与技术支持场景(如演示项目 enterprise-ai-hub-210 下的知识库 kb_enterprise_support)中,服务端应用或智能体运行时通过本模块执行 hybrid(向量 + 全文)混合检索:若知识库已绑定启用词库(如 lex_enterprise_synonyms),服务端会在召回前自动对 query 执行同义词与扩展词改写,经 text-embedding-v3 向量召回与全文检索融合后,再调用 qwen3.7-text-rerank 重排并定位到原文档章节偏移(locator)。
前置
客户端初始化与认证:仅服务端与管理面可用,需初始化 Server SDK
Client(setEndpoint、setProject、setKey),API Key 至少具备knowledgebases.readscope(下载原文getDocumentSource同样只需knowledgebases.read,无需额外申请files.read)。文档与索引状态:目标知识库内至少存在
status=ready且activeGeneration已激活的文档;若启用useKnowledgeGraph或useWiki,对应能力须已在知识库索引治理中开启且存在已发布的成功构建产物(见 wiki.md)。模型网关就绪:Embedding 模型与可选 Rerank 模型(如
qwen3.7-text-rerank)、答案合成 Chat 模型(如qwen-plus)所属的 LLM Gateway Provider 处于激活可用状态。
使用骨架
初始化客户端与服务:使用
setEndpoint('https://appbuild-sit.oceanbase.com/v1')、setProject('enterprise-ai-hub-210')、setKey('<APPBASE_API_KEY>')构造Client,实例化KnowledgeBases(client)。单库混合检索(
createSearch):传入knowledgeBaseId、query、searchMode: 'hybrid'(注意参数名为searchMode,不可写为mode)、limit、similarityThreshold、vectorWeight与rerank: true。按需附加documentTag、subProductId收窄文档范围,或传入answer: true获取基于命中切片合成的接地答案。跨库联合检索(
createMultiSearch):传入knowledgeBaseIds(1–10 个不重复的知识库 ID 数组)、query、searchMode、limit、offset以及按库分键的metadataFilter(特定库 ID 的配置覆盖"*"兜底;二者不合并)。服务端先从各库召回候选集并执行 RRF(Reciprocal Rank Fusion)融合,启用重排时再对合并池执行一次全局 Rerank。解析命中结果与溯源读原文(
getDocumentSource):遍历响应results[]中的切片(含content、score、sourceId、source、locator),普通文档切片以sourceId作为documentId调用getDocumentSource获取原始文件二进制字节流(支持Range头分段下载),用于前端引用预览或合规审计归档。
关键参数与返回
检索请求参数(createSearch / createMultiSearch)
| 参数 | 适用方法 | 类型 | 必填 | 默认值 / 约束 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | createSearch | string | 是 | 非空字符串 | 目标单库 ID(如 kb_enterprise_support)。 |
knowledgeBaseIds | createMultiSearch | string[] | 是 | 1–10 个不重复 ID | 跨库检索的目标知识库 ID 列表。 |
query | 两者 | string | 是 | 非空查询文本 | 用户自然语言问题或检索关键词。 |
searchMode | 两者 | string | 否 | 默认 hybrid;枚举:vector / fulltext / hybrid | 检索模式(严禁误写为 mode)。 |
limit | 两者 | integer | 否 | 默认 10(范围 1–100) | 返回的最大切片数(全局 TopK)。 |
offset | createMultiSearch | integer | 否 | 默认 0(0–5000) | 跨库融合排序后的分页偏移量。 |
recallLimit | 两者 | integer | 否 | 启用重排时默认 min(100, max(limit * 4, 20));显式 1–100 且不小于 limit | 重排前的初始候选召回上限。 |
similarityThreshold | 两者 | number | 否 | 0–1(默认取 KB retrievalDefaults) | 作用于向量与 hybrid 的向量召回分支,不过滤全文分支。 |
vectorWeight | 两者 | number | 否 | 0–1(常见 0.7) | hybrid 模式下向量得分权重,全文权重为 1 - vectorWeight。 |
rerank | 两者 | boolean | 否 | 默认 false | 是否经 LLM Gateway 执行重排序。 |
rerankModel | 两者 | string | 否 | 如 qwen3.7-text-rerank | 显式指定重排模型;不传且 rerank=true 时由平台自动选择。 |
rerankProviderRef | 两者 | string | 否 | project:<id> / trial:<id> | 钉定重排模型的 Provider 引用。 |
documentTag | 两者 | string | 否 | 逗号分隔的标签 | 服务端 2.12.0 支持多个非空标签的任一匹配,以及对结构化和自由格式标签按下划线分段前缀筛选;避免全下划线过滤值;SDK 字段可用性以所用版本为准。 |
subProductId | 两者 | string | 否 | 1–64 位字母或数字 | 2.10.0 新增:按子产品标识过滤(与 documentTag 为 AND 关系)。 |
metadataFilter | 两者 | object | 否 | JSON 过滤对象 | 单库传 logic 与 conditions(每项含 name / comparison / value);跨库按库 ID 分键,"*" 兜底未单独配置的库。 |
useKnowledgeGraph | createSearch | boolean | 否 | 默认 false | 是否联合召回 GraphRAG 实体、关系与社区报告上下文。 |
useWiki | createSearch | boolean | 否 | 默认 false | 是否联合召回已发布的 LLM Wiki 页面切片。 |
allowDegraded | createSearch | boolean | 否 | 默认 true | 控制增强检索的可降级错误,状态见 capabilities / degradedCapabilities;不控制重排模型失败。 |
answer | createSearch | boolean | 否 | 默认 false | 2.9.0 新增:是否对召回的 Top 证据(最多 12 条)调用 Chat 模型生成接地回答(≤1024 tokens)。 |
检索返回结构
单库返回 KnowledgeBaseSearchResultList,跨库返回 KnowledgeBaseMultiSearchResultList。不要将单库增强参数或响应字段直接套用于跨库调用。
| 字段 | 适用方法 | 说明 |
|---|---|---|
total | 两者 | 本次返回的结果数。 |
results | 两者 | 结果数组;单项使用 $id、sourceId、content、score、source、locator、metadata。跨库单项另有 knowledgeBaseId,标识结果所属库。 |
reranked | 两者 | 是否成功完成重排;自动选模失败回退时为 false。 |
resolvedVersionId | createSearch | 本次解析的知识库版本;旧读取路径为 null。 |
capabilities | createSearch | RAPTOR / GraphRAG / Wiki 状态、结果代、耗时及脱敏错误。 |
degradedCapabilities | createSearch | 明确发生降级的增强能力。 |
answer | createSearch | 请求 answer: true 时的 { status, text, model, latencyMs, error },否则为 null。 |
单库结果还通过 indexSource、resultType、resultGeneration 区分普通切片与增强结果。source 是来源描述对象,locator 是位置对象,字段以相应结果类型为准。
答案模型读取 indexingDefaults.chatModel / chatProviderRef。answer.status 为 not_configured(未配置模型)、no_evidence(无有效证据)、succeeded(生成文本)或 failed(调用异常或空文本)。答案成功仍需核对 results 中的来源。
错误与边界
参数名误用(
400 general_argument_invalid):将searchMode误传为mode,或createMultiSearch的knowledgeBaseIds超出 1–10 范围/包含重复库 ID。重排模型失败语义区分:显式传入
rerankModel或rerankProviderRef时,上游调用异常会返回错误;两者均未指定、仅启用rerank: true的自动重排可回退原排序并返回reranked: false。allowDegraded只控制单库增强检索的可降级错误。增强索引未就绪(
409/ 降级):若请求useKnowledgeGraph: true或useWiki: true且allowDegraded: false,当对应索引尚未构建完成时会返回冲突错误;生产环境建议保持allowDegraded: true并检查capabilities与degradedCapabilities。原文读取注意二进制处理:
getDocumentSource直接返回原始文件字节流(而非 JSON 包装),SDK 调用方应按ArrayBuffer/byte[]/bytes接收并落盘或流式转发,切勿调用JSON.parse()。
SDK 类别差异
| SDK 类别 | 支持范围 | 鉴权方式 | 典型场景 |
|---|---|---|---|
| Server SDK(Node.js / Java / Python / Go) | 全量支持 createSearch、createMultiSearch、getDocumentSource | 项目 API Key(knowledgebases.read) | 后端 RAG 服务、智能体工具检索、原文溯源下载 |
| Console SDK(Node.js / Java / Python / Go) | Java / Python / Go Console SDK 含完整 KnowledgeBases 检索面;JS Console SDK 经 client.call 调用 | 管理面 Session / 短期 JWT / API Key | 控制台检索测试台、自动化巡检与评测 |
| Client / Web SDK(Web) | 不支持知识库检索与原文下载(仅含语雀 OAuth 辅助方法) | 用户 Session | 浏览器端必须经由业务后端或 Function 代理调用检索接口 |
各语言调用示例
每个卡片可切换语言(全页同步)。
检索(单库 / 跨库)
createSearch 单库,createMultiSearch 跨 1–10 库(跨库先 RRF 合并再对合并池做一次 rerank);结果 chunk 带 content / source / locator。Web 面无检索能力。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const found = await kb.createSearch({
knowledgeBaseId: base.$id,
query: '退款政策是什么?',
searchMode: 'hybrid', // 参数名是 searchMode;vector / fulltext / hybrid
limit: 10,
rerank: true // 先扩大召回再经 Gateway 重排;自动选择失败降级并返回 reranked: false
});
// 跨库:kb.createMultiSearch({ knowledgeBaseIds: [...], query, limit })(1–10 库,全局 TopK)var found = kb.createSearch(base.getId(), "退款政策是什么?",
10L, // limit(注意:位于 searchMode 之前)
io.agentbase.enums.SearchMode.HYBRID, // vector / fulltext / hybrid
true, // rerank:先扩大召回再经 Gateway 重排;自动选择失败降级并返回 reranked: false
null, null, null, null, null); // recallLimit / rerankModel / rerankProviderRef / similarityThreshold / vectorWeight
// 跨库:kb.createMultiSearch(...)(1–10 库,全局 TopK)found = kb.create_search(
knowledge_base_id=base['$id'],
query='退款政策是什么?',
search_mode='hybrid', # 参数名是 search_mode;vector / fulltext / hybrid
limit=10,
rerank=True) # 先扩大召回再经 Gateway 重排;自动选择失败降级并返回 reranked: false
# 跨库:kb.create_multi_search(knowledge_base_ids=[...], query=..., limit=...)(1–10 库,全局 TopK)found, err := kb.CreateSearch(base.Id, "退款政策是什么?",
kb.WithCreateSearchSearchMode("hybrid"), // vector / fulltext / hybrid
kb.WithCreateSearchLimit(10),
kb.WithCreateSearchRerank(true)) // 自动选择失败降级并返回 reranked: false
// 跨库:kb.CreateMultiSearch(...)(1–10 库,全局 TopK)curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"query":"早餐机首次使用要注意什么","limit":5,"searchMode":"hybrid","similarityThreshold":0.5,"vectorWeight":0.7}'
# 跨库:POST /knowledgebases/search,body 加 "knowledgeBaseIds":["kb_a","kb_b"](1–10 库且不重复)溯源与读原文
命中 chunk 自带 content、source(受保护原文 URI)与 locator(章节 / 文本偏移);getDocumentSource 读回原始文件(二进制流,支持 Range 分段返回 206),只需 knowledgebases.read、不另需 files.read。Web 面无此能力。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 命中 chunk 的 sourceId 即原文档 ID;读回原文做人工核对或归档
const raw = await kb.getDocumentSource({ knowledgeBaseId: base.$id, documentId: '<documentId>' });byte[] raw = kb.getDocumentSource(base.getId(), "<documentId>"); // 二进制流,不要按 JSON 解析;只需 knowledgebases.readraw: bytes = kb.get_document_source(knowledge_base_id=base['$id'], document_id='<documentId>')
# 二进制流,不要按 JSON 解析;只需 knowledgebases.readraw, err := kb.GetDocumentSource(base.Id, "<documentId>") // *[]byte:原始文件二进制,不要按 JSON 解析curl -sS "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents/<documentId>/source" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-o source.bin # 二进制流,不要按 JSON 解析;带 Range 头时分段返回 206高级检索(标签过滤、答案合成与跨库元数据过滤)
示例中的 ob / aigw 与文档定位标识需替换为实际文档的值;subProductId 不接受连字符、下划线或空格,documentTag 可使用自由格式值;控制台的层级标签和定位值共同存放在文档的 documentTag 列表中。
单库支持 answer: true 接地答案合成、documentTag / subProductId 文档范围过滤,以及 createMultiSearch 的分库 metadataFilter 与 offset 分页。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
// 1. 单库高级检索:按 subProductId / documentTag 过滤 + GraphRAG/Wiki 增强 + 答案合成
const singleResult = await kb.createSearch({
knowledgeBaseId: 'kb_enterprise_support',
query: 'OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?',
searchMode: 'hybrid',
limit: 6,
similarityThreshold: 0.45,
vectorWeight: 0.7,
rerank: true,
rerankModel: 'qwen3.7-text-rerank',
subProductId: 'ob',
documentTag: 'ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d',
useKnowledgeGraph: true,
useWiki: true,
allowDegraded: true,
answer: true,
});
console.log('合成答案:', singleResult.answer?.text);
// 2. 跨库联合检索:按库指定 metadataFilter + offset 分页
const multiResult = await kb.createMultiSearch({
knowledgeBaseIds: ['kb_enterprise_support', 'kb_product_docs'],
query: 'AI 网关的工具接入与限流策略怎么配置?',
searchMode: 'hybrid',
limit: 10,
offset: 0,
rerank: true,
subProductId: 'aigw',
metadataFilter: {
'*': { logic: 'and', conditions: [{ name: 'env', comparison: 'is', value: 'production' }] },
kb_enterprise_support: { logic: 'and', conditions: [{ name: 'category', comparison: 'is', value: 'sop' }] },
},
});// Java Server SDK 通过 client.call 或带扩展参数的 createSearch 传递 documentTag / subProductId / answer;跨库 createMultiSearch 不支持 answer
java.util.Map<String, Object> searchBody = new java.util.HashMap<>();
searchBody.put("query", "OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?");
searchBody.put("searchMode", "hybrid");
searchBody.put("limit", 6);
searchBody.put("similarityThreshold", 0.45);
searchBody.put("vectorWeight", 0.7);
searchBody.put("rerank", true);
searchBody.put("rerankModel", "qwen3.7-text-rerank");
searchBody.put("subProductId", "ob");
searchBody.put("documentTag", "ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d");
searchBody.put("useKnowledgeGraph", true);
searchBody.put("useWiki", true);
searchBody.put("allowDegraded", true);
searchBody.put("answer", true);
// POST /knowledgebases/kb_enterprise_support/search# 单库检索:启用答案合成(answer=True)与文档标签过滤(sub_product_id / document_tag)
single_result = kb.create_search(
knowledge_base_id='kb_enterprise_support',
query='OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?',
search_mode='hybrid',
limit=6,
similarity_threshold=0.45,
vector_weight=0.7,
rerank=True,
rerank_model='qwen3.7-text-rerank',
sub_product_id='ob',
document_tag='ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d',
use_knowledge_graph=True,
use_wiki=True,
allow_degraded=True,
answer=True,
)
# 跨库联合检索:分库 metadata_filter + offset 分页
multi_result = kb.create_multi_search(
knowledge_base_ids=['kb_enterprise_support', 'kb_product_docs'],
query='AI 网关的工具接入与限流策略怎么配置?',
search_mode='hybrid',
limit=10,
offset=0,
rerank=True,
sub_product_id='aigw',
metadata_filter={
'*': {'logic': 'and', 'conditions': [{'name': 'env', 'comparison': 'is', 'value': 'production'}]},
'kb_enterprise_support': {'logic': 'and', 'conditions': [{'name': 'category', 'comparison': 'is', 'value': 'sop'}]},
},
)singleResult, err := kb.CreateSearch("kb_enterprise_support",
"OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?",
kb.WithCreateSearchSearchMode("hybrid"),
kb.WithCreateSearchLimit(6),
kb.WithCreateSearchSimilarityThreshold(0.45),
kb.WithCreateSearchVectorWeight(0.7),
kb.WithCreateSearchRerank(true),
kb.WithCreateSearchRerankModel("qwen3.7-text-rerank"),
kb.WithCreateSearchSubProductId("ob"),
kb.WithCreateSearchDocumentTag("ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d"),
kb.WithCreateSearchUseKnowledgeGraph(true),
kb.WithCreateSearchUseWiki(true),
kb.WithCreateSearchAllowDegraded(true),
kb.WithCreateSearchAnswer(true),
)
_ = singleResult
_ = err(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. 单库高级检索(带标签过滤、增强索引与答案合成)
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_enterprise_support/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{
"query": "OceanBase 分布式事务锁冲突与向量索引构建超时的排障步骤是什么?",
"searchMode": "hybrid",
"limit": 6,
"similarityThreshold": 0.45,
"vectorWeight": 0.7,
"rerank": true,
"rerankModel": "qwen3.7-text-rerank",
"subProductId": "ob",
"documentTag": "ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
"useKnowledgeGraph": true,
"useWiki": true,
"allowDegraded": true,
"answer": true
}'
# 2. 跨库联合检索(带 metadataFilter 与 offset 分页)
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/search" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{
"knowledgeBaseIds": ["kb_enterprise_support", "kb_product_docs"],
"query": "AI 网关的工具接入与限流策略怎么配置?",
"searchMode": "hybrid",
"limit": 10,
"offset": 0,
"rerank": true,
"subProductId": "aigw",
"metadataFilter": {
"*": {"logic": "and", "conditions": [{"name": "env", "comparison": "is", "value": "production"}]},
"kb_enterprise_support": {"logic": "and", "conditions": [{"name": "category", "comparison": "is", "value": "sop"}]}
}
}'
)示例指引
本文模型名、项目 ID 与查询内容为配置示例,仍需在自己的环境中完成真实模型调用验证。
JavaScript(Node.js 完整 RAG 摄取与检索链路):examples/javascript.md
Python(Server SDK 知识库检索与溯源脚本):examples/python.md
Java(Server / Console SDK 调用写法):examples/java.md
Go(Server SDK 检索与选项模式):examples/go.md