切换主题
知识检索调试与版本评测
本页阅读位置
完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。
发布前如何检查知识库
- 向 MANAGED 草稿导入文档，检查索引与当前分块策略是否一致。
- 使用真正有权访问该知识库的管理身份调试草稿；发布后再使用实际业务用户凭据调试。
- 为真实业务问题指定稳定的期望文档标识，比较当前与新版本。
- 保存评测并检查逐题命中与指标；确认结果符合业务需要后，通过已有发布流程发布。评测不会自动发布、修改索引或调用模型。
控制台在“知识库 → 查看配置 → 管理托管文档”的“检索与版本评测”中操作。填写问题、K、评测名称、一个或两个精确版本及 JSON 问题集。凭据留空使用当前登录身份；要检查真实用户权限，输入该用户的有效凭据，页面在每次请求后清空输入，不持久保存。不能填写用户编号来模拟他人，也没有管理员正文旁路。
“检索调试”显示命中分块、得分、来源和当前可读索引状态。“执行并保存评测”展示版本比较和逐题排名。“刷新我的评测”只展示本次使用身份自己的摘要；查看详情及重新执行样例时，应再次使用相同主体和租户的有效凭据。换一个身份不会得到别人的评测。
算法、排名与指标
算法标识为 LEXICAL_TERMS_V1，复用实际托管检索的词项评分。英文按词项、中文按双字词项匹配；分数为查询词命中数量除以分块词项数量平方根。词项方式遇到不匹配会返回空结果。配置向量或混合检索后，工作台与聊天共用实际模型向量排名，版本结果分别标识 COSINE_V1 或 RRF_LEXICAL_COSINE_V1；评测同时绑定向量空间与索引摘要。版本摘要绑定可读文档、文档版本、分块正文及策略；相同身份、固定版本和问题集可复测。
调试的 K 是分块数；评测的 K 是文档数。同一文档命中多个分块时，以最高分分块代表，按首次文档出现排名，避免长文档重复占满指标。稳定得分并列采用文档标识及原分块顺序。
| 指标 | 定义 | 如何解释 |
|---|---|---|
| Recall@K | 前 K 个文档中命中的期望文档数 / 期望文档数 | 一题可以有多个相关文档；版本总体为各题平均 |
| MRR@K | 第一个相关文档排名的倒数；无相关命中为 0 | 第一位相关为 1，第二位为 0.5；总体为各题平均 |
| 命中率 HitRate@K | 至少命中一个期望文档的问题比例 | 衡量能否找回任一相关文档 |
指标只评价检索。它们不能证明模型回答真实、工具执行正确或 OCR 没有错字。elapsedMs 是包含当前授权与评测操作的总耗时，不能作为独立向量服务或模型延迟。
权限与历史结果
业务身份只调试已发布 MANAGED 版本；管理身份可调试草稿，仍受当前租户、文档 ACL 与业务授权限制。授权先于排名：其他租户或撤权文档不参与候选，不会在 Top K 后才删除。评测期望文档至少在一个比较版本存在；某版本中缺失会计为未命中，但已有且当前无权读取的期望文档会拒绝整次评测。
业务权限服务收到当前可信身份及 EXECUTE 的 query/topK 参数；评测预期与历史详情还需要 READ_HISTORY。所有者由应用、主体、租户共同确定，凭据轮换后仍需当前权限。管理员不能读取他人记录。评测详情重新检查当前知识状态、租户、期望/命中文档 ACL、业务历史权限和凭据；失败时不回退缓存或显示此前的详情。
数据库保存用户问题、期望标识、精确版本、可读索引摘要、文档命中标识、排名和指标，不保存来源正文。问题集可能包含业务信息，需按组织的数据库及备份规则保护。列表只有自己的名称、版本等摘要；撤权后的详情被拒绝，但所有者仍可删除自己的记录。
历史详情状态 CURRENT 表示可读索引及定义与执行时相同，STALE 表示草稿索引、策略或发布状态发生变化。历史指标不会被自动重算。选择“使用此样例重新评测”，确认当前版本和身份，再创建新的结果。源撤销、应用停用或源文档删除/撤权会拒绝详情；不会显示旧正文。删除评测不删除知识库、索引或原件。
请求上限和失败处理
每次调试问题 1–512 个 UTF-16 字符，K 为 1–20；评测一或两个不重复的稳定版本，1–10 个问题，每题 1–20 个不重复期望文档。名称 1–128 字符。请求最长 15 秒，实例最多 4 个并发工作台操作，没有无限等待队列，不自动重试。每个应用/主体/租户最多保留 100 条评测，实例总计 10000 条；删除自己的旧记录后可继续保存。分页 limit 1–20、offset 0–1000000。
| 错误 | 操作 |
|---|---|
| INVALID_REQUEST | 检查 JSON、问题、期望文档、版本和数量 |
| PERMISSION_DENIED / BUSINESS_PERMISSION_DENIED | 使用真实有效身份并核对当前业务权限 |
| DOCUMENT_NOT_AVAILABLE | 检查版本、租户及文档当前权限；不能借此查询其他租户内容 |
| KNOWLEDGE_ACCESS_CHANGED / KNOWLEDGE_INDEX_CHANGED | 授权或索引在操作中改变，重新检查后显式执行 |
| EVALUATION_TIMED_OUT / WORKBENCH_BUSY | 检查配置与实例负载，稍后显式执行，避免自动批量重试 |
| EVALUATION_LIMIT | 删除自己的旧评测，按容量管理记录 |
| REVISION_MISMATCH | 回读当前记录修订号后确认删除 |
| RESOURCE_NOT_FOUND | 检查记录编号和当前所有者身份 |
可读索引健康只覆盖当前身份能读的文档，不等于全库发布预检成功。发布仍执行全库策略与活跃任务检查。外部 REMOTE/INLINE 知识不进入此托管工作台；需要依照各自版本化回调协议验证，不能把它们描述成已完成托管索引评测。
HTTP 接口
设 P=/v1/apps/{app}/knowledge/{knowledgeId}，均要求 Bearer，返回 no-store。
| 方法与地址 | 输入或用途 |
|---|---|
| POST P/versions/{version}/retrieval-debug | query 必填；topK 默认 5；返回真实分块与可读索引健康 |
| POST P/evaluations | name、versions、cases 必填，topK 默认 5；同步执行并保存当前身份的结果 |
| GET P/evaluations?limit=10&offset=0 | 当前所有者的分页摘要，无正文和逐题问题 |
| GET P/evaluations/ | 当前授权复验后的详情与 CURRENT/STALE |
| DELETE P/evaluations/ | If-Match 为当前修订号；仅所有者删除 |
json
{
"name": "发布前部署问题检查",
"versions": ["1.0.0", "1.1.0"],
"topK": 5,
"cases": [
{"query": "如何重启监测服务", "expectedDocumentIds": ["deployment-manual"]}
]
}逐题结果包含 caseIndex、文档命中 hits、recallAtK、reciprocalRank 和 hit。每个命中只有 documentId、chunkId、rank 和 score；来源正文只在当前授权调试响应中出现，不保存于评测历史。旧索引分块可能没有定位及来源元数据；平台提供原文文档标识，但不推断未保存的定位。
SDK 示例
java
var debug = client.debugKnowledge("project-documents", "1.1.0", "如何重启监测服务", 5)
.toCompletableFuture().get();
var input = KnowledgeEvaluation.builder("部署问题检查", List.of("1.0.0", "1.1.0"))
.topK(5).caseOf("如何重启监测服务", List.of("deployment-manual")).build();
var evaluation = client.evaluateKnowledge("project-documents", input).toCompletableFuture().get();
var id = (String) evaluation.get("id");
var current = client.knowledgeEvaluation("project-documents", id).toCompletableFuture().get();
var page = client.knowledgeEvaluations("project-documents", 10, 0).toCompletableFuture().get();
client.deleteKnowledgeEvaluation("project-documents", id,
((Number) current.get("revision")).longValue()).toCompletableFuture().get();kotlin
val input = knowledgeEvaluation("部署问题检查", listOf("1.0.0", "1.1.0")) {
topK = 5
case("如何重启监测服务", listOf("deployment-manual"))
}
val debug = client.debugKnowledgeAwait("project-documents", "1.1.0", "如何重启监测服务")
val evaluation = client.evaluateKnowledgeAwait("project-documents", input)
val id = evaluation["id"] as String
val current = client.knowledgeEvaluationAwait("project-documents", id)
client.deleteKnowledgeEvaluationAwait("project-documents", id,
(current["revision"] as Number).toLong())Kotlin 示例说明：
客户端使用真实用户 Bearer；Java 请求在构建时快照问题集和版本，Kotlin 仅包装 Java 核心。等待失败不是保存失败的证明：先查询自己的历史，再决定是否重新执行，避免重复创建记录。平台响应没有其他用户的来源缓存。
备份与回退
V14 表随完整数据库备份，旧版平台可保留此表但不能读取工作台记录；不要改已执行迁移。停止工作台写入后回退，不影响原知识文档与聊天检索。评测数据恢复必须与精确知识版本及当前权限共同核验。
文档来源与验证记录
| 字段 | 内容 |
|---|---|
| 状态 | 已确认 |
| 日期 | 2026-10-01 |
| 来源 | KnowledgeWorkbench、Knowledge、Java/Kotlin SDK |
| 责任人 | SparkTide 维护者 |
| 关联任务 | 完整产品落地 K08 |
| 结论 | 以真实用户身份检查命中、比较固定知识版本并保存可重复评测 |
| 证据 | 平台完整构建 178 项、后台 SDK 实际隔离联调完整构建 96 项全部通过；PostgreSQL V13→V14 迁移、版本比较、重启保留与撤权拒绝、管理页面实际操作验证通过 |