检索测试与问答调试(Search)
检索测试(Search) 是验证召回结果、调整检索策略并核对来源的 Console 页面。混合、向量和全文模式以及可用的重排、GraphRAG、Wiki 选项在该页操作;答案合成、定位标签过滤和跨库检索通过 API / SDK 接入。本文分别说明这些入口,不把 API 参数当作页面控件。
功能概述与核心场景
在企业级 RAG 系统中,仅仅完成文档分块与向量入库并不等于拥有高质量的问答体验。不同业务问题对检索策略有着截然不同的诉求:例如查询具体错误码(如 OB_ALLOCATE_MEMORY_FAILED 或工单号 TK-20261022-001)依赖精准的全文关键词匹配,而询问概念性排障思路(如“向量构建内存不够怎么调优”)则依赖高维语义向量匹配。
Agentbase 检索能力包括以下几类。其中第 3 项答案合成和第 4 项的显式过滤参数通过 API / SDK 接入,Console Search 没有对应输入控件:
- **三路检索模式(
searchMode)与动态权重融合**: - 支持 **
hybrid(默认混合检索)、vector(语义向量检索) 与fulltext(全文关键词检索)**。 - 在
hybrid模式下,支持通过 **vectorWeight**(0.0~1.0)动态调节向量相似度得分与全文检索得分的融合比例。
- 支持 **
- 可选语义重排(Rerank)与增强检索降级:
- 第一阶段通过粗召回(
recallLimit,启用重排时默认取min(100, max(limit * 4, 20)))从海量分块中快速筛选候选集; - 第二阶段调用项目可用的重排模型(例如
qwen3.7-text-rerank)重新排序候选。Rerank 默认关闭,模型名为示例,需替换为项目实际配置; - 重排失败按选模方式处理:显式传入
rerankModel或rerankProviderRef时,上游异常向调用方返回;两者均未指定的自动重排可回退原排序并返回reranked: false。allowDegraded独立控制 GraphRAG / RAPTOR / Wiki 增强检索的可降级错误,单库响应通过capabilities与degradedCapabilities报告状态。
- 第一阶段通过粗召回(
- **接地答案合成(
answer=true)与引用证据溯源**: - 开启
answer=true后,系统自动调用知识库配置的 Chat 模型(如qwen-plus),基于精排后的 Top 证据片段(最多 12 条证据)生成不超过 1024 Tokens 的结构化回答,并附带答案状态、生成耗时、使用模型与原文来源预览(View Source)。
- 开启
- 词库(Lexicon)查询改写与多维元数据过滤:
- 自动应用已绑定的同义词词典(
lex_enterprise_synonyms)与停用词词典(lex_support_stopwords)完成查询预处理。 - 支持按 **
documentTag(精确匹配)、subProductId(子产品 AND 过滤)以及跨库检索的metadataFilter** 进行精准范围收敛。
- 自动应用已绑定的同义词词典(
核心概念与架构
多路混合检索、重排与答案合成流水线
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 模型合成答案"] --> OutputallowDegraded 控制增强检索这一阶段;重排失败按是否显式选择模型或 Provider 单独处理。该图是单库 API 流程示意,Console 不提供答案合成控件。
检索参数全表说明
| 参数名称 | 字段标识 | 类型 | 默认值 | 取值范围与行为说明 |
|---|---|---|---|---|
| 查询文本 | query | string | 必填 | 用户输入的自然语言问题或关键词组合。 |
| 检索模式 | searchMode | string | hybrid | 可选值:hybrid(向量+全文混合)、vector(纯向量检索)、fulltext(纯全文检索)。 |
| 返回结果数量 | limit | integer | Console 5 / API 10 | 最终返回条数,范围 1~100。 |
| 分页偏移量 | offset | integer | 0 | 跨库检索范围 0–5000。 |
| 相似度阈值 | similarityThreshold | float | 取知识库默认值(本示例为 0.35) | 范围 0.0~1.0。仅作用于向量检索及 hybrid 的向量召回分支;不用于全文分支,也不能保证答案正确性。 |
| 向量权重 | vectorWeight | float | 取知识库默认值(本示例为 0.7) | 仅在 searchMode=hybrid 下生效(范围 0.0~1.0)。控制向量得分占比,全文得分占比自动为 1 - vectorWeight。 |
| 启用语义重排 | rerank | boolean | false | 开启后使用重排模型对粗召回候选集重新排序。 |
| 重排模型 | rerankModel | string | 自动选择 | 也可显式选择已启用 rerank 能力的模型;显式模型或 Provider 调用失败会返回错误。 |
| 粗召回候选上限 | recallLimit | integer | API 省略时 min(100, max(limit * 4, 20));Console 默认生成 max(limit * 4, 20) 并显式发送 | 仅启用重排时使用;显式值为 1–100 且不得小于 limit。Console 的 Limit > 25 时需手动填写合法值,否则生成值超过 100,会被接口拒绝。 |
| 允许增强检索降级 | allowDegraded | boolean | true | GraphRAG / RAPTOR / Wiki 发生可降级错误时保留普通结果,检查 capabilities / degradedCapabilities;不控制重排模型失败。 |
| 合成接地回答 | answer | boolean | false(可按需开启) | 仅单库 API:使用 indexingDefaults.chatModel 及可选 chatProviderRef,基于最多 12 条证据合成回答,上限 1024 Tokens。 |
| 文档定位标签过滤 | documentTag | string | 可选 | 精确匹配 {subProductId}_{sectionCode}_{fileKey};首段字母或数字,第二段数字(均可为空),末段 32 位十六进制。 |
| 子产品编码过滤 | subProductId | string | 可选 | 非空值限 1–64 位字母或数字;与 documentTag 同时传入时遵循 AND(交集) 语义。 |
| 元数据过滤条件 | metadataFilter | object | 可选 | 单库使用 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/search | POST /v1/knowledgebases/{kbId}/search | createSearch() / 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/search | createMultiSearch() / create_multi_search() | 角色:owner、admin、developer、member<br/>Scope:knowledgebases.read | 支持跨库统一重排、metadataFilter 与 offset 分页 |
功能详解与操作指南
一、在控制台调试混合检索与语义重排
- 进入
kb_enterprise_support的 检索测试(Search) 页签。 - 在页面的检索参数区中,以下示例值只用于初次对照,按项目数据验证后再调整参数:
- 检索模式(Search Mode):选择
Hybrid(混合检索)。 - 返回条数(Limit):设置为
5。 - 相似度阈值(Similarity Threshold):设置为
0.35。 - 向量权重(Vector Weight):填写
0.70(即 70% 语义向量权重 + 30% 全文关键词权重)。 - 语义重排(Rerank):打开开关,选择项目实际可用的重排模型,展开高级项将 粗召回数量(Recall Limit) 设为
20。选定具体模型后,调用失败会返回错误。
- 检索模式(Search Mode):选择
- 在顶部查询输入框中输入典型复合客服问题:
OceanBase 向量索引构建报 4013 内存不足时如何排障?如果一线坐席无法解决,工单升级 SOP 是什么? - 点击 检索(Search) 按钮,查看参数区下方的结果列表:
- 召回结果列表(Retrieved Chunks):依次列出精排后的 Top 5 分块卡片,卡片显示得分(Score)、可用的来源信息及内容摘录;以本次实际返回为准。
- 来源预览(View Source):来源可用(
source.status=available)且能解析出sourceDocumentId时,卡片显示 查看来源(View source) 按钮。点击打开原文预览;来源不可用或没有文档 ID 的结果不显示此按钮。
二、使用 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"}]}
}
}'完成一次检索
- 在 Query 输入一个具体问题,先保留默认 Limit(5)和
hybrid模式,建立基线。 - 检查结果卡片中的相关度分数、可用来源信息和内容摘录。
- 来源状态为可用且结果包含文档 ID 时,点击 View source 对照原文;PDF 来源也可预览。确认摘录确实支持问题后,再判断这条结果是否可用。没有来源入口时,回到 Documents 查找该文档并检查来源是否仍可访问。
- 比较检索策略时,一次只改一个选项并重复同一问题;有多个知识库版本时,先确认当前选中的版本。
检索分数用于排序,不是答案正确率。若高分结果不能支持问题,以来源原文为准;若缺少预期来源,先回到 Documents 检查摄取状态、分块和选中的知识库版本。
可调整的检索选项
- Limit:Console 默认 5,范围 1–100;API 不传时默认 10。
- Search mode:
hybrid(默认)/vector/fulltext;similarityThreshold默认取知识库检索默认值;hybrid 模式下可调vectorWeight。 - Rerank:默认关闭;开启后可自动选择或指定 Provider 模型。高级项留空时,Console 生成
max(limit * 4, 20)并显式发送。Limit > 25 时需手动填写 1–100 且不小于 Limit 的值,否则请求超出接口范围会被拒绝。此行为不同于 API 完全省略该参数时的服务端默认值。 - GraphRAG / Wiki:部署启用对应能力时才显示开关,首次比较时保持关闭;启用前确认对应索引已构建可用。
- 允许降级(
allowDegraded):页面默认开启;增强能力不可用时可返回降级结果。检查capabilities与degradedCapabilities,判断是否使用了预期索引;关闭后,不可用的增强能力可能使请求失败。
按文档标签过滤、跨库检索和答案合成的接入方法见站点 API / SDK 导航下的知识库主题;本版 Console Search 页面未提供对应操作控件。
结果排查
| 现象 | 下一步检查 |
|---|---|
| 没有预期文档 | 回到 Documents 确认文档状态和分块,再检查所选版本及相似度阈值 |
| 命中相关文档但摘录不完整 | 在来源预览中核对原文,并检查该文档的解析和分块结果 |
| 分数较高但内容不能支持问题 | 以来源原文为准;调整 Query 或检索选项后重新比较,不要把分数解释为答案正确率 |
常见问题与排障(FAQ)
Q1:什么时候应该调高或调低 vectorWeight(向量权重)?
- 原因分析:
vectorWeight控制混合检索(searchMode=hybrid)中text-embedding-v3余弦相似度得分与全文 BM25 关键词匹配得分的加权比例。不同业务查询对字面精确性与语义泛化性的敏感度不同。 - 解决措施:
- **调高
vectorWeight(如0.75~0.85)**:适用于用户提问非常口语化、表述多变,且与文档标准术语字面重合度较低的场景(依赖text-embedding-v3捕捉深层语义相似性)。 - **调低
vectorWeight(如0.30~0.50,提高全文检索权重)**:适用于用户经常直接输入精确的错误码(如-4013)、配置参数名(如chunkTokenNum)、工单编号(如TK-20261022-001)或 API 路径的场景。此时结合 [项目级词库(lex_enterprise_synonyms)](lexicons.md) 可获得极佳的精确命中率。
- **调高
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 结果中?
- 原因分析: 候选分块可能因相似度阈值(
similarityThreshold)过高被截断、在第一阶段粗召回(recallLimit)窗口外未进入 Rerank 阶段,或被请求中的documentTag/subProductId过滤条件排除。 - 解决措施: 请按以下三步排查:
- **检查
similarityThreshold是否过高**:若阈值设得过高(如0.85),向量召回分支可能过滤掉有效候选;全文分支不受该阈值过滤,建议先将阈值调至0.25~0.40观察原始得分分布; - **检查
recallLimit是否过小**:若开启了 Rerank,只有进入第一阶段粗召回前recallLimit名的分块才有机会参与重排,建议保持recallLimit >= 20; - **检查是否被
documentTag或subProductId过滤排除**:确认请求中未残留不匹配的定位过滤条件。
- **检查