Docs
文档目录

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

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


功能概述与核心场景

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

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

  1. 三路检索模式(searchMode)与动态权重融合:

    • 支持 hybrid(默认混合检索)、vector(语义向量检索) 与 fulltext(全文关键词检索)。

    • 在 hybrid 模式下,支持通过 vectorWeight(0.0~1.0)动态调节向量相似度得分与全文检索得分的融合比例。

  2. 可选语义重排(Rerank)与增强检索降级:

    • 第一阶段通过粗召回(recallLimit,启用重排时默认取 min(100, max(limit * 4, 20)))从海量分块中快速筛选候选集;

    • 第二阶段调用项目可用的重排模型(例如 qwen3.7-text-rerank)重新排序候选。Rerank 默认关闭,模型名为示例,需替换为项目实际配置;

    • 重排失败按选模方式处理:显式传入 rerankModel 或 rerankProviderRef 时,上游异常向调用方返回;两者均未指定的自动重排可回退原排序并返回 reranked: false。allowDegraded 独立控制 GraphRAG / RAPTOR / Wiki 增强检索的可降级错误,单库响应通过 capabilities 与 degradedCapabilities 报告状态。

  3. 接地答案合成(answer=true)与引用证据溯源:

    • 开启 answer=true 后,系统自动调用知识库配置的 Chat 模型(如 qwen-plus),基于精排后的 Top 证据片段(最多 12 条证据)生成不超过 1024 Tokens 的结构化回答,并附带答案状态、生成耗时、使用模型与原文来源预览(View Source)。

  4. 词库(Lexicon)查询改写与多维元数据过滤:

    • 直接检索可应用已启用绑定中的同义词和扩展词进行查询改写;知识库直接检索不会使用停止词清洗查询。

    • 支持按 documentTag(支持多个标签及分段匹配)、subProductId(子产品 AND 过滤)以及跨库检索的 metadataFilter 进行精准范围收敛。


核心概念与架构

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

检索测试与问答调试(Search):流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

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

检索参数全表说明

参数名称字段标识类型默认值取值范围与行为说明
查询文本querystring必填用户输入的自然语言问题或关键词组合。
检索模式searchModestringhybrid可选值:hybrid(向量+全文混合)、vector(纯向量检索)、fulltext(纯全文检索)。
返回结果数量limitinteger控制台 10 / API 10最终返回条数,范围 1~100。
分页偏移量offsetinteger0跨库检索范围 0–5000。
相似度阈值similarityThresholdfloat控制台 0;API 可取知识库默认值范围 0.0~1.0。仅作用于向量检索及 hybrid 的向量召回分支;不用于全文分支,也不能保证答案正确性。
向量权重vectorWeightfloat控制台 0.5;API 可取知识库默认值仅在 searchMode=hybrid 下生效(范围 0.0~1.0)。控制向量得分占比,全文得分占比自动为 1 - vectorWeight。
启用语义重排rerankbooleanfalse开启后使用重排模型对粗召回候选集重新排序。
重排模型rerankModelstring自动选择也可显式选择已启用 rerank 能力的模型;显式模型或 Provider 调用失败会返回错误。
粗召回候选上限recallLimitintegerAPI 省略时 min(100, max(limit * 4, 20));控制台初始值为 50仅启用重排时使用;显式值为 1–100 且不得小于 limit。重排开启时,控制台数值应不小于 limit 且不超过 API 上限 100。
允许增强检索降级allowDegradedboolean控制台 false / API trueGraphRAG / RAPTOR / Wiki 发生可降级错误时保留普通结果,检查 capabilities / degradedCapabilities;不控制重排模型失败。
合成接地回答answerbooleanfalse(可按需开启)仅单库 API:使用 indexingDefaults.chatModel 及可选 chatProviderRef,基于最多 12 条证据合成回答,上限 1024 Tokens。
文档定位标签过滤documentTagstring可选支持逗号分隔多个非空标签,任一匹配即可;结构化值可按完整段匹配,如 ob_12 可匹配 ob_12_<fileKey>。
子产品编码过滤subProductIdstring可选非空值限 1–64 位字母或数字;与 documentTag 同时传入时遵循 AND(交集) 语义。
元数据过滤条件metadataFilterobject可选单库使用 logic / conditions;跨库按库 ID 分键,"*" 仅兜底未单独配置的库。

