AgentbaseDocs
文档目录

检索测试与问答调试(Search)

检索测试(Search) 是验证召回结果、调整检索策略并核对来源的 Console 页面。混合、向量和全文模式以及可用的重排、GraphRAG、Wiki 选项在该页操作;答案合成、定位标签过滤和跨库检索通过 API / SDK 接入。本文分别说明这些入口,不把 API 参数当作页面控件。


功能概述与核心场景

在企业级 RAG 系统中,仅仅完成文档分块与向量入库并不等于拥有高质量的问答体验。不同业务问题对检索策略有着截然不同的诉求:例如查询具体错误码(如 OB_ALLOCATE_MEMORY_FAILED 或工单号 TK-20261022-001)依赖精准的全文关键词匹配,而询问概念性排障思路(如“向量构建内存不够怎么调优”)则依赖高维语义向量匹配。

Agentbase 检索能力包括以下几类。其中第 3 项答案合成和第 4 项的显式过滤参数通过 API / SDK 接入,Console Search 没有对应输入控件:


核心概念与架构

多路混合检索、重排与答案合成流水线

flowchart TB
    Query["查询与可选文档过滤"] --> Recall["向量 / 全文 / 混合召回"]
    Recall --> Rerank{"启用 Rerank?"}
    Rerank -->|关闭| Ordinary["普通检索结果"]
    Rerank -->|开启| Model["自动选模或显式模型 / Provider"]
    Model -->|成功| Ordinary
    Model -->|自动选模失败| Fallback["保留原排序,reranked=false"] --> Ordinary
    Model -->|显式模型或 Provider 调用失败| Error["返回错误"]
    Ordinary --> Enhanced["单库按需加入 GraphRAG / RAPTOR / Wiki"]
    Enhanced -->|正常或允许可降级错误| Results["results / capabilities / degradedCapabilities"]
    Enhanced -->|严格模式或不可降级错误| Error
    Results --> Answer{"单库 API answer=true?"}
    Answer -->|否| Output["返回检索结果"]
    Answer -->|是| Synthesis["indexingDefaults 的 Chat 模型合成答案"] --> Output

allowDegraded 控制增强检索这一阶段;重排失败按是否显式选择模型或 Provider 单独处理。该图是单库 API 流程示意,Console 不提供答案合成控件。

检索参数全表说明

参数名称字段标识类型默认值取值范围与行为说明
查询文本querystring必填用户输入的自然语言问题或关键词组合。
检索模式searchModestringhybrid可选值:hybrid(向量+全文混合)、vector(纯向量检索)、fulltext(纯全文检索)。
返回结果数量limitintegerConsole 5 / API 10最终返回条数,范围 1~100。
分页偏移量offsetinteger0跨库检索范围 0–5000。
相似度阈值similarityThresholdfloat取知识库默认值(本示例为 0.35)范围 0.0~1.0。仅作用于向量检索及 hybrid 的向量召回分支;不用于全文分支,也不能保证答案正确性。
向量权重vectorWeightfloat取知识库默认值(本示例为 0.7)仅在 searchMode=hybrid 下生效(范围 0.0~1.0)。控制向量得分占比,全文得分占比自动为 1 - vectorWeight。
启用语义重排rerankbooleanfalse开启后使用重排模型对粗召回候选集重新排序。
重排模型rerankModelstring自动选择也可显式选择已启用 rerank 能力的模型;显式模型或 Provider 调用失败会返回错误。
粗召回候选上限recallLimitintegerAPI 省略时 min(100, max(limit * 4, 20));Console 默认生成 max(limit * 4, 20) 并显式发送仅启用重排时使用;显式值为 1–100 且不得小于 limit。Console 的 Limit > 25 时需手动填写合法值,否则生成值超过 100,会被接口拒绝。
允许增强检索降级allowDegradedbooleantrueGraphRAG / RAPTOR / Wiki 发生可降级错误时保留普通结果,检查 capabilities / degradedCapabilities;不控制重排模型失败。
合成接地回答answerbooleanfalse(可按需开启)仅单库 API:使用 indexingDefaults.chatModel 及可选 chatProviderRef,基于最多 12 条证据合成回答,上限 1024 Tokens。
文档定位标签过滤documentTagstring可选精确匹配 {subProductId}_{sectionCode}_{fileKey};首段字母或数字,第二段数字(均可为空),末段 32 位十六进制。
子产品编码过滤subProductIdstring可选非空值限 1–64 位字母或数字;与 documentTag 同时传入时遵循 AND(交集) 语义。
元数据过滤条件metadataFilterobject可选单库使用 logic / conditions;跨库按库 ID 分键,"*" 仅兜底未单独配置的库。

功能入口与权限矩阵

