AgentbaseDocs
文档目录

检索与溯源

这是什么 / 何时用

检索与溯源模块覆盖知识库的数据面查询闭环:单库检索(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)。

前置

使用骨架

关键参数与返回

检索请求参数(createSearch / createMultiSearch)

参数适用方法类型必填默认值 / 约束说明
knowledgeBaseIdcreateSearchstring是非空字符串目标单库 ID(如 kb_enterprise_support)。
knowledgeBaseIdscreateMultiSearchstring[]是1–10 个不重复 ID跨库检索的目标知识库 ID 列表。
query两者string是非空查询文本用户自然语言问题或检索关键词。
searchMode两者string否默认 hybrid;枚举:vector / fulltext / hybrid检索模式(**严禁误写为 mode**)。
limit两者integer否默认 10(范围 1–100)返回的最大切片数(全局 TopK)。
offsetcreateMultiSearchinteger否默认 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否{subProductId}_{sectionCode}_{fileKey}2.10.0 新增:按文档定位标识精确匹配;首段仅字母或数字,第二段仅数字,两段可为空;末段必须是 32 位十六进制。
subProductId两者string否1–64 位字母或数字2.10.0 新增:按子产品标识过滤(与 documentTag 为 AND 关系)。
metadataFilter两者object否JSON 过滤对象单库传 logic 与 conditions(每项含 name / comparison / value);跨库按库 ID 分键,"*" 兜底未单独配置的库。
useKnowledgeGraphcreateSearchboolean否默认 false是否联合召回 GraphRAG 实体、关系与社区报告上下文。
useWikicreateSearchboolean否默认 false是否联合召回已发布的 LLM Wiki 页面切片。
allowDegradedcreateSearchboolean否默认 true控制增强检索的可降级错误,状态见 capabilities / degradedCapabilities;不控制重排模型失败。
answercreateSearchboolean否默认 false2.9.0 新增:是否对召回的 Top 证据(最多 12 条)调用 Chat 模型生成接地回答(≤1024 tokens)。

检索返回结构

单库返回 KnowledgeBaseSearchResultList,跨库返回 KnowledgeBaseMultiSearchResultList。不要将单库增强参数或响应字段直接套用于跨库调用。

字段适用方法说明
total两者本次返回的结果数。
results两者结果数组;单项使用 $id、sourceId、content、score、source、locator、metadata。跨库单项另有 knowledgeBaseId,标识结果所属库。
reranked两者是否成功完成重排;自动选模失败回退时为 false。
resolvedVersionIdcreateSearch本次解析的知识库版本;旧读取路径为 null。
capabilitiescreateSearchRAPTOR / GraphRAG / Wiki 状态、结果代、耗时及脱敏错误。
degradedCapabilitiescreateSearch明确发生降级的增强能力。
answercreateSearch请求 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 中的来源。

错误与边界

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 面无检索能力。

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)

溯源与读原文

命中 chunk 自带 content、source(受保护原文 URI)与 locator(章节 / 文本偏移);getDocumentSource 读回原始文件(二进制流,支持 Range 分段返回 206),只需 knowledgebases.read、不另需 files.read。Web 面无此能力。

// 命中 chunk 的 sourceId 即原文档 ID;读回原文做人工核对或归档
const raw = await kb.getDocumentSource({ knowledgeBaseId: base.$id, documentId: '<documentId>' });

高级检索(标签过滤、答案合成与跨库元数据过滤)

示例中的 ob / aigw 与文档定位标识需替换为实际文档的值;subProductId 不接受连字符、下划线或空格,documentTag 不能填标题或层级标签。

单库支持 answer: true 接地答案合成、documentTag / subProductId 文档范围过滤,以及 createMultiSearch 的分库 metadataFilter 与 offset 分页。

// 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' }] },
    },
});

示例指引

事实源

本次契约核对来源