Skip to content

feat(retrieval): 固定 SAG1/SAG2 知识库算法,支持原生入库、混合检索与问答对比 - #253

Draft
luoshuai990529 wants to merge 5 commits into
mainfrom
feat/sag2-retrieval-strategy
Draft

luoshuai990529 wants to merge 5 commits into
mainfrom
feat/sag2-retrieval-strategy

Conversation

@luoshuai990529

@luoshuai990529 luoshuai990529 commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

功能变化

  • 知识库算法在创建时固定:只提供「事件检索(SAG1)」和「证据检索(SAG2)」,默认 SAG1。编辑只能修改名称、描述等信息,前后端均禁止切换算法;既有信源全部保留 SAG1,旧的 default_search_strategy=sag2 不会被误迁为 SAG2 入库算法。
  • SAG2 原生入库与完整生命周期:后续上传只解析、分块、建立原文索引,不调用 embedding 或实体/事项提取;创建及建索引不需要 JEV Key。SAG1 保留原有处理流程。覆盖重处理、取消/恢复、回放、原文/引用读取、文档与整源删除。SQLite 使用独立 sag2.db;PostgreSQL 使用同库独立 sag2 schema,每个不可变输入独立命名空间。
  • 默认自动混合检索:搜索和问答按各信源固定算法分别召回,混合范围通过 RRF 合并、去重并限额,保留来源与算法;显式 SAG1 子模式只检索 SAG1,SAG2 模式只检索 SAG2。设置页只配置 SAG1 内部检索策略。部分失败、SAG1 子检索失败及 JEV 降级均明确展示,避免把不完整证据当作完整结果。
  • 付费模式就地配置:搜索/问答选择缺配置的 JEV 精排或 SAG2 时打开共享配置弹窗,保存成功后才切换;取消或保存失败保留原模式和草稿。服务端仍禁止缺 Key 的显式付费检索。回答显示实际 JEV 用量。
  • OCTX 兼容采用最小范围:保留 SAG1 导入/导出;SAG2 整源及单文档导出禁用,API、执行任务与导入覆盖边界同样拦截。不扩展 OCTX 格式、不提供算法转换。
  • 保留问答按轮选择与探索页 2–3 模式并排对比;快速、均衡、精确、JEV 精排均属于 SAG1 子策略。SAG2 首期仅支持 SQLite / PostgreSQL。
  • 依赖仍为正式版 zleap-sag2==0.1.0、jieba==0.42.1,保留桌面词典收集配置。

验证结果

最终功能提交 86c6c0ab:

  • 后端完整回归:1,800 passed / 7 skipped(396.81 秒);前端 111 文件 / 906 passed,typecheck、lint、生产构建通过;Ruff 与 diff 检查通过。
  • SQLite / PostgreSQL 组合:8 passed;其中独立 PostgreSQL 原生入库、读取、回放、删除生命周期 1 项通过,其余应用任务链路在 SQLite 验证。未运行的环境专项以 pytest skip 保留,未计作通过。
  • 真实本地服务 + 浏览器:保留旧库副本;SAG1 新上传就绪并产生 1 事件,SAG2 浏览器上传就绪且 0 事件;真实在线 JEV 混合搜索与问答均同时引用 SAG1/SAG2,正确回答原生文档独有的 NATIVE-253,SAG2 引用可打开原文。API 重启后混合检索、显式算法限定再次通过。
  • 缺 Key:浏览器弹窗、取消保留草稿已验证;未填 Key 的显式检索返回 400;API 修改算法返回 422、SAG2 OCTX 导出返回 422。真实文档/整源删除任务均最终 succeeded,未仅以墓碑 404 判断成功。
  • 独立 Standards / Spec code-review:未发现明确仓库规范违反;审查发现的删除回执完整性、混合失败/降级信息丢失均以失败复现测试修复。保留一项非阻断维护建议:后续可集中 EngineManager 的原生内容读取分支,避免本次扩大为无关重构。
  • 已生成 16 张真实截图的离线对比报告,存放本地 output/pr253-engine-binding-acceptance-20261101/report.html,不提交运行产物。本次应用与 PostgreSQL 验收服务已关闭。
  • 远端最终提交 CI:CI #642 六项任务全部通过;dsh-sag #77 通过(覆盖实际 DSH 宿主上传、处理、检索与重启)。未执行完整桌面安装包安装或生产部署验收。

提交与数据边界

保留原有 4 个功能提交,本次固定算法及完整双引擎链路归入 1 个完整功能提交;审查修复并入此提交,不增加零散修补提交。未提交本地计划、无关 Markdown、API Key、数据库、上传文件、日志或截图;Markdown 仅对应功能的 README.md、README-CN.md、CHANGELOG.md。已将本地已保存凭证与完整待提交 diff 比对,无匹配。

