seekdb 混合检索验收助手

将“导入文本 → 浏览器生成向量 → 写入 seekdb → 数据库混合检索 → 展示结果”拆成可复现的检查，输出有证据的结论。适用于已有 JavaScript/TypeScript Web 知识库项目；不假定用户使用特定前端框架。

开始前读取项目

从 package.json、锁文件、服务端数据库适配器和浏览器推理模块确认实际版本及入口。记录 seekdb 的部署方式、模型 ID 和 revision、向量维度、pooling、归一化方式、dtype、推理后端。连接凭据使用现有环境变量，不输出密码、访问令牌或带凭据的连接串。

优先复用现有开发环境和测试命令。没有数据库或浏览器访问能力时，可以完成静态检查，但将对应动态检查标为“未验证”，不把静态推断写成实测通过。

数据库写入测试使用独立测试集合和虚构文本。不要写入或清空业务集合。只在用户授权的测试范围内创建资源，记录本次创建的名称；清理仅限这些资源，并遵守当前工具的删除权限。

检查检索链路

定位文档编码与查询编码的真实调用点，确认两者均在浏览器运行。下载模型权重属于加载过程；请求服务端生成 embedding 属于远程推理。不能仅凭页面显示“本地”判断。
检查写入向量与查询向量的维度、数值有效性、模型版本、pooling 和归一化配置是否一致。对全零、NaN、Infinity 和维度不一致给出明确错误。
沿着检索路由跟踪 SDK 调用和实际数据库执行路径，确认全文检索、向量检索和融合发生在 seekdb。仅调用名含 hybrid 的函数不足以证明这一点；检查当前依赖实现或数据库侧执行证据。将两路结果拉回应用后拼接，不算数据库混合检索。
确认文本、向量、文档 ID 和来源元数据都被持久化；刷新页面后的查询不能依赖前端残留数组返回结果。
把“写入完成”和“索引可查询”分开检查。检查当前 SDK 的 refresh 方法实际执行了什么，不能只因 Promise 成功返回就认定刷新生效。根据安装版本采用受支持的索引刷新方式，并用刚写入的文档验证可见性。

版本参考：在 seekdb-js 1.4.0 配合 seekdb server 1.4 的项目实践中，可通过 collection.hybridSearch 调用数据库混合检索，并使用 CALL dbms_index_manager.refresh() 显式刷新索引。其他版本先检查安装包实现和官方文档，不直接照搬参数或 SQL。

最小动态验收

使用两个临时集合 A、B。模型为英文模型时使用英文语料，另行报告中文场景是否适配，避免把语言不匹配误判成数据库故障。

| 步骤 | 操作 | 需要观察的结果 | | --- | --- | --- | | 初次导入 | 在 A 导入带唯一标记的苹果种植文本并刷新索引 | 对应查询能返回文本、文档 ID 和来源 | | 增量导入 | 保留旧数据，在 A 再导入带另一标记的香蕉运输文本并刷新 | 新文档能检索，旧文档仍保留 | | 集合隔离 | 在 B 导入带不同标记的香蕉文本 | A 的结果不含 B 的文档，反向同样检查 | | 状态切换 | 发起 A 的查询后立即切到 B | A 的迟到响应不能覆盖 B 的结果区域 | | 持久化 | 刷新页面或重启应用后重新选择 A 并查询 | 从数据库取回此前数据 | | 后端降级 | 使用项目支持的开关禁用 WebGPU，或模拟初始化失败 | WASM 可编码并完成真实查询，页面显示实际后端 |

唯一标记用于检查文档身份，另用自然语言查询检查语义检索。不要将手工构造向量的数据库测试冒充真实 embedding 效果测试；两种测试可分别用于验证数据库机制和模型检索质量。

若可访问测试数据库，再验证连接异常：只中断专用测试连接；只读请求可以在明确的连接失效错误后重连并有限重试。写操作若返回结果不确定，先核查文档 ID 或幂等键，避免盲目重试造成重复导入。

检查会话与并发

检查 SDK 的混合检索实现是否在同一连接上使用会话变量。如果存在“生成 SQL 到变量，再执行变量中的 SQL”的两阶段流程，共享连接上的并发可能串扰。按当前驱动设计使用每请求独立连接或串行化完整操作；只串行第一条 SQL 不足以保护后续读取。

前端查询绑定发起时的集合和请求序号。切换集合后清除旧结果，丢弃属于旧集合或旧请求的迟到响应。模型工作线程的消息也需要请求标识，避免文档编码与查询编码结果混用。

量化与性能对照

先保证模型与后端组合能正确运行，再比较性能。WebGPU 可用不等于任意 INT8 模型都可用；初始化成功也不能替代输出质量检查。需要同时覆盖初始化失败和首次推理失败时的降级路径。

使用固定语料、查询和相关性标注，对比 FP32 基线与 FP16 或 INT8 方案。保持模型 revision、分词、pooling、归一化和检索参数一致。量化更换后如继续使用旧向量库，额外测量“新后端查询向量检索旧后端文档向量”的兼容性。

分别记录：

模型权重字节数，以及 tokenizer/config 等公共文件的字节数。压缩比采用相同文件范围，计算为基线字节数除以量化字节数。
冷加载和缓存后加载时间。未清理缓存或未记录网络条件时，不将两次加载作严格冷启动对比。
文档编码总时间和吞吐量，至少比较 batch=1 与一个合理批量；记录样本数及文本长度分布。
查询编码、数据库检索、索引刷新和端到端耗时，分别计时。不能把浏览器 HTTP 请求总耗时标成纯数据库耗时。
Recall@k 与 nDCG@k。Recall@k 为前 k 条命中的相关文档数除以该查询全部相关文档数；没有相关性标注的查询单列，不悄悄记为满分。nDCG 的增益、折损及无相关项处理方式应写清楚。

预热后重复测量并保留逐次数据。报告中位数、重复次数和浏览器/硬件/数据库版本；偶数样本的中位数取中间两个值的平均值。模型变小不代表端到端更快。小样本得满分只说明该测试集通过，不推广为通用检索准确率。

交付结果

输出简洁验收表，区分“通过、失败、未验证”，为每项附运行命令、文件位置、脱敏日志或结果记录。失败时指出最先出现偏差的环节和最小修复建议；若用户授权修复，再修改代码并仅重跑受影响检查。

报告保留以下信息：测试版本与环境、语料与查询规模、实际推理后端、数据库混合检索证据、增量与隔离结果、量化质量和耗时对比、未完成项。不要虚构运行结果或用示例数值充当实测数据。

可用请求示例：

“用这个 Skill 验收我的 seekdb 浏览器知识库，重点查增量导入后搜不到的问题。”
“比较现有 FP16 WebGPU 与 INT8 WASM 的检索质量和端到端延迟，保留原始数据。”
“切换知识库后偶尔显示上一个库的结果，请沿会话和请求状态排查。”