控制台入口、REST API、SDK 方法与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
单知识库交互式检索与问答调试/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/searchPOST /v1/knowledgebases/{kbId}/searchcreateSearch() / create_search()角色:owner、admin、developer、member<br/>Scope:knowledgebases.read自动应用已绑定的 项目级词库(lex_enterprise_synonyms、lex_support_stopwords)
语义重排(Rerank)检索测试页「语义重排(Rerank)」开关POST /v1/knowledgebases/{kbId}/search(rerank: true)createSearch() / create_search()角色:owner、admin、developer、member<br/>Scope:knowledgebases.read依赖 dashscope-prod 的 qwen3.7-text-rerank 模型
**接地答案合成(Grounded Answer,answer=true)**本版通过 API / SDK 接入,Console Search 无此开关POST /v1/knowledgebases/{kbId}/search(answer: true)createSearch() / create_search()角色:owner、admin、developer、member<br/>Scope:knowledgebases.read依赖 dashscope-prod 的 qwen-plus 模型与 知识库设置 的 indexingDefaults.chatModel
**图谱增强多跳检索(useKnowledgeGraph=true)**检索测试页「启用知识图谱增强」开关(部署启用时显示)POST /v1/knowledgebases/{kbId}/search(useKnowledgeGraph: true)createSearch() / create_search()角色:owner、admin、developer、member<br/>Scope:knowledgebases.read依赖 高级索引构建 中 GraphRAG 已就绪(详见 知识图谱探索)
跨多知识库联合检索(Multi-KB Search)服务端 API / 智能体工作台多库挂载POST /v1/knowledgebases/searchcreateMultiSearch() / create_multi_search()角色:owner、admin、developer、member<br/>Scope:knowledgebases.read支持跨库统一重排、metadataFilter 与 offset 分页

功能详解与操作指南

一、在控制台调试混合检索与语义重排


二、使用 documentTag 与 subProductId 进行精确范围过滤

当知识库中包含多个子产品线或多类规范文档,而业务前端明确知道当前用户正在咨询某一个特定子产品(如 subProductId = "ob")或某篇特定手册时,可在检索时传入定位过滤条件:

过滤值必须对应实际文档;模型、项目和知识库名称也需按实际配置替换。

本版 Console Search 没有 documentTag / subProductId 输入控件。需要限定范围时,通过 API / SDK 传递这些字段,并检查返回结果的来源;两个字段同时指定时按交集过滤。


三、通过 REST API 调用单库检索与多库跨库检索

业务后端可通过以下两个标准端点集成知识库检索能力:

1. 单知识库混合检索与答案合成(POST /v1/knowledgebases/{knowledgeBaseId}/search)

curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI 网关的逻辑模型主备容灾和语义缓存是如何工作的?",
    "searchMode": "hybrid",
    "vectorWeight": 0.7,
    "similarityThreshold": 0.35,
    "limit": 5,
    "rerank": true,
    "rerankModel": "qwen3.7-text-rerank",
    "recallLimit": 20,
    "allowDegraded": true,
    "answer": true,
    "subProductId": "aigw"
  }'

2. 跨多个知识库联合检索(POST /v1/knowledgebases/search)

当企业按部门拆分了多个知识库,需要一次请求跨库联合召回并统一重排时,可调用多库检索端点(支持 metadataFilter 与 offset 分页)。该端点不提供单库的增强检索开关和答案合成。过滤对象按库 ID 分键;"*" 只兜底未单独配置的库,具体库配置覆盖兜底,不与其合并。示例需文档已提取对应元数据字段:

curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/search" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseIds": ["kb_enterprise_support"],
    "query": "分布式事务两阶段提交与工单流转规范",
    "searchMode": "hybrid",
    "vectorWeight": 0.65,
    "limit": 10,
    "offset": 0,
    "rerank": true,
    "rerankModel": "qwen3.7-text-rerank",
    "metadataFilter": {
      "*": {"logic": "and", "conditions": [{"name": "category", "comparison": "is", "value": "sop"}]}
    }
  }'

完成一次检索

检索分数用于排序,不是答案正确率。若高分结果不能支持问题,以来源原文为准;若缺少预期来源,先回到 Documents 检查摄取状态、分块和选中的知识库版本。

可调整的检索选项

按文档标签过滤、跨库检索和答案合成的接入方法见站点 API / SDK 导航下的知识库主题;本版 Console Search 页面未提供对应操作控件。

结果排查

现象下一步检查
没有预期文档回到 Documents 确认文档状态和分块,再检查所选版本及相似度阈值
命中相关文档但摘录不完整在来源预览中核对原文,并检查该文档的解析和分块结果
分数较高但内容不能支持问题以来源原文为准;调整 Query 或检索选项后重新比较,不要把分数解释为答案正确率

常见问题与排障(FAQ)

Q1:什么时候应该调高或调低 vectorWeight(向量权重)?

Q2:开启 answer=true 后为什么没有得到答案?

先读 answer.status,再检查配置和证据:

状态含义与处理
not_configured未配置 indexingDefaults.chatModel;先配置可用 Chat 模型及按需设置的 chatProviderRef。
no_evidence模型已配置,但没有可用于合成的证据;检查文档摄取、版本和过滤条件。
failed模型调用失败或返回空答案;结合 answer.error、模型可用性和限流排查。
succeeded已生成文本;仍须核对 results 中的来源是否支持答案。

答案对象含 status、text、model、latencyMs 和 error。来源来自检索结果的 source / locator,不要假定答案对象另有结构化引用数组。答案模型取自 indexingDefaults;retrievalDefaults 提供向量权重和相似度阈值等检索默认值。

Q3:为什么有些明显包含关键词的段落没有出现在最终的 Top 5 结果中?


相关文档