@luoshuai990529
luoshuai990529 force-pushed the feat/sag2-retrieval-strategy branch 2 times, most recently from 92d6022 to 524ec57 Compare October 24, 2026 17:06
@luoshuai990529 luoshuai990529 changed the title feat(search): 新增 SAG2 证据检索模式并要求 JEV 模式配置 API Key feat(retrieval): 接入 SAG2 证据检索模式及信源默认、问答按轮选择与探索页对比 Oct 24, 2026
依赖与打包
- 新增 `zleap-sag2==0.1.0`(PyPI 正式版);中文分词由 `jieba-py` 改为
  `jieba==0.42.1`,与 zleap-sag2 共用;桌面打包收集 `zleap-sag2`、`jieba`
  元数据与 `pyuca` 排序词典

后端
- 新增 `sag/sag2_engine.py`:只读 zleap-sag2 引擎直接在 SAG 的 SQLite /
  PostgreSQL 关系库上检索(BM25 召回后由 JEV 服务多轮评分),一次请求覆盖
  全部目标信源;按配置指纹惰性重建,内置并发上限、范围段落上限、整次超时
  与异常翻译;引擎工作运行在专用线程的事件循环,不阻塞 API 循环
- 新增门面策略 `sag2`:保留引擎顺序与原始 JEV 分数,失败不回退 vector;
  能力依赖 `jev` 与 `sag2_relational`(首期仅 SQLite / PostgreSQL)
- JEV 为付费服务:`jev` 能力要求同时保存地址与 API Key(`jev_api_key_missing`),
  `multi_jev` 同步受约束;设置保存、Agent 人格、显式请求、连接测试均在缺
  Key 时拒绝;改地址或 Key 导致连接不完整而默认策略仍为 JEV 模式时拒绝保存
- `sag2` 与 `multi_jev` 共用 JEV 错误文案与错误码;以 `JEV_SCORED_STRATEGIES`
  统一各入口的 JEV 模式判断;新增 `SAG_SAG2_*` 调优参数

前端
- 检索模式列表新增 `sag2`,JEV 评分模式带付费标识;旧后端未声明支持时按
  不可用处理;灰置项因缺配置或 Key 时提供「去设置」入口
- 知识库设置中 API Key 改为选择 JEV 模式时必填;检索状态栏显示 SAG2 的
  本次 JEV 评分用量

文档
- README / README-CN 检索模式表新增 `sag2`,说明存储要求、PostgreSQL 辅助表
  权限与付费 Key 要求;CHANGELOG Unreleased 记录
后端
- `Source` 新增 `default_search_strategy`(可空,跟随全局默认),创建 / 更新
  接口接受并返回;取值须为当前部署可用的模式,JEV 付费模式还需已保存
  API Key,拒绝时沿用能力原因码
- 新增 `resolve_search_strategy`:显式请求 → Agent 人格 → 范围内信源的共同
  默认 → 全局默认;检索服务、搜索接口、Agent 工具统一走该解析,结果
  `stats.strategy_origin` 标明来源

前端
- 创建 / 编辑信源对话框新增「默认检索模式」选择器:首项「跟随全局默认」,
  各模式附通俗说明、适用场景与付费标识;不可用的模式灰置并说明原因
- 选择 JEV 模式但缺少服务或 Key 时就地展开 JEV 配置(预设服务商、Key、
  测试连接),保存后再创建或更新;缺 Key 时无法提交
- 信源卡片与详情头部显示默认模式标签;搜索页在范围内信源默认一致且用户
  未手动选择时自动采用并标注「信源默认」
@luoshuai990529
luoshuai990529 force-pushed the feat/sag2-retrieval-strategy branch 3 times, most recently from 683ef31 to c155710 Compare November 1, 2026 10:27
后端
- `AskRequest` 新增可选 `strategy`,经 `AskPlan` 与工具上下文传入
  `search_context`,优先于 Agent 人格与信源默认
- `/ask` 在开始流式生成前校验该模式可用,付费 JEV 模式缺 Key 时返回 400,
  不落库用户消息;工具结果 `retrieval_stats.strategy_origin` 标明来源

前端
- 输入框工具栏在「联网」旁加入与探索页一致的模式控件,默认显示将实际
  使用的模式并标注来源(人格默认 / 信源默认),生成中禁用
- 用户选择后仅对本面板后续轮次生效;模式不可用被拒绝时在输入框上方
  内联提示并提供设置入口;活动时间线显示本轮模式来源
- 搜索栏「对比」开关:开启后以 2–3 个模式芯片替代单模式控件,同一问题
  并发对比;可选 LLM 评审,范围沿用 @ 选择
- 分栏结果显示耗时、召回数、SAG2 的 JEV 用量与降级状态,跨列共同命中的
  片段加标记,失败列内联显示原因;下方列出两两评审结论
- 任一列可「按此模式检索」,固定该模式并回到普通搜索;关闭对比保留上次
  普通结果
- 对比列、片段行与评审列表抽为共享组件,信源页检索测试对话框改为复用
@luoshuai990529
luoshuai990529 force-pushed the feat/sag2-retrieval-strategy branch from c155710 to 9eccdec Compare November 1, 2026 10:47
@luoshuai990529 luoshuai990529 changed the title feat(retrieval): 接入 SAG2 证据检索模式及信源默认、问答按轮选择与探索页对比 feat(retrieval): 固定 SAG1/SAG2 知识库算法,支持原生入库、混合检索与问答对比 Nov 1, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant