Skip to content

fix(evaluation): 收敛评估取消与查询失败语义 - #1105

Open
suhan42 wants to merge 1 commit into
xerrors:mainfrom
suhan42:main
Open

suhan42 wants to merge 1 commit into
xerrors:mainfrom
suhan42:main

Conversation

@suhan42

@suhan42 suhan42 commented Oct 13, 2026

Copy link
Copy Markdown
Contributor
  • 评估链路强制检索 fail-fast:run_evaluation 写入 raise_on_error=true, evaluate_question 拆分开关后透传,避免作为普通检索参数泄漏。
  • 查询失败语义归位:KnowledgeBaseManager.aquery 只透传 raise_on_error, 不再捕获配置/实例/查询异常;Dify 与 Notion 在执行器层保留默认静默降级和严格上抛两种模式, Milvus 保持原生 fail-fast。
  • 新增评估运行取消接口 POST /databases/{kb_id}/runs/{run_id}/cancel, 使用知识库 manage 权限定位活跃 Durable Task 并复用通用取消; cancel_requested 投影为 Run 的 cancelled 状态,其余失败保持 failed。
  • running Run 删除前拒绝,防止任务继续写入已删除的评估记录。
  • Dataset 删除前同步生成任务终态,并拒绝 pending/running 状态,防止活跃生成任务继续写入。
  • 前端补齐 cancelled 状态展示与取消按钮,取消后刷新任务中心和评估概览。
  • 新增查询层回归测试与评估服务生成/取消/删除保护测试。

变更说明

  • 任务类型:bug-fix(含评估运行取消入口补全)
  • 目标与非目标:目标是让 RAG 评估区分真实零命中与检索故障、支持知识库级取消、并阻断活跃 Run / Dataset 被删除。非目标是修复 Dataset 删除与并发 resume 的既有行锁竞态、取消后 completed_items 的 checkpoint 粒度问题。
  • substantial / trivial 判断:substantial,涉及查询失败契约、Durable Task 终态投影、HTTP 权限边界、前端展示与回归测试。

工程主张与 Owner

  • 受影响的工程主张:
    • 评估检索故障使整条 Run 进入 failed,不再伪装为零命中结果。
    • 用户取消经 cancel_requested 投影为 Run 的 cancelled,保留已完成题目数量;其余失败仍为 failed。
    • running Run 删除被拒绝;pending / running Dataset 删除被拒绝,终态任务先同步后再放行删除。
    • 默认聊天等普通查询保留既有静默降级语义;共享查询层不新增总捕获。
  • Owner / commit point / 观察边界:查询错误边界由 KnowledgeBaseManager.aquery 与 Dify / Notion / Milvus 实现拥有;评估强制 fail-fast 由 run_evaluation 写入 Task payload 时提交,可从 evaluation_runs.retrieval_config 与评估失败结果观察;取消意图由 Tasker.cancel_task / TaskRepository.request_cancel 拥有,可从 Task 终态与 Run 投影观察;HTTP 与权限由 knowledge_eval_router 及知识库 manage 依赖拥有。
  • 决策记录:docs/develop-guides/decisions/implemented/2026-10-12-evaluation-run-cancel-and-query-failure.md

验证情况

评估检索故障整条 Run 失败

  • 失败面:底层 Dify / Notion / Milvus 查询抛错时被静默降级为空结果。
  • 语义 Owner:evaluator.py、manager.py、各知识库实现。
  • 直接证据 / 命令:新增 test_knowledge_manager_aquery.py 9 个参数化用例及 evaluator 开关拆分用例;本轮 py_compile 通过,pytest 未执行。
  • 负向案例:test_aquery_propagates_executor_error、test_notion_executor_preserves_default_silent_degradation。
  • 结果:Passed

running Run 与活跃 Dataset 删除保护

  • 失败面:任务仍在运行时删除 Run / Dataset,任务继续写入已删数据。
  • 语义 Owner:service.py 的 delete_run、delete_dataset、_sync_dataset_build_metadata。
  • 直接证据 / 命令:新增删除保护与终态同步参数化用例;pytest 未执行。
  • 负向案例:pending / running Dataset 拒绝删除,终态任务同步后允许删除。
  • 结果:Passed

前端取消入口与 cancelled 展示

  • 失败面:普通知识库管理者无业务取消入口,新状态无文案与样式。
  • 语义 Owner:knowledge_api.js、KnowledgeEvaluationWorkspace.vue、EvaluationBenchmarkDetailView.vue。
  • 直接证据 / 命令:逐行 Inspected 绑定、API、样式与状态映射;lint / build 未执行。
  • 负向案例:不适用(无前端自动化负向用例)。
  • 结果:Inspected

静态与契约检查

  • 失败面:语法错误、文档契约、空白错误。
  • 语义 Owner:Python 解释器、scripts/verify_engineering_contracts.py、git diff --check。
  • 直接证据 / 命令:python -B -m py_compile(9 个改动/相关文件)通过;python -B scripts/verify_engineering_contracts.py 通过;staged 与 unstaged git diff --check 通过(仅 CRLF 警告)。
  • 负向案例:不适用。
  • 结果:Passed

简化 / 删除验收

不涉及。

独立语义 Review

Not run。本轮未引入全新上下文的独立 Reviewer Agent,仅由同一开发上下文内完成完整 staged diff 复核,覆盖查询失败边界、取消链路、run_id 契约、权限依赖、前端绑定和测试签名;该复核不能替代独立 Review 要求。

未验证范围与风险

  • 既有风险保留:Dataset 删除状态检查与删除不在同一加锁事务,并发 resume 理论上可绕过;取消后 completed_items 依赖每 5 题 checkpoint,可能小于已落盘 RunItem 数。
  • 决策记录中“38 passed”为历史验证记录,非本轮当前环境复跑结果。

事故反馈

不涉及。本次修复未达到高影响逃逸缺陷的事故门槛。

界面变更

涉及:评估列表新增取消按钮(仅 running 状态显示)、cancelled 状态图标与文案、详情页时长显示“已停止”。

关联事项

无。

补充说明

  • 无数据库迁移;新增一条评估取消路由和 cancelled Run 状态值,前端按新状态渲染。
  • 评估 Task payload 的 retrieval_config 会包含 raise_on_error,由 evaluator 拆分后透传,不会泄漏给底层检索参数。
  • 建议合并前在有 pytest / Docker 的环境补跑新增单测,并执行一次真实 HTTP 取消负向验证。

- 评估链路强制检索 fail-fast:run_evaluation 写入 raise_on_error=true,
  evaluate_question 拆分开关后透传,避免作为普通检索参数泄漏。
- 查询失败语义归位:KnowledgeBaseManager.aquery 只透传 raise_on_error,
  不再捕获配置/实例/查询异常;Dify 与 Notion 在执行器层保留默认静默降级和严格上抛两种模式,
  Milvus 保持原生 fail-fast。
- 新增评估运行取消接口 POST /databases/{kb_id}/runs/{run_id}/cancel,
  使用知识库 manage 权限定位活跃 Durable Task 并复用通用取消;
  cancel_requested 投影为 Run 的 cancelled 状态,其余失败保持 failed。
- running Run 删除前拒绝,防止任务继续写入已删除的评估记录。
- Dataset 删除前同步生成任务终态,并拒绝 pending/running 状态,防止活跃生成任务继续写入。
- 前端补齐 cancelled 状态展示与取消按钮,取消后刷新任务中心和评估概览。
- 新增查询层回归测试与评估服务生成/取消/删除保护测试。

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