在 2.12.0 中,匹配按下划线分段前缀进行,自由格式标签也参与:例如 finance 可命中 finance_confidential_notes。过滤值 ___ 的末尾空段被移除后可能匹配有标签的文档;不要使用全下划线值。标签筛选不能替代权限控制,请对输入和返回结果进行校验。


功能入口与权限矩阵

控制台入口、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
Scope:knowledgebases.read
使用已启用的 项目级词库 进行同义词和扩展词改写;直接检索忽略停止词
语义重排(Rerank)检索测试页「语义重排(Rerank)」开关POST /v1/knowledgebases/{kbId}/search(rerank: true)createSearch() / create_search()角色:owner、admin、developer、member
Scope:knowledgebases.read
依赖项目可用的重排模型;模型名与提供商以实际配置为准
接地答案合成(Grounded Answer,answer=true)本版通过 API / SDK 接入,Console Search 无此开关POST /v1/knowledgebases/{kbId}/search(answer: true)createSearch() / create_search()角色:owner、admin、developer、member
Scope:knowledgebases.read
依赖 知识库设置 的 indexingDefaults.chatModel 及项目可用的对话模型
图谱增强多跳检索(useKnowledgeGraph=true)检索测试页「启用知识图谱增强」开关(部署启用时显示)POST /v1/knowledgebases/{kbId}/search(useKnowledgeGraph: true)createSearch() / create_search()角色:owner、admin、developer、member
Scope:knowledgebases.read
依赖 高级索引构建 中 GraphRAG 已就绪(详见 知识图谱探索)
跨多知识库联合检索(Multi-KB Search)服务端 API / 智能体工作台多库挂载POST /v1/knowledgebases/searchcreateMultiSearch() / create_multi_search()角色:owner、admin、developer、member
Scope:knowledgebases.read
支持跨库统一重排、metadataFilter 与 offset 分页

功能详解与操作指南

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

  1. 进入 kb_enterprise_support 的 检索测试(Search) 页签。

  2. 在页面的检索参数区中,以下示例值只用于初次对照,按项目数据验证后再调整参数:

    • 检索模式(Search Mode):选择 Hybrid(混合检索)。

    • 返回条数(Limit):设置为 5。

    • 相似度阈值(Similarity Threshold):设置为 0.35。

    • 向量权重(Vector Weight):填写 0.70(即 70% 语义向量权重 + 30% 全文关键词权重)。

    • 语义重排(Rerank):打开开关,选择项目实际可用的重排模型,展开高级项将 粗召回数量(Recall Limit) 设为 20。选定具体模型后,调用失败会返回错误。

  3. 在顶部查询输入框中输入典型复合客服问题: OceanBase 向量索引构建报 4013 内存不足时如何排障?如果一线坐席无法解决,工单升级 SOP 是什么?

  4. 点击 检索(Search) 按钮,查看参数区下方的结果列表:

    • 召回结果列表(Retrieved Chunks):依次列出精排后的 Top 5 分块卡片,卡片显示得分(Score)、可用的来源信息及内容摘录;以本次实际返回为准。

    • 来源预览(View Source):结果包含 source.documentId 时,卡片显示 查看原文 按钮;点击后能否加载内容还取决于来源状态和权限。


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

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

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

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


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

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

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

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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 分键;"*" 只兜底未单独配置的库,具体库配置覆盖兜底,不与其合并。示例需文档已提取对应元数据字段:

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/search" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -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"}]}
    }
  }'
)

完成一次检索

  1. 在 Query 输入一个具体问题,先保留默认 Limit(10)和 hybrid 模式,建立基线。

  2. 检查结果卡片中的相关度分数、可用来源信息和内容摘录。

  3. 结果包含 source.documentId 时,点击 查看原文;若来源状态不可用,面板会提示无法加载。PDF 来源也可预览。确认摘录确实支持问题后,再判断这条结果是否可用。没有来源入口时,回到 文档 查找该文档并检查来源是否仍可访问。

  4. 比较检索策略时,一次只改一个选项并重复同一问题;有多个知识库版本时,先确认当前选中的版本。

测试知识库的检索结果

图:2.12.0 测试知识库使用默认检索选项命中合成文档。

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

可调整的检索选项

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

结果排查

现象下一步检查
没有预期文档回到 文档 确认文档状态和分块,再检查所选版本及相似度阈值
命中相关文档但摘录不完整在来源预览中核对原文,并检查该文档的解析和分块结果
分数较高但内容不能支持问题以来源原文为准;调整 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 结果中?


相关文档